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
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
|
/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights. These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qt4-mainwindow.html
\title The Qt 4 Main Window Classes
\contentspage {What's New in Qt 4}{Home}
\previouspage The Scribe Classes
\nextpage The New Qt Designer
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.
\tableofcontents
\section1 Overview of the Main Window Classes
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.
\section1 The Main Window Classes
Qt 4 provides the following classes for managing main windows and
associated user interface components:
\list
\o QMainWindow 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 QDockWidget and QToolBar classes.
\o QDockWidget 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.
\o QToolBar 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.
\endlist
\section1 Example Code
Using QMainWindow is straightforward. Generally, we subclass
QMainWindow and set up menus, toolbars, and dock widgets inside
the QMainWindow constructor.
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
QMainWindow::menuBar() function will automatically create the menu bar
the first time it is called. You can also call
QMainWindow::setMenuBar() to use a custom menu bar in the main window.
\snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 0
\dots
\snippet examples/mainwindows/menus/mainwindow.cpp 5
\dots
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:
\snippet examples/mainwindows/menus/mainwindow.cpp 10
\dots
\snippet examples/mainwindows/menus/mainwindow.cpp 11
\dots
The QToolBar and QMenu 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 QMenu::addAction() function. QToolBar also
provides this function, making it easy to reuse actions in different
parts of the main window. This avoids unnecessary duplication of work.
We create a toolbar as a child of the main window, and add the desired
actions to it:
\snippet examples/mainwindows/sdi/mainwindow.cpp 0
\dots
\snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 1
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 \c
newAct and \c openAct will be displayed both on the toolbar and in
the file menu.
QDockWidget is used in a similar way to QToolBar. We create a
dock widget as a child of the main window, and add widgets as children
of the dock widget:
\snippet doc/src/snippets/dockwidgets/mainwindow.cpp 0
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.
The QMainWindow 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
QMainWindow::setCorner() function:
\snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 2
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.
\image mainwindow-docks-example.png
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:
\snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 3
The central widget can be any subclass of QWidget.
\section1 What's Changed since Qt 3?
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.
Although the QMainWindow 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 QMainWindow member functions. In Qt 4,
the QMainWindow class delegates many of the management tasks to
QDockWidget and QToolBar (allowing more consistent behavior to be
defined and implemented).
The dock widget and toolbar classes are now separated into
independent classes. (write some more here)
(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.)
\section2 New Functionality
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 \c setAnimated().
By default, dock widgets are added to the dock areas in a single
row. By setting nesting enabled with \c setDockNestingEnabled(),
the widgets can be added both vertically and horizontally.
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 QMainWindow::tabifyDockWidget()
joins two tab widgets in such a tabbed dock area. (revise the
entire paragraph)
\section2 Independent QDockWidget And QToolBar Classes
Toolbar and dock window functionality is provided by two independent
classes: QToolBar and QDockWidget. Toolbars and dock widgets
reside in separate areas, with toolbars outside the dock widget
area. This behavior differs from the Qt 3 behavior, where
QToolBar inherited functionality from QDockWidget, 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.
\image mainwindow-docks.png
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.
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 QDockArea class is no
longer required in Qt 4.
\section2 Code Change Examples
QMainWindow retains the menuBar() function, but menus are always
constructed using QAction objects. All kinds of menus are
constructed using the general QMenu class.
Qt 3:
\snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 4
Qt 4:
\snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 5
Toolbars follow the same pattern as menus, with the new, more
consistent behavior:
Qt 3:
\snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 6
Qt 4:
\snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 7
The behavior of dock widgets is now configured through the member
functions of QDockWidget. 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.
In Qt 3:
\snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 8
In Qt 4:
\snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 9
*/
|
