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 */