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