doc/src/examples/sliders.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/sliders
  30     \title Sliders Example
  31
  32     \brief Qt provides three types of slider-like widgets: QSlider,
  33     QScrollBar and QDial. They all inherit most of their
  34     functionality from QAbstractSlider, and can in theory replace
  35     each other in an application since the differences only concern
  36     their look and feel. This example shows what they look like, how
  37     they work and how their behavior and appearance can be
  38     manipulated through their properties.
  39
  40     The example also demonstrates how signals and slots can be used to
  41     synchronize the behavior of two or more widgets.
  42
  43     \image sliders-example.png Screenshot of the Sliders example
  44
  45     The Sliders example consists of two classes:
  46
  47     \list
  48
  49     \o \c SlidersGroup is a custom widget. It combines a QSlider, a
  50     QScrollBar and a QDial.
  51
  52     \o \c Window is the main widget combining a QGroupBox and a
  53     QStackedWidget. In this example, the QStackedWidget provides a
  54     stack of two \c SlidersGroup widgets. The QGroupBox contain
  55     several widgets that control the behavior of the slider-like
  56     widgets.
  57
  58     \endlist
  59
  60     First we will review the \c Window class, then we
  61     will take a look at the \c SlidersGroup class.
  62
  63     \section1 Window Class Definition
  64
  65     \snippet examples/widgets/sliders/window.h 0
  66
  67     The \c Window class inherits from QWidget. It displays the slider
  68     widgets and allows the user to set their minimum, maximum and
  69     current values and to customize their appearance, key bindings
  70     and orientation. We use a private \c createControls() function to
  71     create the widgets that provide these controlling mechanisms and
  72     to connect them to the slider widgets.
  73
  74     \section1 Window Class Implementation
  75
  76     \snippet examples/widgets/sliders/window.cpp 0
  77
  78     In the constructor we first create the two \c SlidersGroup
  79     widgets that display the slider widgets horizontally and
  80     vertically, and add them to the QStackedWidget. QStackedWidget
  81     provides a stack of widgets where only the top widget is visible.
  82     With \c createControls() we create a connection from a
  83     controlling widget to the QStackedWidget, making the user able to
  84     choose between horizontal and vertical orientation of the slider
  85     widgets. The rest of the controlling mechanisms is implemented by
  86     the same function call.
  87
  88     \snippet examples/widgets/sliders/window.cpp 1
  89     \snippet examples/widgets/sliders/window.cpp 2
  90
  91     Then we connect the \c horizontalSliders, \c verticalSliders and
  92     \c valueSpinBox to each other, so that the slider widgets and the
  93     control widget will behave synchronized when the current value of
  94     one of them changes. The \c valueChanged() signal is emitted with
  95     the new value as argument. The \c setValue() slot sets the
  96     current value of the widget to the new value, and emits \c
  97     valueChanged() if the new value is different from the old one.
  98
  99     We put the group of control widgets and the stacked widget in a
 100     horizontal layout before we initialize the minimum, maximum and
 101     current values. The initialization of the current value will
 102     propagate to the slider widgets through the connection we made
 103     between \c valueSpinBox and the \c SlidersGroup widgets. The
 104     minimum and maximum values propagate through the connections we
 105     created with \c createControls().
 106
 107     \snippet examples/widgets/sliders/window.cpp 3
 108     \snippet examples/widgets/sliders/window.cpp 4
 109
 110     In the private \c createControls() function, we let a QGroupBox
 111     (\c controlsGroup) display the control widgets. A group box can
 112     provide a frame, a title and a keyboard shortcut, and displays
 113     various other widgets inside itself. The group of control widgets
 114     is composed by two checkboxes, three spin boxes (with labels) and
 115     one combobox.
 116
 117     After creating the labels, we create the two checkboxes.
 118     Checkboxes are typically used to represent features in an
 119     application that can be enabled or disabled. When \c
 120     invertedAppearance is enabled, the slider values are inverted.
 121     The table below shows the appearance for the different
 122     slider-like widgets:
 123
 124     \table
 125     \header \o                \o{2,1} QSlider                   \o{2,1} QScrollBar                \o{2,1} QDial
 126     \header \o                \o Normal        \o Inverted      \o Normal        \o Inverted      \o Normal         \o Inverted
 127     \row    \o Qt::Horizontal \o Left to right \o Right to left \o Left to right \o Right to left \o Clockwise \o Counterclockwise
 128     \row    \o Qt::Vertical   \o Bottom to top \o Top to bottom \o Top to bottom \o Bottom to top \o Clockwise \o Counterclockwise
 129     \endtable
 130
 131     It is common to invert the appearance of a vertical QSlider. A
 132     vertical slider that controls volume, for example, will typically
 133     go from bottom to top (the non-inverted appearance), whereas a
 134     vertical slider that controls the position of an object on screen
 135     might go from top to bottom, because screen coordinates go from
 136     top to bottom.
 137
 138     When the \c invertedKeyBindings option is enabled (corresponding
 139     to the QAbstractSlider::invertedControls property), the slider's
 140     wheel and key events are inverted. The normal key bindings mean
 141     that scrolling the mouse wheel "up" or using keys like page up
 142     will increase the slider's current value towards its maximum.
 143     Inverted, the same wheel and key events will move the value
 144     toward the slider's minimum. This can be useful if the \e
 145     appearance of a slider is inverted: Some users might expect the
 146     keys to still work the same way on the value, whereas others
 147     might expect \key PageUp to mean "up" on the screen.
 148
 149     Note that for horizontal and vertical scroll bars, the key
 150     bindings are inverted by default: \key PageDown increases the
 151     current value, and \key PageUp decreases it.
 152
 153     \snippet examples/widgets/sliders/window.cpp 5
 154     \snippet examples/widgets/sliders/window.cpp 6
 155
 156     Then we create the spin boxes. QSpinBox allows the user to choose
 157     a value by clicking the up and down buttons or pressing the \key
 158     Up and \key Down keys on the keyboard to modify the value
 159     currently displayed. The user can also type in the value
 160     manually. The spin boxes control the minimum, maximum and current
 161     values for the QSlider, QScrollBar, and QDial widgets.
 162
 163     We create a QComboBox that allows the user to choose the
 164     orientation of the slider widgets. The QComboBox widget is a
 165     combined button and popup list. It provides a means of presenting
 166     a list of options to the user in a way that takes up the minimum
 167     amount of screen space.
 168
 169     \snippet examples/widgets/sliders/window.cpp 7
 170     \snippet examples/widgets/sliders/window.cpp 8
 171
 172     We synchronize the behavior of the control widgets and the slider
 173     widgets through their signals and slots. We connect each control
 174     widget to both the horizontal and vertical group of slider
 175     widgets. We also connect \c orientationCombo to the
 176     QStackedWidget, so that the correct "page" is shown. Finally, we
 177     lay out the control widgets in a QGridLayout within the \c
 178     controlsGroup group box.
 179
 180     \section1 SlidersGroup Class Definition
 181
 182     \snippet examples/widgets/sliders/slidersgroup.h 0
 183
 184     The \c SlidersGroup class inherits from QGroupBox. It provides a
 185     frame and a title, and contains a QSlider, a QScrollBar and a
 186     QDial.
 187
 188     We provide a \c valueChanged() signal and a public \c setValue()
 189     slot with equivalent functionality to the ones in QAbstractSlider
 190     and QSpinBox. In addition, we implement several other public
 191     slots to set the minimum and maximum value, and invert the slider
 192     widgets' appearance as well as key bindings.
 193
 194     \section1 SlidersGroup Class Implementation
 195
 196     \snippet examples/widgets/sliders/slidersgroup.cpp 0
 197
 198     First we create the slider-like widgets with the appropiate
 199     properties. In particular we set the focus policy for each
 200     widget. Qt::FocusPolicy is an enum type that defines the various
 201     policies a widget can have with respect to acquiring keyboard
 202     focus. The Qt::StrongFocus policy means that the widget accepts
 203     focus by both tabbing and clicking.
 204
 205     Then we connect the widgets with each other, so that they will
 206     stay synchronized when the current value of one of them changes.
 207
 208     \snippet examples/widgets/sliders/slidersgroup.cpp 1
 209     \snippet examples/widgets/sliders/slidersgroup.cpp 2
 210
 211     We connect \c {dial}'s \c valueChanged() signal to the
 212     \c{SlidersGroup}'s \c valueChanged() signal, to notify the other
 213     widgets in the application (i.e., the control widgets) of the
 214     changed value.
 215
 216     \snippet examples/widgets/sliders/slidersgroup.cpp 3
 217     \codeline
 218     \snippet examples/widgets/sliders/slidersgroup.cpp 4
 219
 220     Finally, depending on the \l {Qt::Orientation}{orientation} given
 221     at the time of construction, we choose and create the layout for
 222     the slider widgets within the group box.
 223
 224     \snippet examples/widgets/sliders/slidersgroup.cpp 5
 225     \snippet examples/widgets/sliders/slidersgroup.cpp 6
 226
 227     The \c setValue() slot sets the value of the QSlider. We don't
 228     need to explicitly call
 229     \l{QAbstractSlider::setValue()}{setValue()} on the QScrollBar and
 230     QDial widgets, since QSlider will emit the
 231     \l{QAbstractSlider::valueChanged()}{valueChanged()} signal when
 232     its value changes, triggering a domino effect.
 233
 234     \snippet examples/widgets/sliders/slidersgroup.cpp 7
 235     \snippet examples/widgets/sliders/slidersgroup.cpp 8
 236     \codeline
 237     \snippet examples/widgets/sliders/slidersgroup.cpp 9
 238     \snippet examples/widgets/sliders/slidersgroup.cpp 10
 239
 240     The \c setMinimum() and \c setMaximum() slots are used by the \c
 241     Window class to set the range of the QSlider, QScrollBar, and
 242     QDial widgets.
 243
 244     \snippet examples/widgets/sliders/slidersgroup.cpp 11
 245     \snippet examples/widgets/sliders/slidersgroup.cpp 12
 246     \codeline
 247     \snippet examples/widgets/sliders/slidersgroup.cpp 13
 248     \snippet examples/widgets/sliders/slidersgroup.cpp 14
 249
 250     The \c invertAppearance() and \c invertKeyBindings() slots
 251     control the child widgets'
 252     \l{QAbstractSlider::invertedAppearance}{invertedAppearance} and
 253     \l{QAbstractSlider::invertedControls}{invertedControls}
 254     properties.
 255 */