← Back to branch summary

~gabriel1984sibiu/minitube/qt5.6

« back to all changes in this revision

Viewing changes to src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc

  • Committer: Grevutiu Gabriel
  • Date: 2017-06-13 08:43:17 UTC
  • Revision ID: gabriel1984sibiu@gmail.com-20170613084317-ek0zqe0u9g3ocvi8
Original upstream code

Show diffs side-by-side

added added

removed removed

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