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