source: trunk/doc/src/qt4-mainwindow.qdoc@ 477

Last change on this file since 477 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 10.5 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information ([email protected])
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at [email protected].
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