doc/src/examples/spinboxes.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/spinboxes
  30     \title Spin Boxes Example
  31
  32     \brief The Spin Boxes example shows how to use the many different types of spin boxes
  33     available in Qt, from a simple QSpinBox widget to more complex editors like
  34     the QDateTimeEdit widget.
  35
  36     \image spinboxes-example.png
  37
  38     The example consists of a single \c Window class that is used to display the
  39     different spin box-based widgets available with Qt.
  40
  41     \section1 Window Class Definition
  42
  43     The \c Window class inherits QWidget and contains two slots that are used
  44     to provide interactive features:
  45
  46     \snippet examples/widgets/spinboxes/window.h 0
  47
  48     The private functions are used to set up each type of spin box in the window.
  49     We use member variables to keep track of various widgets so that they can
  50     be reconfigured when required.
  51
  52     \section1 Window Class Implementation
  53
  54     The constructor simply calls private functions to set up the different types
  55     of spin box used in the example, and places each group in a layout:
  56
  57     \snippet examples/widgets/spinboxes/window.cpp 0
  58
  59     We use the layout to manage the arrangement of the window's child widgets,
  60     and change the window title.
  61
  62     The \c createSpinBoxes() function constructs a QGroupBox and places three
  63     QSpinBox widgets inside it with descriptive labels to indicate the types of
  64     input they expect.
  65
  66     \snippet examples/widgets/spinboxes/window.cpp 1
  67
  68     The first spin box shows the simplest way to use QSpinBox. It accepts values
  69     from -20 to 20, the current value can be increased or decreased by 1 with
  70     either the arrow buttons or \key{Up} and \key{Down} keys, and the default
  71     value is 0.
  72
  73     The second spin box uses a larger step size and displays a suffix to
  74     provide more information about the type of data the number represents:
  75
  76     \snippet examples/widgets/spinboxes/window.cpp 2
  77
  78     This spin box also displays a
  79     \l{QAbstractSpinBox::specialValueText}{special value} instead of the minimum
  80     value defined for it. This means that it will never show \gui{0%}, but will
  81     display \gui{Automatic} when the minimum value is selected.
  82
  83     The third spin box shows how a prefix can be used:
  84
  85     \snippet examples/widgets/spinboxes/window.cpp 4
  86
  87     For simplicity, we show a spin box with a prefix and no suffix. It is also
  88     possible to use both at the same time.
  89
  90     \snippet examples/widgets/spinboxes/window.cpp 5
  91
  92     The rest of the function sets up a layout for the group box and places each
  93     of the widgets inside it.
  94
  95     The \c createDateTimeEdits() function constructs another group box with a
  96     selection of spin boxes used for editing dates and times.
  97
  98     \snippet examples/widgets/spinboxes/window.cpp 6
  99
 100     The first spin box is a QDateEdit widget that is able to accept dates
 101     within a given range specified using QDate values. The arrow buttons and
 102     \key{Up} and \key{Down} keys can be used to increase and decrease the
 103     values for year, month, and day when the cursor is in the relevant section.
 104
 105     The second spin box is a QTimeEdit widget:
 106
 107     \snippet examples/widgets/spinboxes/window.cpp 7
 108
 109     Acceptable values for the time are defined using QTime values.
 110
 111     The third spin box is a QDateTimeEdit widget that can display both date and
 112     time values, and we place a label above it to indicate the range of allowed
 113     times for a meeting. These widgets will be updated when the user changes a
 114     format string.
 115
 116     \snippet examples/widgets/spinboxes/window.cpp 8
 117
 118     The format string used for the date time editor, which is also shown in the
 119     string displayed by the label, is chosen from a set of strings in a combobox:
 120
 121     \snippet examples/widgets/spinboxes/window.cpp 9
 122     \codeline
 123     \snippet examples/widgets/spinboxes/window.cpp 10
 124
 125     A signal from this combobox is connected to a slot in the \c Window class
 126     (shown later).
 127
 128     \snippet examples/widgets/spinboxes/window.cpp 11
 129
 130     Each child widget of the group box in placed in a layout.
 131
 132     The \c setFormatString() slot is called whenever the user selects a new
 133     format string in the combobox. The display format for the QDateTimeEdit
 134     widget is set using the raw string passed by the signal:
 135
 136     \snippet examples/widgets/spinboxes/window.cpp 12
 137
 138     Depending on the visible sections in the widget, we set a new date or time
 139     range, and update the associated label to provide relevant information for
 140     the user:
 141
 142     \snippet examples/widgets/spinboxes/window.cpp 13
 143
 144     When the format string is changed, there will be an appropriate label and
 145     entry widget for dates, times, or both types of input.
 146
 147     The \c createDoubleSpinBoxes() function constructs three spin boxes that are
 148     used to input double-precision floating point numbers:
 149
 150     \snippet examples/widgets/spinboxes/window.cpp 14
 151
 152     Before the QDoubleSpinBox widgets are constructed, we create a spin box to
 153     control how many decimal places they show. By default, only two decimal places
 154     are shown in the following spin boxes, each of which is the equivalent of a
 155     spin box in the group created by the \c createSpinBoxes() function.
 156
 157     The first double spin box shows a basic double-precision spin box with the
 158     same range, step size, and default value as the first spin box in the
 159     \c createSpinBoxes() function:
 160
 161     \snippet examples/widgets/spinboxes/window.cpp 15
 162
 163     However, this spin box also allows non-integer values to be entered.
 164
 165     The second spin box displays a suffix and shows a special value instead
 166     of the minimum value:
 167
 168     \snippet examples/widgets/spinboxes/window.cpp 16
 169
 170     The third spin box displays a prefix instead of a suffix:
 171
 172     \snippet examples/widgets/spinboxes/window.cpp 17
 173
 174     We connect the QSpinBox widget that specifies the precision to a slot in
 175     the \c Window class.
 176
 177     \snippet examples/widgets/spinboxes/window.cpp 18
 178
 179     The rest of the function places each of the widgets into a layout for the
 180     group box.
 181
 182     The \c changePrecision() slot is called when the user changes the value in
 183     the precision spin box:
 184
 185     \snippet examples/widgets/spinboxes/window.cpp 19
 186
 187     This function simply uses the integer supplied by the signal to specify the
 188     number of decimal places in each of the QDoubleSpinBox widgets. Each one
 189     of these will be updated automatically when their
 190     \l{QDoubleSpinBox::decimals}{decimals} property is changed.
 191 */