1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
<?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" />
<!-- qt4-mainwindow.qdoc -->
<title>Qt 4.8: The Qt 4 Main Window Classes</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="content">
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
</div>
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>The Qt 4 Main Window Classes</li>
</ul>
</div>
</div>
<div class="content mainContent">
<link rel="prev" href="qt4-scribe.html" />
<link rel="next" href="qt4-designer.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="qt4-scribe.html">The Scribe Classes</a>
<a class="nextPage" href="qt4-designer.html">The New Qt Designer</a>
</p><p/>
<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>
<li class="level1"><a href="#what-s-changed-since-qt-3">What's Changed since Qt 3?</a></li>
<li class="level2"><a href="#new-functionality">New Functionality</a></li>
<li class="level2"><a href="#independent-qdockwidget-and-qtoolbar-classes">Independent QDockWidget And QToolBar Classes</a></li>
<li class="level2"><a href="#code-change-examples">Code Change Examples</a></li>
</ul>
</div>
<h1 class="title">The Qt 4 Main Window Classes</h1>
<span class="subtitle"></span>
<!-- $$$qt4-mainwindow.html-description -->
<div class="descr"> <a name="details"></a>
<p>Qt 4 introduces a new set of main window classes that supersede the Qt 3 main window classes, providing a more efficient implementation while remaining easy to use.</p>
<a name="overview-of-the-main-window-classes"></a>
<h2>Overview of the Main Window Classes</h2>
<p>The main window-related classes have been redesigned to satisfy a number of requirements, addressing issues raised by our customers and internal developers. The aim of this redesign is to provide a more consistent and efficient framework for main window management.</p>
<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>
<a name="what-s-changed-since-qt-3"></a>
<h2>What's Changed since Qt 3?</h2>
<p>The main window classes in Qt 4 adds new functionality, mainly to the dock widgets and toolbars. We have also made changes to the design of the framework.</p>
<p>Although the <a href="qmainwindow.html">QMainWindow</a> class in Qt 3 provided support for toolbars, dock widgets, and other standard user interface components, its design meant that these items were managed through a large number of <a href="qmainwindow.html">QMainWindow</a> member functions. In Qt 4, the <a href="qmainwindow.html">QMainWindow</a> class delegates many of the management tasks to <a href="qdockwidget.html">QDockWidget</a> and <a href="qtoolbar.html">QToolBar</a> (allowing more consistent behavior to be defined and implemented).</p>
<p>The dock widget and toolbar classes are now separated into independent classes. (write some more here)</p>
<p>(It is intended that these changes allow more consistent behavior to be defined and implemented (which? example). In response to feedback from customers, we hope to improve these classes even further.)</p>
<a name="new-functionality"></a>
<h3>New Functionality</h3>
<p>Dock widgets are animated when docking or detaching from a dock area. The dock areas will also adjust their size to show where the dock widget will dock when it hovers over it. This animation can be turned off with <tt>setAnimated()</tt>.</p>
<p>By default, dock widgets are added to the dock areas in a single row. By setting nesting enabled with <tt>setDockNestingEnabled()</tt>, the widgets can be added both vertically and horizontally.</p>
<p>Two dock widgets can occupy the same space in a dock area. The user can then choose which widget that is visible with a tab bar that is located below the widgets. The <a href="qmainwindow.html#tabifyDockWidget">QMainWindow::tabifyDockWidget</a>() joins two tab widgets in such a tabbed dock area. (revise the entire paragraph)</p>
<a name="independent-qdockwidget-and-qtoolbar-classes"></a>
<h3>Independent QDockWidget And QToolBar Classes</h3>
<p>Toolbar and dock window functionality is provided by two independent classes: <a href="qtoolbar.html">QToolBar</a> and <a href="qdockwidget.html">QDockWidget</a>. Toolbars and dock widgets reside in separate areas, with toolbars outside the dock widget area. This behavior differs from the Qt 3 behavior, where <a href="qtoolbar.html">QToolBar</a> inherited functionality from <a href="qdockwidget.html">QDockWidget</a>, and both types of component shared the same areas. The result is a more consistent and predictable experience for users. Toolbars and dock widgets provide feedback while being dragged into their new positions.</p>
<p class="centerAlign"><img src="images/mainwindow-docks.png" alt="" /></p><p>The diagram above shows the layout of a main window that contains both toolbars and dock widgets. Each corner area can be used by either of the adjacent dock widget areas, allowing dock widget behavior and main window layout to be specified precisely.</p>
<p>Toolbars and dock widgets are child widgets of the main window. They are no longer reparented into a dock area widget by the main window. Instead, layouts are used to manage the placement of toolbars and dock widgets. One consequence is that the old <a href="porting4.html#qdockarea">QDockArea</a> class is no longer required in Qt 4.</p>
<a name="code-change-examples"></a>
<h3>Code Change Examples</h3>
<p><a href="qmainwindow.html">QMainWindow</a> retains the menuBar() function, but menus are always constructed using <a href="qaction.html">QAction</a> objects. All kinds of menus are constructed using the general <a href="qmenu.html">QMenu</a> class.</p>
<p>Qt 3:</p>
<pre class="cpp"> <span class="type">QPopupMenu</span> <span class="operator">*</span>fileMenu <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QPopupMenu</span>(<span class="keyword">this</span>);
openAction<span class="operator">-</span><span class="operator">></span>addTo(fileMenu);
saveAction<span class="operator">-</span><span class="operator">></span>addTo(fileMenu);
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
menuBar()<span class="operator">-</span><span class="operator">></span>insertItem(tr(<span class="string">"&File"</span>)<span class="operator">,</span> fileMenu);</pre>
<p>Qt 4:</p>
<pre class="cpp"> <span class="type"><a href="qmenu.html">QMenu</a></span> <span class="operator">*</span>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(openAction);
fileMenu<span class="operator">-</span><span class="operator">></span>addAction(saveAction);
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span></pre>
<p>Toolbars follow the same pattern as menus, with the new, more consistent behavior:</p>
<p>Qt 3:</p>
<pre class="cpp"> <span class="type"><a href="qtoolbar.html">QToolBar</a></span> <span class="operator">*</span>fileTools <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qtoolbar.html">QToolBar</a></span>(<span class="keyword">this</span><span class="operator">,</span> <span class="string">"file toolbar"</span>);
openAction<span class="operator">-</span><span class="operator">></span>addTo(fileTools);
saveAction<span class="operator">-</span><span class="operator">></span>addTo(fileTools);
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span></pre>
<p>Qt 4:</p>
<pre class="cpp"> <span class="type"><a href="qtoolbar.html">QToolBar</a></span> <span class="operator">*</span>fileTools <span class="operator">=</span> addToolBar(tr(<span class="string">"File Tool Bar"</span>));
fileTools<span class="operator">-</span><span class="operator">></span>addAction(openAction);
fileTools<span class="operator">-</span><span class="operator">></span>addAction(saveAction);
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span></pre>
<p>The behavior of dock widgets is now configured through the member functions of <a href="qdockwidget.html">QDockWidget</a>. For example, compare the old and new ways of creating a dock widget in the dock area on the left hand side of the main window.</p>
<p>In Qt 3:</p>
<pre class="cpp"> <span class="type"><a href="qdockwidget.html">QDockWidget</a></span> <span class="operator">*</span>dockWidget <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qdockwidget.html">QDockWidget</a></span>(<span class="keyword">this</span>);
mainWin<span class="operator">-</span><span class="operator">></span>moveDockWidget(dockWidget<span class="operator">,</span> <span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>DockLeft);</pre>
<p>In Qt 4:</p>
<pre class="cpp"> <span class="type"><a href="qdockwidget.html">QDockWidget</a></span> <span class="operator">*</span>dockWidget <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qdockwidget.html">QDockWidget</a></span>(mainWindow);
mainWindow<span class="operator">-</span><span class="operator">></span>addDockWidget(<span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>LeftDockWidgetArea<span class="operator">,</span> dockWidget);</pre>
</div>
<!-- @@@qt4-mainwindow.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="qt4-scribe.html">The Scribe Classes</a>
<a class="nextPage" href="qt4-designer.html">The New Qt Designer</a>
</p>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2012 Nokia Corporation 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>
Nokia, Qt and their respective logos are trademarks of Nokia Corporation
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>
</body>
</html>
|
