1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
4 \page application-windows.html
5 \title Window and Dialog Widgets
6 \brief Windows and Dialogs in Qt.
7 \ingroup qt-gui-concepts
9 A \l{Widgets Tutorial}{widget} that is not embedded in a parent widget is
10 called a window. Usually, windows have a frame and a title bar, although it
11 is also possible to create windows without such decoration using suitable
12 window flags. In Qt, QMainWindow and the various subclasses of QDialog are
13 the most common window types.
15 In applications, windows provide the screen space upon which the user
16 interface is built. Windows separate applications visually from each other
17 and usually provide a window decoration that allows you to resize and
18 position the applications according to your preferences. Windows are
19 typically integrated into the desktop environment and to some degree managed
20 by the window management system that the desktop environment provides. For
21 instance, selected windows of an application are represented in the task
24 \section1 Primary and Secondary Windows
26 Any QWidget that has no parent will become a window, and will on most platforms
27 be listed in the desktop's task bar. This is usually only wanted for one
28 window in the application, the \e{primary window}.
30 In addition, a QWidget that has a parent can become a window by setting the
31 Qt::Window flag. Depending on the window management system
32 such \e{secondary windows} are usually stacked on top of their respective
33 parent window and do not have a task bar entry of their own.
35 The QMainWindow class sets the Qt::Window flag in its constructor,
36 as it is designed to be used as a window and provides facilities that are
37 not wanted for child widgets.
39 \section1 Main Windows and Dialogs
41 The \l{Application Main Window} provides the framework for building the
42 application's main user interface and are created by subclassing
44 QMainWindow has its own layout to which you can add a \l{QMenuBar}{menu bar},
45 \l{QToolBar}{tool bars}, \l{QDockWidget}{dockable widgets} and a
46 \l{QStatusBar}{status bar}. The center area can be occupied by any kind of
49 \l{Dialog Windows} are used as secondary windows that present you with
50 options and choices. Dialogs are created by subclassing QDialog and using
51 \l{Widgets and Layouts}{widgets and layouts} to implement the user interface.
52 In addition, Qt provides a number of ready-made standard dialogs that can be
53 used for standard tasks like file or font selection.
55 Both main windows and dialogs can be created with \QD, Qt's visual design tool.
56 Using \QD is a lot faster than hand-coding, and makes it easy to test different
57 design ideas. Creating designs visually and reading the code generated by
58 \l{uic} is a great way to learn Qt!
60 \target window geometry
61 \section1 Window Geometry
63 QWidget provides several functions that deal with a widget's
64 geometry. Some of these functions operate on the pure client area
65 (that is, the window excluding the window frame), others include the
66 window frame. QWidget differentiates in a way that covers the
67 most common usage transparently.
70 \li \b{Including the window frame:}
71 \l{QWidget::x()}{x()},
72 \l{QWidget::y()}{y()},
73 \l{QWidget::frameGeometry()}{frameGeometry()},
74 \l{QWidget::pos()}{pos()}, and
75 \l{QWidget::move()}{move()}.
76 \li \b{Excluding the window frame:}
77 \l{QWidget::geometry()}{geometry()},
78 \l{QWidget::width()}{width()},
79 \l{QWidget::height()}{height()},
80 \l{QWidget::rect()}{rect()}, and
81 \l{QWidget::size()}{size()}.
84 Note that the distinction only matters for decorated top-level
85 widgets. For all child widgets, the frame geometry is equal to the
86 widget's client geometry.
88 This diagram shows most of the functions in use:
89 \image geometry.png Geometry diagram
91 \section2 X11 Peculiarities
93 On X11, a window does not have a frame until the window manager
94 decorates it. This happens asynchronously at some point in time
95 after calling QWidget::show() and the first paint event the
96 window receives, or it does not happen at all. Bear in mind that
97 X11 is policy-free (others call it flexible). Thus you cannot
98 make any safe assumption about the decoration frame your window
99 will get. Basic rule: There's always one user who uses a window
100 manager that breaks your assumption, and who will complain to
103 Furthermore, a toolkit cannot simply place windows on the screen. All
104 Qt can do is to send certain hints to the window manager. The window
105 manager, a separate process, may either obey, ignore, or misunderstand
106 them. Due to the partially unclear Inter-Client Communication
107 Conventions Manual (ICCCM), window placement is handled
108 differently in existing window managers.
110 X11 provides no standard or easy way to get the frame geometry
111 once the window is decorated. Qt solves this problem with nifty
112 heuristics and clever code that works on a wide range of window
113 managers that exist today. Don't be surprised if you find one
114 where QWidget::frameGeometry() returns wrong results though.
116 Nor does X11 provide a way to maximize a window.
117 QWidget::showMaximized() has to emulate the feature. Its result
118 depends on the result of QWidget::frameGeometry() and the
119 capability of the window manager to do proper window placement,
120 neither of which can be guaranteed.
122 \section2 Wayland Peculiarities
124 On Wayland, programmatically setting or getting the position of a top-level window from the
125 client-side is typically not supported. Technically speaking, it depends on the shell
126 interface. For typical desktop compositors, however, the default shell interface will be
127 \c{XDG Shell}, which does not support manual positioning of windows. In such cases, Qt will
128 ignore calls to set the top-level position of a window, and, when queried, the window position
129 will always be returned as QPoint(0, 0).
133 \page mainwindow.html
134 \title Application Main Window
135 \ingroup qt-gui-concepts
136 \brief Creating the application window.
140 \section1 Overview of the Main Window Classes
142 These classes provide everything you need for a typical modern main
143 application window, such as the main window itself, menu and tool bars,
146 \annotatedlist mainwindow-classes
148 \section1 The Main Window Classes
150 Qt provides the following classes for managing main windows and
151 associated user interface components:
154 \li QMainWindow is the central class around which applications can be
155 built. Along with the companion QDockWidget and QToolBar
156 classes, it represents the top-level user interface of the application.
158 \li QDockWidget provides a widget that can be used to create
159 detachable tool palettes or helper windows. Dock widgets keep track
160 of their own properties, and they can be moved, closed, and floated
163 \li QToolBar provides a generic toolbar widget that can hold a
164 number of different action-related widgets, such as buttons,
165 drop-down menus, comboboxes, and spin boxes. The emphasis on a
166 unified action model in Qt means that toolbars cooperate well
167 with menus and keyboard shortcuts.
170 \section1 Example Code
172 Using QMainWindow is straightforward. Generally, you subclass
173 QMainWindow and set up menus, toolbars, and dock widgets inside
174 the QMainWindow constructor.
176 To add a menu bar to the main window, create the menus, and
177 add them to the main window's menu bar. Note that the
178 QMainWindow::menuBar() function will automatically create the menu bar
179 the first time it is called. You can also call
180 QMainWindow::setMenuBar() to use a custom menu bar in the main window.
182 \snippet code/doc_src_qt4-mainwindow.cpp 0
184 \snippet mainwindows/menus/mainwindow.cpp 5
187 Once actions have been created, you can add them to the main window
188 components. To begin with, add them to the pop-up menus:
190 \snippet mainwindows/menus/mainwindow.cpp 10
192 \snippet mainwindows/menus/mainwindow.cpp 11
195 The QToolBar and QMenu classes use Qt's action system to provide a
196 consistent API. In the above code, some existing actions were added to
197 the file menu with the QMenu::addAction() function. QToolBar also
198 provides this function, making it easy to reuse actions in different
199 parts of the main window. This avoids unnecessary duplication of work.
201 Create a toolbar as a child of the main window, and add the desired
205 fileToolBar = addToolBar(tr("File"));
206 fileToolBar->addAction(newAct);
207 fileToolBar->addAction(openAct);
210 \snippet code/doc_src_qt4-mainwindow.cpp 1
212 In this example, the toolbar is restricted to the top and bottom
213 toolbar areas of the main window, and is initially placed in the
214 top tool bar area. We can see that the actions specified by \c
215 newAct and \c openAct will be displayed both on the toolbar and in
218 QDockWidget is used in a similar way to QToolBar. You create a
219 dock widget as a child of the main window, and add widgets as children
222 \snippet dockwidgets/mainwindow.cpp 0
224 In this example, the dock widget can only be placed in the left and
225 right dock areas, and it is initially placed in the left dock area.
227 The QMainWindow API lets you customize which dock
228 widget areas occupy the four corners of the dock widget area. If
229 required, the default can be changed with the
230 QMainWindow::setCorner() function:
232 \snippet code/doc_src_qt4-mainwindow.cpp 2
234 The following diagram shows the configuration produced by the above code.
235 Note that the left and right dock widgets will occupy the top and bottom
236 corners of the main window in this layout.
238 \image mainwindow-docks-example.png
240 Once all the main window components have been set up, the central widget
241 is created and installed by using code similar to the following:
243 \snippet code/doc_src_qt4-mainwindow.cpp 3
245 The central widget can be any subclass of QWidget.