|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \page qt4-mainwindow.html |
|
44 \title The Qt 4 Main Window Classes |
|
45 |
|
46 \contentspage {What's New in Qt 4}{Home} |
|
47 \previouspage The Scribe Classes |
|
48 \nextpage The New Qt Designer |
|
49 |
|
50 Qt 4 introduces a new set of main window classes that supersede the |
|
51 Qt 3 main window classes, providing a more efficient implementation |
|
52 while remaining easy to use. |
|
53 |
|
54 \tableofcontents |
|
55 |
|
56 \section1 Overview of the Main Window Classes |
|
57 |
|
58 The main window-related classes have been redesigned to satisfy a |
|
59 number of requirements, addressing issues raised by our customers and |
|
60 internal developers. The aim of this redesign is to provide a more |
|
61 consistent and efficient framework for main window management. |
|
62 |
|
63 \section1 The Main Window Classes |
|
64 |
|
65 Qt 4 provides the following classes for managing main windows and |
|
66 associated user interface components: |
|
67 |
|
68 \list |
|
69 \o QMainWindow remains the central class around which applications |
|
70 can be built. The interface to this class has been simplified, and |
|
71 much of the functionality previously included in this class is now |
|
72 present in the companion QDockWidget and QToolBar classes. |
|
73 |
|
74 \o QDockWidget provides a widget that can be used to create |
|
75 detachable tool palettes or helper windows. Dock widgets keep track |
|
76 of their own properties, and they can be moved, closed, and floated |
|
77 as external windows. |
|
78 |
|
79 \o QToolBar provides a generic toolbar widget that can hold a |
|
80 number of different action-related widgets, such as buttons, |
|
81 drop-down menus, comboboxes, and spin boxes. The emphasis on a |
|
82 unified action model in Qt 4 means that toolbars cooperate well |
|
83 with menus and keyboard shortcuts. |
|
84 \endlist |
|
85 |
|
86 \section1 Example Code |
|
87 |
|
88 Using QMainWindow is straightforward. Generally, we subclass |
|
89 QMainWindow and set up menus, toolbars, and dock widgets inside |
|
90 the QMainWindow constructor. |
|
91 |
|
92 To add a menu bar to the main window, we simply create the menus, and |
|
93 add them to the main window's menu bar. Note that the |
|
94 QMainWindow::menuBar() function will automatically create the menu bar |
|
95 the first time it is called. You can also call |
|
96 QMainWindow::setMenuBar() to use a custom menu bar in the main window. |
|
97 |
|
98 \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 0 |
|
99 \dots |
|
100 \snippet examples/mainwindows/menus/mainwindow.cpp 5 |
|
101 \dots |
|
102 |
|
103 Once actions have been created, we can add them to the main window |
|
104 components. To begin with, we add them to the pop-up menus: |
|
105 |
|
106 \snippet examples/mainwindows/menus/mainwindow.cpp 10 |
|
107 \dots |
|
108 \snippet examples/mainwindows/menus/mainwindow.cpp 11 |
|
109 \dots |
|
110 |
|
111 The QToolBar and QMenu classes use Qt's action system to provide a |
|
112 consistent API. In the above code, some existing actions were added to |
|
113 the file menu with the QMenu::addAction() function. QToolBar also |
|
114 provides this function, making it easy to reuse actions in different |
|
115 parts of the main window. This avoids unnecessary duplication of work. |
|
116 |
|
117 We create a toolbar as a child of the main window, and add the desired |
|
118 actions to it: |
|
119 |
|
120 \snippet examples/mainwindows/sdi/mainwindow.cpp 0 |
|
121 \dots |
|
122 \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 1 |
|
123 |
|
124 In this example, the toolbar is restricted to the top and bottom |
|
125 toolbar areas of the main window, and is initially placed in the |
|
126 top tool bar area. We can see that the actions specified by \c |
|
127 newAct and \c openAct will be displayed both on the toolbar and in |
|
128 the file menu. |
|
129 |
|
130 QDockWidget is used in a similar way to QToolBar. We create a |
|
131 dock widget as a child of the main window, and add widgets as children |
|
132 of the dock widget: |
|
133 |
|
134 \snippet doc/src/snippets/dockwidgets/mainwindow.cpp 0 |
|
135 |
|
136 In this example, the dock widget can only be placed in the left and |
|
137 right dock areas, and it is initially placed in the left dock area. |
|
138 |
|
139 The QMainWindow API allows the programmer to customize which dock |
|
140 widget areas occupy the four corners of the dock widget area. If |
|
141 required, the default can be changed with the |
|
142 QMainWindow::setCorner() function: |
|
143 |
|
144 \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 2 |
|
145 |
|
146 The following diagram shows the configuration produced by the above code. |
|
147 Note that the left and right dock widgets will occupy the top and bottom |
|
148 corners of the main window in this layout. |
|
149 |
|
150 \image mainwindow-docks-example.png |
|
151 |
|
152 Once all of the main window components have been set up, the central widget |
|
153 is created and installed by using code similar to the following: |
|
154 |
|
155 \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 3 |
|
156 |
|
157 The central widget can be any subclass of QWidget. |
|
158 |
|
159 \section1 What's Changed since Qt 3? |
|
160 |
|
161 The main window classes in Qt 4 adds new functionality, mainly to |
|
162 the dock widgets and toolbars. We have also made changes to the |
|
163 design of the framework. |
|
164 |
|
165 Although the QMainWindow class in Qt 3 provided support for |
|
166 toolbars, dock widgets, and other standard user interface |
|
167 components, its design meant that these items were managed |
|
168 through a large number of QMainWindow member functions. In Qt 4, |
|
169 the QMainWindow class delegates many of the management tasks to |
|
170 QDockWidget and QToolBar (allowing more consistent behavior to be |
|
171 defined and implemented). |
|
172 |
|
173 The dock widget and toolbar classes are now separated into |
|
174 independent classes. (write some more here) |
|
175 |
|
176 (It is intended that these changes allow more consistent behavior |
|
177 to be defined and implemented (which? example). In |
|
178 response to feedback from customers, we hope to improve these classes |
|
179 even further.) |
|
180 |
|
181 \section2 New Functionality |
|
182 |
|
183 Dock widgets are animated when docking or |
|
184 detaching from a dock area. The dock areas will also adjust their |
|
185 size to show where the dock widget will dock when it hovers over |
|
186 it. This animation can be turned off with \c setAnimated(). |
|
187 |
|
188 By default, dock widgets are added to the dock areas in a single |
|
189 row. By setting nesting enabled with \c setDockNestingEnabled(), |
|
190 the widgets can be added both vertically and horizontally. |
|
191 |
|
192 Two dock widgets can occupy the same space in a dock area. The user |
|
193 can then choose which widget that is visible with a tab bar that |
|
194 is located below the widgets. The QMainWindow::tabifyDockWidget() |
|
195 joins two tab widgets in such a tabbed dock area. (revise the |
|
196 entire paragraph) |
|
197 |
|
198 \section2 Independent QDockWidget And QToolBar Classes |
|
199 |
|
200 Toolbar and dock window functionality is provided by two independent |
|
201 classes: QToolBar and QDockWidget. Toolbars and dock widgets |
|
202 reside in separate areas, with toolbars outside the dock widget |
|
203 area. This behavior differs from the Qt 3 behavior, where |
|
204 QToolBar inherited functionality from QDockWidget, and both types of |
|
205 component shared the same areas. The result is a more consistent |
|
206 and predictable experience for users. Toolbars and dock widgets |
|
207 provide feedback while being dragged into their new positions. |
|
208 |
|
209 \image mainwindow-docks.png |
|
210 |
|
211 The diagram above shows the layout of a main window that contains both |
|
212 toolbars and dock widgets. Each corner area can be used by either |
|
213 of the adjacent dock widget areas, allowing dock widget behavior and |
|
214 main window layout to be specified precisely. |
|
215 |
|
216 Toolbars and dock widgets are child widgets of the main window. They |
|
217 are no longer reparented into a dock area widget by the main window. |
|
218 Instead, layouts are used to manage the placement of toolbars and dock |
|
219 widgets. One consequence is that the old QDockArea class is no |
|
220 longer required in Qt 4. |
|
221 |
|
222 \section2 Code Change Examples |
|
223 |
|
224 QMainWindow retains the menuBar() function, but menus are always |
|
225 constructed using QAction objects. All kinds of menus are |
|
226 constructed using the general QMenu class. |
|
227 |
|
228 Qt 3: |
|
229 \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 4 |
|
230 Qt 4: |
|
231 \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 5 |
|
232 |
|
233 Toolbars follow the same pattern as menus, with the new, more |
|
234 consistent behavior: |
|
235 |
|
236 Qt 3: |
|
237 \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 6 |
|
238 Qt 4: |
|
239 \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 7 |
|
240 |
|
241 The behavior of dock widgets is now configured through the member |
|
242 functions of QDockWidget. For example, compare the old and new ways |
|
243 of creating a dock widget in the dock area on the left hand side of the |
|
244 main window. |
|
245 |
|
246 In Qt 3: |
|
247 \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 8 |
|
248 In Qt 4: |
|
249 \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 9 |
|
250 */ |