1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
10 ** GNU Free Documentation License
11 ** Alternatively, this file may be used under the terms of the GNU Free
12 ** Documentation License version 1.3 as published by the Free Software
13 ** Foundation and appearing in the file included in the packaging of
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \group mainwindow-classes
30 \title Main Window and Related Classes
34 \page application-windows.html
35 \title Window and Dialog Widgets
36 \brief Windows and Dialogs in Qt.
37 \ingroup qt-gui-concepts
39 A \l{Widgets Tutorial}{widget} that is not embedded in a parent widget is called a window.
40 (Usually, windows have a frame and a title bar, although it is also possible to create
41 windows without such decoration using suitable window flags). In Qt, QMainWindow
42 and the various subclasses of QDialog are the most common window types.
44 In applications, windows provide the screen space upon which the user
45 interface is built. Windows separate applications visually from each other
46 and usually provide a window decoration that allows the user to resize and
47 position the applications according to his preferences. Windows are typically
48 integrated into the desktop environment and to some degree managed by the
49 window management system that the desktop environment provides. For instance,
50 selected windows of an application are represented in the task bar.
52 \section1 Primary and Secondary Windows
54 Any QWidget that has no parent will become a window, and will on most platforms
55 be listed in the desktop's task bar. This is usually only wanted for one
56 window in the application, the \e{primary window}.
58 In addition, a QWidget that has a parent can become a window by setting the
59 \l{Qt::WindowType}{Qt::WA_Window} flag. Depending on the window management system
60 such \e{secondary windows} are usually stacked on top of their respective parent
61 window, and not have a task bar entry of their own.
63 The QMainWindow and the QDialog classes set the Qt::WA_Window flag in their
64 constructor, as they are designed to be used as windows and provide facilities
65 that are not wanted for child widgets.
67 \section1 Main Windows and Dialogs
69 The \l{Application Main Window} provides the framework for building the
70 application's main user interface, and are created by subclassing QMainWindow.
71 QMainWindow has its own layout to which you can add a \l{QMenuBar}{menu bar},
72 \l{QToolBar}{tool bars}, \l{QDockWidget}{dockable widgets} and a
73 \l{QStatusBar}{status bar}. The center area can be occupied by any kind of
76 \l{Dialog Windows} are used as secondary windows that present the user with
77 options and choices. Dialogs are created by subclassing QDialog and using
78 \l{Widgets and Layouts}{widgets and layouts} to implement the user interface.
79 In addition, Qt provides a number of ready-made standard dialogs that can be
80 used for standard tasks like file or font selection.
82 Both main windows and dialogs can be created with \QD, Qt's visual design tool.
83 Using \QD is a lot faster than hand-coding, and makes it easy to test different
84 design ideas. Creating designs visually and reading the code generated by
85 \l{uic} is a great way to learn Qt!
87 \keyword window geometry
88 \section1 Window Geometry
90 QWidget provides several functions that deal with a widget's
91 geometry. Some of these functions operate on the pure client area
92 (i.e. the window excluding the window frame), others include the
93 window frame. The differentiation is done in a way that covers the
94 most common usage transparently.
97 \o \bold{Including the window frame:}
98 \l{QWidget::x()}{x()},
99 \l{QWidget::y()}{y()},
100 \l{QWidget::frameGeometry()}{frameGeometry()},
101 \l{QWidget::pos()}{pos()}, and
102 \l{QWidget::move()}{move()}.
103 \o \bold{Excluding the window frame:}
104 \l{QWidget::geometry()}{geometry()},
105 \l{QWidget::width()}{width()},
106 \l{QWidget::height()}{height()},
107 \l{QWidget::rect()}{rect()}, and
108 \l{QWidget::size()}{size()}.
111 Note that the distinction only matters for decorated top-level
112 widgets. For all child widgets, the frame geometry is equal to the
113 widget's client geometry.
115 This diagram shows most of the functions in use:
116 \img geometry.png Geometry diagram
118 \section2 X11 Peculiarities
120 On X11, a window does not have a frame until the window manager
121 decorates it. This happens asynchronously at some point in time
122 after calling QWidget::show() and the first paint event the
123 window receives, or it does not happen at all. Bear in mind that
124 X11 is policy-free (others call it flexible). Thus you cannot
125 make any safe assumption about the decoration frame your window
126 will get. Basic rule: There's always one user who uses a window
127 manager that breaks your assumption, and who will complain to
130 Furthermore, a toolkit cannot simply place windows on the screen. All
131 Qt can do is to send certain hints to the window manager. The window
132 manager, a separate process, may either obey, ignore or misunderstand
133 them. Due to the partially unclear Inter-Client Communication
134 Conventions Manual (ICCCM), window placement is handled quite
135 differently in existing window managers.
137 X11 provides no standard or easy way to get the frame geometry
138 once the window is decorated. Qt solves this problem with nifty
139 heuristics and clever code that works on a wide range of window
140 managers that exist today. Don't be surprised if you find one
141 where QWidget::frameGeometry() returns wrong results though.
143 Nor does X11 provide a way to maximize a window.
144 QWidget::showMaximized() has to emulate the feature. Its result
145 depends on the result of QWidget::frameGeometry() and the
146 capability of the window manager to do proper window placement,
147 neither of which can be guaranteed.
151 \page mainwindow.html
152 \title Application Main Window
153 \ingroup qt-gui-concepts
154 \brief Creating the application window.
158 \section1 Overview of the Main Window Classes
160 These classes provide everything you need for a typical modern main
161 application window, like the main window itself, menu and tool bars,
164 \annotatedlist mainwindow-classes
166 \section1 The Main Window Classes
168 Qt 4 provides the following classes for managing main windows and
169 associated user interface components:
172 \o QMainWindow remains the central class around which applications
173 can be built. The interface to this class has been simplified, and
174 much of the functionality previously included in this class is now
175 present in the companion QDockWidget and QToolBar classes.
177 \o QDockWidget provides a widget that can be used to create
178 detachable tool palettes or helper windows. Dock widgets keep track
179 of their own properties, and they can be moved, closed, and floated
182 \o QToolBar provides a generic toolbar widget that can hold a
183 number of different action-related widgets, such as buttons,
184 drop-down menus, comboboxes, and spin boxes. The emphasis on a
185 unified action model in Qt 4 means that toolbars cooperate well
186 with menus and keyboard shortcuts.
189 \section1 Example Code
191 Using QMainWindow is straightforward. Generally, we subclass
192 QMainWindow and set up menus, toolbars, and dock widgets inside
193 the QMainWindow constructor.
195 To add a menu bar to the main window, we simply create the menus, and
196 add them to the main window's menu bar. Note that the
197 QMainWindow::menuBar() function will automatically create the menu bar
198 the first time it is called. You can also call
199 QMainWindow::setMenuBar() to use a custom menu bar in the main window.
201 \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 0
203 \snippet examples/mainwindows/menus/mainwindow.cpp 5
206 Once actions have been created, we can add them to the main window
207 components. To begin with, we add them to the pop-up menus:
209 \snippet examples/mainwindows/menus/mainwindow.cpp 10
211 \snippet examples/mainwindows/menus/mainwindow.cpp 11
214 The QToolBar and QMenu classes use Qt's action system to provide a
215 consistent API. In the above code, some existing actions were added to
216 the file menu with the QMenu::addAction() function. QToolBar also
217 provides this function, making it easy to reuse actions in different
218 parts of the main window. This avoids unnecessary duplication of work.
220 We create a toolbar as a child of the main window, and add the desired
223 \snippet examples/mainwindows/sdi/mainwindow.cpp 0
225 \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 1
227 In this example, the toolbar is restricted to the top and bottom
228 toolbar areas of the main window, and is initially placed in the
229 top tool bar area. We can see that the actions specified by \c
230 newAct and \c openAct will be displayed both on the toolbar and in
233 QDockWidget is used in a similar way to QToolBar. We create a
234 dock widget as a child of the main window, and add widgets as children
237 \snippet doc/src/snippets/dockwidgets/mainwindow.cpp 0
239 In this example, the dock widget can only be placed in the left and
240 right dock areas, and it is initially placed in the left dock area.
242 The QMainWindow API allows the programmer to customize which dock
243 widget areas occupy the four corners of the dock widget area. If
244 required, the default can be changed with the
245 QMainWindow::setCorner() function:
247 \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 2
249 The following diagram shows the configuration produced by the above code.
250 Note that the left and right dock widgets will occupy the top and bottom
251 corners of the main window in this layout.
253 \image mainwindow-docks-example.png
255 Once all of the main window components have been set up, the central widget
256 is created and installed by using code similar to the following:
258 \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 3
260 The central widget can be any subclass of QWidget.