/****************************************************************************+
−
**+
−
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).+
−
** All rights reserved.+
−
** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying+
−
** this package.+
−
**+
−
** 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.1, included in the file LGPL_EXCEPTION.txt in this package.+
−
**+
−
** If you have questions regarding the use of this file, please contact+
−
** Nokia at qt-info@nokia.com.+
−
**+
−
**+
−
**+
−
**+
−
**+
−
**+
−
**+
−
**+
−
** $QT_END_LICENSE$+
−
**+
−
****************************************************************************/+
−
+
−
/*!+
−
    \example widgets/sliders+
−
    \title Sliders Example+
−
+
−
    Qt provides three types of slider-like widgets: QSlider,+
−
    QScrollBar and QDial. They all inherit most of their+
−
    functionality from QAbstractSlider, and can in theory replace+
−
    each other in an application since the differences only concern+
−
    their look and feel. This example shows what they look like, how+
−
    they work and how their behavior and appearance can be+
−
    manipulated through their properties.+
−
+
−
    The example also demonstrates how signals and slots can be used to+
−
    synchronize the behavior of two or more widgets.+
−
+
−
    \image sliders-example.png Screenshot of the Sliders example+
−
+
−
    The Sliders example consists of two classes:+
−
+
−
    \list+
−
+
−
    \o \c SlidersGroup is a custom widget. It combines a QSlider, a+
−
    QScrollBar and a QDial.+
−
+
−
    \o \c Window is the main widget combining a QGroupBox and a+
−
    QStackedWidget. In this example, the QStackedWidget provides a+
−
    stack of two \c SlidersGroup widgets. The QGroupBox contain+
−
    several widgets that control the behavior of the slider-like+
−
    widgets.+
−
+
−
    \endlist+
−
+
−
    First we will review the \c Window class, then we+
−
    will take a look at the \c SlidersGroup class.+
−
+
−
    \section1 Window Class Definition+
−
+
−
    \snippet examples/widgets/sliders/window.h 0+
−
+
−
    The \c Window class inherits from QWidget. It displays the slider+
−
    widgets and allows the user to set their minimum, maximum and+
−
    current values and to customize their appearance, key bindings+
−
    and orientation. We use a private \c createControls() function to+
−
    create the widgets that provide these controlling mechanisms and+
−
    to connect them to the slider widgets.+
−
+
−
    \section1 Window Class Implementation+
−
+
−
    \snippet examples/widgets/sliders/window.cpp 0+
−
+
−
    In the constructor we first create the two \c SlidersGroup+
−
    widgets that display the slider widgets horizontally and+
−
    vertically, and add them to the QStackedWidget. QStackedWidget+
−
    provides a stack of widgets where only the top widget is visible.+
−
    With \c createControls() we create a connection from a+
−
    controlling widget to the QStackedWidget, making the user able to+
−
    choose between horizontal and vertical orientation of the slider+
−
    widgets. The rest of the controlling mechanisms is implemented by+
−
    the same function call.+
−
+
−
    \snippet examples/widgets/sliders/window.cpp 1+
−
    \snippet examples/widgets/sliders/window.cpp 2+
−
+
−
    Then we connect the \c horizontalSliders, \c verticalSliders and+
−
    \c valueSpinBox to each other, so that the slider widgets and the+
−
    control widget will behave synchronized when the current value of+
−
    one of them changes. The \c valueChanged() signal is emitted with+
−
    the new value as argument. The \c setValue() slot sets the+
−
    current value of the widget to the new value, and emits \c+
−
    valueChanged() if the new value is different from the old one.+
−
+
−
    We put the group of control widgets and the stacked widget in a+
−
    horizontal layout before we initialize the minimum, maximum and+
−
    current values. The initialization of the current value will+
−
    propagate to the slider widgets through the connection we made+
−
    between \c valueSpinBox and the \c SlidersGroup widgets. The+
−
    minimum and maximum values propagate through the connections we+
−
    created with \c createControls().+
−
+
−
    \snippet examples/widgets/sliders/window.cpp 3+
−
    \snippet examples/widgets/sliders/window.cpp 4+
−
+
−
    In the private \c createControls() function, we let a QGroupBox+
−
    (\c controlsGroup) display the control widgets. A group box can+
−
    provide a frame, a title and a keyboard shortcut, and displays+
−
    various other widgets inside itself. The group of control widgets+
−
    is composed by two checkboxes, three spin boxes (with labels) and+
−
    one combobox.+
−
+
−
    After creating the labels, we create the two checkboxes.+
−
    Checkboxes are typically used to represent features in an+
−
    application that can be enabled or disabled. When \c+
−
    invertedAppearance is enabled, the slider values are inverted.+
−
    The table below shows the appearance for the different+
−
    slider-like widgets:+
−
+
−
    \table+
−
    \header \o                \o{2,1} QSlider                   \o{2,1} QScrollBar                \o{2,1} QDial+
−
    \header \o                \o Normal        \o Inverted      \o Normal        \o Inverted      \o Normal         \o Inverted+
−
    \row    \o Qt::Horizontal \o Left to right \o Right to left \o Left to right \o Right to left \o Clockwise \o Counterclockwise+
−
    \row    \o Qt::Vertical   \o Bottom to top \o Top to bottom \o Top to bottom \o Bottom to top \o Clockwise \o Counterclockwise+
−
    \endtable+
−
+
−
    It is common to invert the appearance of a vertical QSlider. A+
−
    vertical slider that controls volume, for example, will typically+
−
    go from bottom to top (the non-inverted appearance), whereas a+
−
    vertical slider that controls the position of an object on screen+
−
    might go from top to bottom, because screen coordinates go from+
−
    top to bottom.+
−
+
−
    When the \c invertedKeyBindings option is enabled (corresponding+
−
    to the QAbstractSlider::invertedControls property), the slider's+
−
    wheel and key events are inverted. The normal key bindings mean+
−
    that scrolling the mouse wheel "up" or using keys like page up+
−
    will increase the slider's current value towards its maximum.+
−
    Inverted, the same wheel and key events will move the value+
−
    toward the slider's minimum. This can be useful if the \e+
−
    appearance of a slider is inverted: Some users might expect the+
−
    keys to still work the same way on the value, whereas others+
−
    might expect \key PageUp to mean "up" on the screen.+
−
+
−
    Note that for horizontal and vertical scroll bars, the key+
−
    bindings are inverted by default: \key PageDown increases the+
−
    current value, and \key PageUp decreases it.+
−
+
−
    \snippet examples/widgets/sliders/window.cpp 5+
−
    \snippet examples/widgets/sliders/window.cpp 6+
−
+
−
    Then we create the spin boxes. QSpinBox allows the user to choose+
−
    a value by clicking the up and down buttons or pressing the \key+
−
    Up and \key Down keys on the keyboard to modify the value+
−
    currently displayed. The user can also type in the value+
−
    manually. The spin boxes control the minimum, maximum and current+
−
    values for the QSlider, QScrollBar, and QDial widgets.+
−
+
−
    We create a QComboBox that allows the user to choose the+
−
    orientation of the slider widgets. The QComboBox widget is a+
−
    combined button and popup list. It provides a means of presenting+
−
    a list of options to the user in a way that takes up the minimum+
−
    amount of screen space.+
−
+
−
    \snippet examples/widgets/sliders/window.cpp 7+
−
    \snippet examples/widgets/sliders/window.cpp 8+
−
+
−
    We synchronize the behavior of the control widgets and the slider+
−
    widgets through their signals and slots. We connect each control+
−
    widget to both the horizontal and vertical group of slider+
−
    widgets. We also connect \c orientationCombo to the+
−
    QStackedWidget, so that the correct "page" is shown. Finally, we+
−
    lay out the control widgets in a QGridLayout within the \c+
−
    controlsGroup group box.+
−
+
−
    \section1 SlidersGroup Class Definition+
−
+
−
    \snippet examples/widgets/sliders/slidersgroup.h 0+
−
+
−
    The \c SlidersGroup class inherits from QGroupBox. It provides a+
−
    frame and a title, and contains a QSlider, a QScrollBar and a+
−
    QDial.+
−
+
−
    We provide a \c valueChanged() signal and a public \c setValue()+
−
    slot with equivalent functionality to the ones in QAbstractSlider+
−
    and QSpinBox. In addition, we implement several other public+
−
    slots to set the minimum and maximum value, and invert the slider+
−
    widgets' appearance as well as key bindings.+
−
+
−
    \section1 SlidersGroup Class Implementation+
−
+
−
    \snippet examples/widgets/sliders/slidersgroup.cpp 0+
−
+
−
    First we create the slider-like widgets with the appropiate+
−
    properties. In particular we set the focus policy for each+
−
    widget. Qt::FocusPolicy is an enum type that defines the various+
−
    policies a widget can have with respect to acquiring keyboard+
−
    focus. The Qt::StrongFocus policy means that the widget accepts+
−
    focus by both tabbing and clicking.+
−
+
−
    Then we connect the widgets with each other, so that they will+
−
    stay synchronized when the current value of one of them changes.+
−
+
−
    \snippet examples/widgets/sliders/slidersgroup.cpp 1+
−
    \snippet examples/widgets/sliders/slidersgroup.cpp 2+
−
+
−
    We connect \c {dial}'s \c valueChanged() signal to the+
−
    \c{SlidersGroup}'s \c valueChanged() signal, to notify the other+
−
    widgets in the application (i.e., the control widgets) of the+
−
    changed value.+
−
+
−
    \snippet examples/widgets/sliders/slidersgroup.cpp 3+
−
    \codeline+
−
    \snippet examples/widgets/sliders/slidersgroup.cpp 4+
−
+
−
    Finally, depending on the \l {Qt::Orientation}{orientation} given+
−
    at the time of construction, we choose and create the layout for+
−
    the slider widgets within the group box.+
−
+
−
    \snippet examples/widgets/sliders/slidersgroup.cpp 5+
−
    \snippet examples/widgets/sliders/slidersgroup.cpp 6+
−
+
−
    The \c setValue() slot sets the value of the QSlider. We don't+
−
    need to explicitly call+
−
    \l{QAbstractSlider::setValue()}{setValue()} on the QScrollBar and+
−
    QDial widgets, since QSlider will emit the+
−
    \l{QAbstractSlider::valueChanged()}{valueChanged()} signal when+
−
    its value changes, triggering a domino effect.+
−
+
−
    \snippet examples/widgets/sliders/slidersgroup.cpp 7+
−
    \snippet examples/widgets/sliders/slidersgroup.cpp 8+
−
    \codeline+
−
    \snippet examples/widgets/sliders/slidersgroup.cpp 9+
−
    \snippet examples/widgets/sliders/slidersgroup.cpp 10+
−
+
−
    The \c setMinimum() and \c setMaximum() slots are used by the \c+
−
    Window class to set the range of the QSlider, QScrollBar, and+
−
    QDial widgets.+
−
+
−
    \snippet examples/widgets/sliders/slidersgroup.cpp 11+
−
    \snippet examples/widgets/sliders/slidersgroup.cpp 12+
−
    \codeline+
−
    \snippet examples/widgets/sliders/slidersgroup.cpp 13+
−
    \snippet examples/widgets/sliders/slidersgroup.cpp 14+
−
+
−
    The \c invertAppearance() and \c invertKeyBindings() slots+
−
    control the child widgets'+
−
    \l{QAbstractSlider::invertedAppearance}{invertedAppearance} and+
−
    \l{QAbstractSlider::invertedControls}{invertedControls}+
−
    properties.+
−
*/+
−