Long live Qt 4.5!

1 files changed, 230 insertions, 0 deletions

diff --git a/doc/src/examples/windowflags.qdoc b/doc/src/examples/windowflags.qdoc
new file mode 100644
index 0000000..b25206e
--- /dev/null
+++ b/doc/src/examples/windowflags.qdoc
@@ -0,0 +1,230 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example widgets/windowflags
+    \title Window Flags Example
+
+    The Window Flags example shows how to use the window flags
+    available in Qt.
+
+    A window flag is either a type or a hint. A type is used to
+    specify various window-system properties for the widget. A widget
+    can only have one type, and the default is Qt::Widget. However, a
+    widget can have zero or more hints. The hints are used to
+    customize the appearance of top-level windows.
+
+    A widget's flags are stored in a Qt::WindowFlags type which stores
+    an OR combination of the flags.
+
+    \image windowflags-example.png Screenshot of the Window Flags example
+
+    The example consists of two classes:
+
+    \list
+    \o \c ControllerWindow is the main application widget that allows
+       the user to choose among the available window flags, and displays
+       the effect on a separate preview window.
+    \o \c PreviewWindow is a custom widget displaying the name of
+       its currently set window flags in a read-only text editor.
+    \endlist
+
+    We will start by reviewing the \c ControllerWindow class, then we
+    will take a look at the \c PreviewWindow class.
+
+    \section1 ControllerWindow Class Definition
+
+    \snippet examples/widgets/windowflags/controllerwindow.h 0
+
+    The \c ControllerWindow class inherits QWidget. The widget allows
+    the user to choose among the available window flags, and displays
+    the effect on a separate preview window.
+
+    We declare a private \c updatePreview() slot to refresh the
+    preview window whenever the user changes the window flags.
+
+    We also declare several private functions to simplify the
+    constructor: We call the \c createTypeGroupBox() function to
+    create a radio button for each available window type, using the
+    private \c createButton() function, and gather them within a group
+    box. In a similar way we use the \c createHintsGroupBox() function
+    to create a check box for each available hint, using the private
+    \c createCheckBox() function.
+
+    In addition to the various radio buttons and checkboxes, we need
+    an associated \c PreviewWindow to show the effect of the currently
+    chosen window flags.
+
+    \image windowflags_controllerwindow.png Screenshot of the Controller Window
+
+    \section1 ControllerWindow Class Implementation
+
+    \snippet examples/widgets/windowflags/controllerwindow.cpp 0
+
+    In the constructor we first create the preview window. Then we
+    create the group boxes containing the available window flags using
+    the private \c createTypeGroupBox() and \c createHintsGroupBox()
+    functions. In addition we create a \gui Quit button. We put the
+    button and a stretchable space in a separate layout to make the
+    button appear in the \c WindowFlag widget's right bottom corner.
+
+    Finally, we add the button's layout and the two goup boxes to a
+    QVBoxLayout, set the window title and refresh the preview window
+    using the \c updatePreview() slot.
+
+    \snippet examples/widgets/windowflags/controllerwindow.cpp 1
+    \snippet examples/widgets/windowflags/controllerwindow.cpp 2
+
+    The \c updatePreview() slot is called whenever the user changes
+    any of the window flags. First we create an empty Qt::WindowFlags
+    \c flags, then we determine which one of the types that is checked
+    and add it to \c flags.
+
+    \snippet examples/widgets/windowflags/controllerwindow.cpp 3
+
+    We also determine which of the hints that are checked, and add
+    them to \c flags using an OR operator. We use \c flags to set the
+    window flags for the preview window.
+
+    \snippet examples/widgets/windowflags/controllerwindow.cpp 4
+
+    We adjust the position of the preview window. The reason we do
+    that, is that playing around with the window's frame may on some
+    platforms cause the window's position to be changed behind our
+    back. If a window is located in the upper left corner of the
+    screen, parts of the window may not be visible. So we adjust the
+    widget's position to make sure that, if this happens, the window
+    is moved within the screen's boundaries. Finally, we call
+    QWidget::show() to make sure the preview window is visible.
+
+    \omit
+    \skipto pos
+    \printuntil /^\}/
+    \endomit
+
+    \snippet examples/widgets/windowflags/controllerwindow.cpp 5
+
+    The private \c createTypeGroupBox() function is called from the
+    constructor.
+
+    First we create a group box, and then we create a radio button
+    (using the private \c createRadioButton() function) for each of
+    the available types among the window flags. We make Qt::Window the
+    initially applied type. We put the radio buttons into a
+    QGridLayout and install the layout on the group box.
+
+    We do not include the default Qt::Widget type. The reason is that
+    it behaves somewhat different than the other types. If the type is
+    not specified for a widget, and it has no parent, the widget is a
+    window. However, if it has a parent, it is a standard child
+    widget. The other types are all top-level windows, and since the
+    hints only affect top-level windows, we abandon the Qt::Widget
+    type.
+
+    \snippet examples/widgets/windowflags/controllerwindow.cpp 6
+
+    The private \c createHintsGroupBox() function is also called from
+    the constructor.
+
+    Again, the first thing we do is to create a group box. Then we
+    create a checkbox, using the private \c createCheckBox() function,
+    for each of the available hints among the window flags. We put the
+    checkboxes into a QGridLayout and install the layout on the group
+    box.
+
+    \snippet examples/widgets/windowflags/controllerwindow.cpp 7
+
+    The private \c createCheckBox() function is called from \c
+    createHintsGroupBox().
+
+    We simply create a QCheckBox with the provided text, connect it to
+    the private \c updatePreview() slot, and return a pointer to the
+    checkbox.
+
+    \snippet examples/widgets/windowflags/controllerwindow.cpp 8
+
+    In the private \c createRadioButton() function it is a
+    QRadioButton we create with the provided text, and connect to the
+    private \c updatePreview() slot. The function is called from \c
+    createTypeGroupBox(), and returns a pointer to the button.
+
+    \section1 PreviewWindow Class Definition
+
+    \snippet examples/widgets/windowflags/previewwindow.h 0
+
+    The \c PreviewWindow class inherits QWidget. It is a custom widget
+    that displays the names of its currently set window flags in a
+    read-only text editor. It is also provided with a QPushbutton that
+    closes the window.
+
+    We reimplement the constructor to create the \gui Close button and
+    the text editor, and the QWidget::setWindowFlags() function to
+    display the names of the window flags.
+
+    \image windowflags_previewwindow.png Screenshot of the Preview Window
+
+    \section1 PreviewWindow Class Implementation
+
+    \snippet examples/widgets/windowflags/previewwindow.cpp 0
+
+    In the constructor, we first create a QTextEdit and make sure that
+    it is read-only.
+
+    We also prohibit any line wrapping in the text editor using the
+    QTextEdit::setLineWrapMode() function. The result is that a
+    horizontal scrollbar appears when a window flag's name exceeds the
+    width of the editor. This is a reasonable solution since we
+    construct the displayed text with built-in line breaks. If no line
+    breaks were guaranteed, using another QTextEdit::LineWrapMode
+    would perhaps make more sense.
+
+    Then we create the \gui Close button, and put both the widgets
+    into a QVBoxLayout before we set the window title.
+
+    \snippet examples/widgets/windowflags/previewwindow.cpp 1
+
+    In our reimplementation of the \c setWindowFlags() function, we
+    first set the widgets flags using the QWidget::setWindowFlags()
+    function. Then we run through the available window flags, creating
+    a text that contains the names of the flags that matches the \c
+    flags parameter. Finally, we display the text in the widgets text
+    editor.
+*/