qt5base-lts/examples/widgets/doc/src/spinboxes.qdoc

192 lines
7.4 KiB
Plaintext
Raw Normal View History

/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example widgets/spinboxes
\title Spin Boxes Example
\ingroup examples-widgets
\brief The Spin Boxes example shows how to use the many different types of
spin boxes available in Qt, from a simple QSpinBox widget to more complex
editors like the QDateTimeEdit widget.
\borderedimage spinboxes-example.png
The example consists of a single \c Window class that is used to display the
different spin box-based widgets available with Qt.
\section1 Window Class Definition
The \c Window class inherits QWidget and contains two slots that are used
to provide interactive features:
\snippet widgets/spinboxes/window.h 0
The private functions are used to set up each type of spin box in the window.
We use member variables to keep track of various widgets so that they can
be reconfigured when required.
\section1 Window Class Implementation
The constructor simply calls private functions to set up the different types
of spin box used in the example, and places each group in a layout:
\snippet widgets/spinboxes/window.cpp 0
We use the layout to manage the arrangement of the window's child widgets,
and change the window title.
The \c createSpinBoxes() function constructs a QGroupBox and places three
QSpinBox widgets inside it with descriptive labels to indicate the types of
input they expect.
\snippet widgets/spinboxes/window.cpp 1
The first spin box shows the simplest way to use QSpinBox. It accepts values
from -20 to 20, the current value can be increased or decreased by 1 with
either the arrow buttons or \uicontrol{Up} and \uicontrol{Down} keys, and the default
value is 0.
The second spin box uses a larger step size and displays a suffix to
provide more information about the type of data the number represents:
\snippet widgets/spinboxes/window.cpp 2
This spin box also displays a
\l{QAbstractSpinBox::specialValueText}{special value} instead of the minimum
value defined for it. This means that it will never show \uicontrol{0%}, but will
display \uicontrol{Automatic} when the minimum value is selected.
The third spin box shows how a prefix can be used:
\snippet widgets/spinboxes/window.cpp 4
For simplicity, we show a spin box with a prefix and no suffix. It is also
possible to use both at the same time.
\snippet widgets/spinboxes/window.cpp 5
The rest of the function sets up a layout for the group box and places each
of the widgets inside it.
The \c createDateTimeEdits() function constructs another group box with a
selection of spin boxes used for editing dates and times.
\snippet widgets/spinboxes/window.cpp 6
The first spin box is a QDateEdit widget that is able to accept dates
within a given range specified using QDate values. The arrow buttons and
\uicontrol{Up} and \uicontrol{Down} keys can be used to increase and decrease the
values for year, month, and day when the cursor is in the relevant section.
The second spin box is a QTimeEdit widget:
\snippet widgets/spinboxes/window.cpp 7
Acceptable values for the time are defined using QTime values.
The third spin box is a QDateTimeEdit widget that can display both date and
time values, and we place a label above it to indicate the range of allowed
times for a meeting. These widgets will be updated when the user changes a
format string.
\snippet widgets/spinboxes/window.cpp 8
The format string used for the date time editor, which is also shown in the
string displayed by the label, is chosen from a set of strings in a combobox:
\snippet widgets/spinboxes/window.cpp 9
\codeline
\snippet widgets/spinboxes/window.cpp 10
A signal from this combobox is connected to a slot in the \c Window class
(shown later).
\snippet widgets/spinboxes/window.cpp 11
Each child widget of the group box in placed in a layout.
The \c setFormatString() slot is called whenever the user selects a new
format string in the combobox. The display format for the QDateTimeEdit
widget is set using the raw string passed by the signal:
\snippet widgets/spinboxes/window.cpp 12
Depending on the visible sections in the widget, we set a new date or time
range, and update the associated label to provide relevant information for
the user:
\snippet widgets/spinboxes/window.cpp 13
When the format string is changed, there will be an appropriate label and
entry widget for dates, times, or both types of input.
The \c createDoubleSpinBoxes() function constructs three spin boxes that are
used to input double-precision floating point numbers:
\snippet widgets/spinboxes/window.cpp 14
Before the QDoubleSpinBox widgets are constructed, we create a spin box to
control how many decimal places they show. By default, only two decimal places
are shown in the following spin boxes, each of which is the equivalent of a
spin box in the group created by the \c createSpinBoxes() function.
The first double spin box shows a basic double-precision spin box with the
same range, step size, and default value as the first spin box in the
\c createSpinBoxes() function:
\snippet widgets/spinboxes/window.cpp 15
However, this spin box also allows non-integer values to be entered.
The second spin box displays a suffix and shows a special value instead
of the minimum value:
\snippet widgets/spinboxes/window.cpp 16
The third spin box displays a prefix instead of a suffix:
\snippet widgets/spinboxes/window.cpp 17
We connect the QSpinBox widget that specifies the precision to a slot in
the \c Window class.
\snippet widgets/spinboxes/window.cpp 18
The rest of the function places each of the widgets into a layout for the
group box.
The \c changePrecision() slot is called when the user changes the value in
the precision spin box:
\snippet widgets/spinboxes/window.cpp 19
This function simply uses the integer supplied by the signal to specify the
number of decimal places in each of the QDoubleSpinBox widgets. Each one
of these will be updated automatically when their
\l{QDoubleSpinBox::decimals}{decimals} property is changed.
*/