diff options
Diffstat (limited to 'doc/src/examples/sliders.qdoc')
| -rw-r--r-- | doc/src/examples/sliders.qdoc | 269 |
1 files changed, 269 insertions, 0 deletions
diff --git a/doc/src/examples/sliders.qdoc b/doc/src/examples/sliders.qdoc new file mode 100644 index 0000000..650fdcb --- /dev/null +++ b/doc/src/examples/sliders.qdoc @@ -0,0 +1,269 @@ +/**************************************************************************** +** +** 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/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. +*/ |