Update copyright headers
[qt:qt.git] / doc / src / examples / windowflags.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://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 http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \example widgets/windowflags
30     \title Window Flags Example
31
32     \brief The Window Flags example shows how to use the window flags
33     available in Qt.
34
35     A window flag is either a type or a hint. A type is used to
36     specify various window-system properties for the widget. A widget
37     can only have one type, and the default is Qt::Widget. However, a
38     widget can have zero or more hints. The hints are used to
39     customize the appearance of top-level windows.
40
41     A widget's flags are stored in a Qt::WindowFlags type which stores
42     an OR combination of the flags.
43
44     \image windowflags-example.png Screenshot of the Window Flags example
45
46     The example consists of two classes:
47
48     \list
49     \o \c ControllerWindow is the main application widget that allows
50        the user to choose among the available window flags, and displays
51        the effect on a separate preview window.
52     \o \c PreviewWindow is a custom widget displaying the name of
53        its currently set window flags in a read-only text editor.
54     \endlist
55
56     We will start by reviewing the \c ControllerWindow class, then we
57     will take a look at the \c PreviewWindow class.
58
59     \section1 ControllerWindow Class Definition
60
61     \snippet examples/widgets/windowflags/controllerwindow.h 0
62
63     The \c ControllerWindow class inherits QWidget. The widget allows
64     the user to choose among the available window flags, and displays
65     the effect on a separate preview window.
66
67     We declare a private \c updatePreview() slot to refresh the
68     preview window whenever the user changes the window flags.
69
70     We also declare several private functions to simplify the
71     constructor: We call the \c createTypeGroupBox() function to
72     create a radio button for each available window type, using the
73     private \c createButton() function, and gather them within a group
74     box. In a similar way we use the \c createHintsGroupBox() function
75     to create a check box for each available hint, using the private
76     \c createCheckBox() function.
77
78     In addition to the various radio buttons and checkboxes, we need
79     an associated \c PreviewWindow to show the effect of the currently
80     chosen window flags.
81
82     \image windowflags_controllerwindow.png Screenshot of the Controller Window
83
84     \section1 ControllerWindow Class Implementation
85
86     \snippet examples/widgets/windowflags/controllerwindow.cpp 0
87
88     In the constructor we first create the preview window. Then we
89     create the group boxes containing the available window flags using
90     the private \c createTypeGroupBox() and \c createHintsGroupBox()
91     functions. In addition we create a \gui Quit button. We put the
92     button and a stretchable space in a separate layout to make the
93     button appear in the \c WindowFlag widget's right bottom corner.
94
95     Finally, we add the button's layout and the two goup boxes to a
96     QVBoxLayout, set the window title and refresh the preview window
97     using the \c updatePreview() slot.
98
99     \snippet examples/widgets/windowflags/controllerwindow.cpp 1
100     \snippet examples/widgets/windowflags/controllerwindow.cpp 2
101
102     The \c updatePreview() slot is called whenever the user changes
103     any of the window flags. First we create an empty Qt::WindowFlags
104     \c flags, then we determine which one of the types that is checked
105     and add it to \c flags.
106
107     \snippet examples/widgets/windowflags/controllerwindow.cpp 3
108
109     We also determine which of the hints that are checked, and add
110     them to \c flags using an OR operator. We use \c flags to set the
111     window flags for the preview window.
112
113     \snippet examples/widgets/windowflags/controllerwindow.cpp 4
114
115     We adjust the position of the preview window. The reason we do
116     that, is that playing around with the window's frame may on some
117     platforms cause the window's position to be changed behind our
118     back. If a window is located in the upper left corner of the
119     screen, parts of the window may not be visible. So we adjust the
120     widget's position to make sure that, if this happens, the window
121     is moved within the screen's boundaries. Finally, we call
122     QWidget::show() to make sure the preview window is visible.
123
124     \omit
125     \skipto pos
126     \printuntil /^\}/
127     \endomit
128
129     \snippet examples/widgets/windowflags/controllerwindow.cpp 5
130
131     The private \c createTypeGroupBox() function is called from the
132     constructor.
133
134     First we create a group box, and then we create a radio button
135     (using the private \c createRadioButton() function) for each of
136     the available types among the window flags. We make Qt::Window the
137     initially applied type. We put the radio buttons into a
138     QGridLayout and install the layout on the group box.
139
140     We do not include the default Qt::Widget type. The reason is that
141     it behaves somewhat different than the other types. If the type is
142     not specified for a widget, and it has no parent, the widget is a
143     window. However, if it has a parent, it is a standard child
144     widget. The other types are all top-level windows, and since the
145     hints only affect top-level windows, we abandon the Qt::Widget
146     type.
147
148     \snippet examples/widgets/windowflags/controllerwindow.cpp 6
149
150     The private \c createHintsGroupBox() function is also called from
151     the constructor.
152
153     Again, the first thing we do is to create a group box. Then we
154     create a checkbox, using the private \c createCheckBox() function,
155     for each of the available hints among the window flags. We put the
156     checkboxes into a QGridLayout and install the layout on the group
157     box.
158
159     \snippet examples/widgets/windowflags/controllerwindow.cpp 7
160
161     The private \c createCheckBox() function is called from \c
162     createHintsGroupBox().
163
164     We simply create a QCheckBox with the provided text, connect it to
165     the private \c updatePreview() slot, and return a pointer to the
166     checkbox.
167
168     \snippet examples/widgets/windowflags/controllerwindow.cpp 8
169
170     In the private \c createRadioButton() function it is a
171     QRadioButton we create with the provided text, and connect to the
172     private \c updatePreview() slot. The function is called from \c
173     createTypeGroupBox(), and returns a pointer to the button.
174
175     \section1 PreviewWindow Class Definition
176
177     \snippet examples/widgets/windowflags/previewwindow.h 0
178
179     The \c PreviewWindow class inherits QWidget. It is a custom widget
180     that displays the names of its currently set window flags in a
181     read-only text editor. It is also provided with a QPushbutton that
182     closes the window.
183
184     We reimplement the constructor to create the \gui Close button and
185     the text editor, and the QWidget::setWindowFlags() function to
186     display the names of the window flags.
187
188     \image windowflags_previewwindow.png Screenshot of the Preview Window
189
190     \section1 PreviewWindow Class Implementation
191
192     \snippet examples/widgets/windowflags/previewwindow.cpp 0
193
194     In the constructor, we first create a QTextEdit and make sure that
195     it is read-only.
196
197     We also prohibit any line wrapping in the text editor using the
198     QTextEdit::setLineWrapMode() function. The result is that a
199     horizontal scrollbar appears when a window flag's name exceeds the
200     width of the editor. This is a reasonable solution since we
201     construct the displayed text with built-in line breaks. If no line
202     breaks were guaranteed, using another QTextEdit::LineWrapMode
203     would perhaps make more sense.
204
205     Then we create the \gui Close button, and put both the widgets
206     into a QVBoxLayout before we set the window title.
207
208     \snippet examples/widgets/windowflags/previewwindow.cpp 1
209
210     In our reimplementation of the \c setWindowFlags() function, we
211     first set the widgets flags using the QWidget::setWindowFlags()
212     function. Then we run through the available window flags, creating
213     a text that contains the names of the flags that matches the \c
214     flags parameter. Finally, we display the text in the widgets text
215     editor.
216 */