1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*! 

    43     \example widgets/spinboxes

    44     \title Spin Boxes Example

    45 

    46     The Spin Boxes example shows how to use the many different types of spin boxes

    47     available in Qt, from a simple QSpinBox widget to more complex editors like

    48     the QDateTimeEdit widget.

    49 

    50     \image spinboxes-example.png

    51 

    52     The example consists of a single \c Window class that is used to display the

    53     different spin box-based widgets available with Qt.

    54 

    55     \section1 Window Class Definition

    56 

    57     The \c Window class inherits QWidget and contains two slots that are used

    58     to provide interactive features:

    59 

    60     \snippet examples/widgets/spinboxes/window.h 0

    61 

    62     The private functions are used to set up each type of spin box in the window.

    63     We use member variables to keep track of various widgets so that they can

    64     be reconfigured when required.

    65 

    66     \section1 Window Class Implementation

    67 

    68     The constructor simply calls private functions to set up the different types

    69     of spin box used in the example, and places each group in a layout:

    70 

    71     \snippet examples/widgets/spinboxes/window.cpp 0

    72 

    73     We use the layout to manage the arrangement of the window's child widgets,

    74     and change the window title.

    75 

    76     The \c createSpinBoxes() function constructs a QGroupBox and places three

    77     QSpinBox widgets inside it with descriptive labels to indicate the types of

    78     input they expect.

    79 

    80     \snippet examples/widgets/spinboxes/window.cpp 1

    81 

    82     The first spin box shows the simplest way to use QSpinBox. It accepts values

    83     from -20 to 20, the current value can be increased or decreased by 1 with

    84     either the arrow buttons or \key{Up} and \key{Down} keys, and the default

    85     value is 0.

    86 

    87     The second spin box uses a larger step size and displays a suffix to

    88     provide more information about the type of data the number represents:

    89 

    90     \snippet examples/widgets/spinboxes/window.cpp 2

    91 

    92     This spin box also displays a

    93     \l{QAbstractSpinBox::specialValueText}{special value} instead of the minimum

    94     value defined for it. This means that it will never show \gui{0%}, but will

    95     display \gui{Automatic} when the minimum value is selected.

    96 

    97     The third spin box shows how a prefix can be used:

    98 

    99     \snippet examples/widgets/spinboxes/window.cpp 4

   100 

   101     For simplicity, we show a spin box with a prefix and no suffix. It is also

   102     possible to use both at the same time.

   103 

   104     \snippet examples/widgets/spinboxes/window.cpp 5

   105 

   106     The rest of the function sets up a layout for the group box and places each

   107     of the widgets inside it.

   108 

   109     The \c createDateTimeEdits() function constructs another group box with a

   110     selection of spin boxes used for editing dates and times.

   111 

   112     \snippet examples/widgets/spinboxes/window.cpp 6

   113 

   114     The first spin box is a QDateEdit widget that is able to accept dates

   115     within a given range specified using QDate values. The arrow buttons and

   116     \key{Up} and \key{Down} keys can be used to increase and decrease the

   117     values for year, month, and day when the cursor is in the relevant section.

   118 

   119     The second spin box is a QTimeEdit widget:

   120 

   121     \snippet examples/widgets/spinboxes/window.cpp 7

   122 

   123     Acceptable values for the time are defined using QTime values.

   124 

   125     The third spin box is a QDateTimeEdit widget that can display both date and

   126     time values, and we place a label above it to indicate the range of allowed

   127     times for a meeting. These widgets will be updated when the user changes a

   128     format string.

   129 

   130     \snippet examples/widgets/spinboxes/window.cpp 8

   131 

   132     The format string used for the date time editor, which is also shown in the

   133     string displayed by the label, is chosen from a set of strings in a combobox:

   134 

   135     \snippet examples/widgets/spinboxes/window.cpp 9

   136     \codeline

   137     \snippet examples/widgets/spinboxes/window.cpp 10

   138 

   139     A signal from this combobox is connected to a slot in the \c Window class

   140     (shown later).

   141 

   142     \snippet examples/widgets/spinboxes/window.cpp 11

   143 

   144     Each child widget of the group box in placed in a layout.

   145 

   146     The \c setFormatString() slot is called whenever the user selects a new

   147     format string in the combobox. The display format for the QDateTimeEdit

   148     widget is set using the raw string passed by the signal:

   149 

   150     \snippet examples/widgets/spinboxes/window.cpp 12

   151 

   152     Depending on the visible sections in the widget, we set a new date or time

   153     range, and update the associated label to provide relevant information for

   154     the user:

   155 

   156     \snippet examples/widgets/spinboxes/window.cpp 13

   157 

   158     When the format string is changed, there will be an appropriate label and

   159     entry widget for dates, times, or both types of input.

   160 

   161     The \c createDoubleSpinBoxes() function constructs three spin boxes that are

   162     used to input double-precision floating point numbers:

   163 

   164     \snippet examples/widgets/spinboxes/window.cpp 14

   165 

   166     Before the QDoubleSpinBox widgets are constructed, we create a spin box to

   167     control how many decimal places they show. By default, only two decimal places

   168     are shown in the following spin boxes, each of which is the equivalent of a

   169     spin box in the group created by the \c createSpinBoxes() function.

   170 

   171     The first double spin box shows a basic double-precision spin box with the

   172     same range, step size, and default value as the first spin box in the

   173     \c createSpinBoxes() function:

   174 

   175     \snippet examples/widgets/spinboxes/window.cpp 15

   176 

   177     However, this spin box also allows non-integer values to be entered.

   178 

   179     The second spin box displays a suffix and shows a special value instead

   180     of the minimum value:

   181 

   182     \snippet examples/widgets/spinboxes/window.cpp 16

   183 

   184     The third spin box displays a prefix instead of a suffix:

   185 

   186     \snippet examples/widgets/spinboxes/window.cpp 17

   187 

   188     We connect the QSpinBox widget that specifies the precision to a slot in

   189     the \c Window class.

   190 

   191     \snippet examples/widgets/spinboxes/window.cpp 18

   192 

   193     The rest of the function places each of the widgets into a layout for the

   194     group box.

   195 

   196     The \c changePrecision() slot is called when the user changes the value in

   197     the precision spin box:

   198 

   199     \snippet examples/widgets/spinboxes/window.cpp 19

   200 

   201     This function simply uses the integer supplied by the signal to specify the

   202     number of decimal places in each of the QDoubleSpinBox widgets. Each one

   203     of these will be updated automatically when their

   204     \l{QDoubleSpinBox::decimals}{decimals} property is changed.

   205 */