<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- mainwindow.qdoc -->
<title>Qt 4.8: Application Main Window</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>Application Main Window</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#overview-of-the-main-window-classes">Overview of the Main Window Classes</a></li>
<li class="level1"><a href="#the-main-window-classes">The Main Window Classes</a></li>
<li class="level1"><a href="#example-code">Example Code</a></li>
</ul>
</div>
<h1 class="title">Application Main Window</h1>
<span class="subtitle"></span>
<!-- $$$mainwindow.html-description -->
<div class="descr"> <a name="details"></a>
<a name="overview-of-the-main-window-classes"></a>
<h2>Overview of the Main Window Classes</h2>
<p>These classes provide everything you need for a typical modern main application window, like the main window itself, menu and tool bars, a status bar, etc.</p>
<table class="annotated">
<tr class="odd topAlign"><td class="tblName"><p><a href="qaction.html">QAction</a></p></td><td class="tblDescr"><p>Abstract user interface action that can be inserted into widgets</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qactiongroup.html">QActionGroup</a></p></td><td class="tblDescr"><p>Groups actions together</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qdockwidget.html">QDockWidget</a></p></td><td class="tblDescr"><p>Widget that can be docked inside a QMainWindow or floated as a top-level window on the desktop</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qmainwindow.html">QMainWindow</a></p></td><td class="tblDescr"><p>Main application window</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qmdiarea.html">QMdiArea</a></p></td><td class="tblDescr"><p>Area in which MDI windows are displayed</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qmdisubwindow.html">QMdiSubWindow</a></p></td><td class="tblDescr"><p>Subwindow class for QMdiArea</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qmenu.html">QMenu</a></p></td><td class="tblDescr"><p>Menu widget for use in menu bars, context menus, and other popup menus</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qmenubar.html">QMenuBar</a></p></td><td class="tblDescr"><p>Horizontal menu bar</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qsizegrip.html">QSizeGrip</a></p></td><td class="tblDescr"><p>Resize handle for resizing top-level windows</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qstatusbar.html">QStatusBar</a></p></td><td class="tblDescr"><p>Horizontal bar suitable for presenting status information</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qtoolbar.html">QToolBar</a></p></td><td class="tblDescr"><p>Movable panel that contains a set of controls</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qwidgetaction.html">QWidgetAction</a></p></td><td class="tblDescr"><p>Extends QAction by an interface for inserting custom widgets into action based containers, such as toolbars</p></td></tr>
</table>
<a name="the-main-window-classes"></a>
<h2>The Main Window Classes</h2>
<p>Qt 4 provides the following classes for managing main windows and associated user interface components:</p>
<ul>
<li><a href="qmainwindow.html">QMainWindow</a> remains the central class around which applications can be built. The interface to this class has been simplified, and much of the functionality previously included in this class is now present in the companion <a href="qdockwidget.html">QDockWidget</a> and <a href="qtoolbar.html">QToolBar</a> classes.</li>
<li><a href="qdockwidget.html">QDockWidget</a> provides a widget that can be used to create detachable tool palettes or helper windows. Dock widgets keep track of their own properties, and they can be moved, closed, and floated as external windows.</li>
<li><a href="qtoolbar.html">QToolBar</a> provides a generic toolbar widget that can hold a number of different action-related widgets, such as buttons, drop-down menus, comboboxes, and spin boxes. The emphasis on a unified action model in Qt 4 means that toolbars cooperate well with menus and keyboard shortcuts.</li>
</ul>
<a name="example-code"></a>
<h2>Example Code</h2>
<p>Using <a href="qmainwindow.html">QMainWindow</a> is straightforward. Generally, we subclass <a href="qmainwindow.html">QMainWindow</a> and set up menus, toolbars, and dock widgets inside the <a href="qmainwindow.html">QMainWindow</a> constructor.</p>
<p>To add a menu bar to the main window, we simply create the menus, and add them to the main window's menu bar. Note that the <a href="qmainwindow.html#menuBar">QMainWindow::menuBar</a>() function will automatically create the menu bar the first time it is called. You can also call <a href="qmainwindow.html#setMenuBar">QMainWindow::setMenuBar</a>() to use a custom menu bar in the main window.</p>
<pre class="cpp"> MainWindow<span class="operator">::</span>MainWindow(<span class="type"><a href="qwidget.html">QWidget</a></span> <span class="operator">*</span>parent)
: <span class="type"><a href="qmainwindow.html">QMainWindow</a></span>(parent)
{
...
newAct <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qaction.html">QAction</a></span>(tr(<span class="string">"&New"</span>)<span class="operator">,</span> <span class="keyword">this</span>);
newAct<span class="operator">-</span><span class="operator">></span>setShortcuts(<span class="type"><a href="qkeysequence.html">QKeySequence</a></span><span class="operator">::</span>New);
newAct<span class="operator">-</span><span class="operator">></span>setStatusTip(tr(<span class="string">"Create a new file"</span>));
connect(newAct<span class="operator">,</span> SIGNAL(triggered())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(newFile()));
openAct <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qaction.html">QAction</a></span>(tr(<span class="string">"&Open..."</span>)<span class="operator">,</span> <span class="keyword">this</span>);
openAct<span class="operator">-</span><span class="operator">></span>setShortcuts(<span class="type"><a href="qkeysequence.html">QKeySequence</a></span><span class="operator">::</span>Open);
openAct<span class="operator">-</span><span class="operator">></span>setStatusTip(tr(<span class="string">"Open an existing file"</span>));
connect(openAct<span class="operator">,</span> SIGNAL(triggered())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(open()));
...</pre>
<p>Once actions have been created, we can add them to the main window components. To begin with, we add them to the pop-up menus:</p>
<pre class="cpp"> fileMenu <span class="operator">=</span> menuBar()<span class="operator">-</span><span class="operator">></span>addMenu(tr(<span class="string">"&File"</span>));
fileMenu<span class="operator">-</span><span class="operator">></span>addAction(newAct);
fileMenu<span class="operator">-</span><span class="operator">></span>addAction(openAct);
...
fileMenu<span class="operator">-</span><span class="operator">></span>addSeparator();
...</pre>
<p>The <a href="qtoolbar.html">QToolBar</a> and <a href="qmenu.html">QMenu</a> classes use Qt's action system to provide a consistent API. In the above code, some existing actions were added to the file menu with the <a href="qmenu.html#addAction">QMenu::addAction</a>() function. <a href="qtoolbar.html">QToolBar</a> also provides this function, making it easy to reuse actions in different parts of the main window. This avoids unnecessary duplication of work.</p>
<p>We create a toolbar as a child of the main window, and add the desired actions to it:</p>
<pre class="cpp"> fileToolBar <span class="operator">=</span> addToolBar(tr(<span class="string">"File"</span>));
fileToolBar<span class="operator">-</span><span class="operator">></span>addAction(newAct);
fileToolBar<span class="operator">-</span><span class="operator">></span>addAction(openAct);
...
fileToolbar<span class="operator">-</span><span class="operator">></span>setAllowedAreas(<span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>TopToolBarArea <span class="operator">|</span> <span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>BottomToolBarArea);
addToolBar(<span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>TopToolBarArea<span class="operator">,</span> fileToolbar);</pre>
<p>In this example, the toolbar is restricted to the top and bottom toolbar areas of the main window, and is initially placed in the top tool bar area. We can see that the actions specified by <tt>newAct</tt> and <tt>openAct</tt> will be displayed both on the toolbar and in the file menu.</p>
<p><a href="qdockwidget.html">QDockWidget</a> is used in a similar way to <a href="qtoolbar.html">QToolBar</a>. We create a dock widget as a child of the main window, and add widgets as children of the dock widget:</p>
<pre class="cpp"> contentsWindow <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qdockwidget.html">QDockWidget</a></span>(tr(<span class="string">"Table of Contents"</span>)<span class="operator">,</span> <span class="keyword">this</span>);
contentsWindow<span class="operator">-</span><span class="operator">></span>setAllowedAreas(<span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>LeftDockWidgetArea
<span class="operator">|</span> <span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>RightDockWidgetArea);
addDockWidget(<span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>LeftDockWidgetArea<span class="operator">,</span> contentsWindow);
headingList <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qlistwidget.html">QListWidget</a></span>(contentsWindow);
contentsWindow<span class="operator">-</span><span class="operator">></span>setWidget(headingList);</pre>
<p>In this example, the dock widget can only be placed in the left and right dock areas, and it is initially placed in the left dock area.</p>
<p>The <a href="qmainwindow.html">QMainWindow</a> API allows the programmer to customize which dock widget areas occupy the four corners of the dock widget area. If required, the default can be changed with the <a href="qmainwindow.html#setCorner">QMainWindow::setCorner</a>() function:</p>
<pre class="cpp"> setCorner(<span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>TopLeftCorner<span class="operator">,</span> <span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>LeftDockWidgetArea);
setCorner(<span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>BottomLeftCorner<span class="operator">,</span> <span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>LeftDockWidgetArea);
setCorner(<span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>TopRightCorner<span class="operator">,</span> <span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>RightDockWidgetArea);
setCorner(<span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>BottomRightCorner<span class="operator">,</span> <span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>RightDockWidgetArea);</pre>
<p>The following diagram shows the configuration produced by the above code. Note that the left and right dock widgets will occupy the top and bottom corners of the main window in this layout.</p>
<p class="centerAlign"><img src="images/mainwindow-docks-example.png" alt="" /></p><p>Once all of the main window components have been set up, the central widget is created and installed by using code similar to the following:</p>
<pre class="cpp"> <span class="type"><a href="qwidget.html">QWidget</a></span> <span class="operator">*</span>centralWidget <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qwidget.html">QWidget</a></span>(<span class="keyword">this</span>);
setCentralWidget(centralWidget);</pre>
<p>The central widget can be any subclass of <a href="qwidget.html">QWidget</a>.</p>
</div>
<!-- @@@mainwindow.html -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Digia, Qt and their respective logos are trademarks of Digia Plc
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
