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