qt5base-lts/examples/widgets/doc/lineedits.qdoc

/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example widgets/widgets/lineedits
    \title Line Edits Example

    The Line Edits example demonstrates the many ways that QLineEdit can be used, and
    shows the effects of various properties and validators on the input and output
    supplied by the user.

    \image lineedits-example.png

    The example consists of a single \c Window class, containing a selection of
    line edits with different input constraints and display properties that can be
    changed by selecting items from comboboxes. Presenting these together helps
    developers choose suitable properties to use with line edits, and makes it easy
    to compare the effects of each validator on user input.

    \section1 Window Class Definition

    The \c Window class inherits QWidget and contains a constructor and several
    slots:

    \snippet widgets/widgets/lineedits/window.h 0

    The slots are used to update the type of validator used for a given line edit when
    a new validator has been selected in the associated combobox. The line edits
    are stored in the window for use in these slots.

    \section1 Window Class Implementation

    The \c Window constructor is used to set up the line edits, validators,
    and comboboxes, connect signals from the comboboxes to slots in the \c Window
    class, and arrange the child widgets in layouts.

    We begin by constructing a \l{QGroupBox}{group box} to hold a label, combobox,
    and line edit so that we can demonstrate the QLineEdit::echoMode property:

    \snippet widgets/widgets/lineedits/window.cpp 0

    At this point, none of these widgets have been arranged in layouts. Eventually,
    the \c echoLabel, \c echoComboBox, and \c echoLineEdit will be placed in a
    vertical layout inside the \c echoGroup group box.

    Similarly, we construct group boxes and collections of widgets to show the
    effects of QIntValidator and QDoubleValidator on a line edit's contents:

    \snippet widgets/widgets/lineedits/window.cpp 1

    Text alignment is demonstrated by another group of widgets:

    \snippet widgets/widgets/lineedits/window.cpp 2

    QLineEdit supports the use of \l{QLineEdit::inputMask}{input masks}.
    These only allow the user to type characters into the line edit that
    follow a simple specification. We construct a group of widgets to
    demonstrate a selection of predefined masks:

    \snippet widgets/widgets/lineedits/window.cpp 3

    Another useful feature of QLineEdit is its ability to make its contents
    read-only. This property is used to control access to a line edit in the
    following group of widgets:

    \snippet widgets/widgets/lineedits/window.cpp 4

    Now that all the child widgets have been constructed, we connect signals
    from the comboboxes to slots in the \c Window object:

    \snippet widgets/widgets/lineedits/window.cpp 5

    Each of these connections use the QComboBox::activated() signal that
    supplies an integer to the slot. This will be used to efficiently
    make changes to the appropriate line edit in each slot.

    We place each combobox, line edit, and label in a layout for each group
    box, beginning with the layout for the \c echoGroup group box:

    \snippet widgets/widgets/lineedits/window.cpp 6

    The other layouts are constructed in the same way:

    \snippet widgets/widgets/lineedits/window.cpp 7

    Finally, we place each group box in a grid layout for the \c Window object
    and set the window title:

    \snippet widgets/widgets/lineedits/window.cpp 8

    The slots respond to signals emitted when the comboboxes are changed by the
    user.

    When the combobox for the \uicontrol{Echo} group box is changed, the \c echoChanged()
    slot is called:

    \snippet widgets/widgets/lineedits/window.cpp 9

    The slot updates the line edit in the same group box to use an echo mode that
    corresponds to the entry described in the combobox.

    When the combobox for the \uicontrol{Validator} group box is changed, the
    \c validatorChanged() slot is called:

    \snippet widgets/widgets/lineedits/window.cpp 10

    The slot either creates a new validator for the line edit to use, or it removes
    the validator in use by calling QLineEdit::setValidator() with a zero pointer.
    We clear the line edit in this case to ensure that the new validator is
    initially given valid input to work with.

    When the combobox for the \uicontrol{Alignment} group box is changed, the
    \c alignmentChanged() slot is called:

    \snippet widgets/widgets/lineedits/window.cpp 11

    This changes the way that text is displayed in the line edit to correspond with
    the description selected in the combobox.

    The \c inputMaskChanged() slot handles changes to the combobox in the
    \uicontrol{Input Mask} group box:

    \snippet widgets/widgets/lineedits/window.cpp 12

    Each entry in the relevant combobox is associated with an input mask. We set
    a new mask by calling the QLineEdit::setMask() function with a suitable string;
    the mask is disabled if an empty string is used.

    The \c accessChanged() slot handles changes to the combobox in the
    \uicontrol{Access} group box:

    \snippet widgets/widgets/lineedits/window.cpp 13

    Here, we simply associate the \uicontrol{False} and \uicontrol{True} entries in the combobox
    with \c false and \c true values to be passed to QLineEdit::setReadOnly(). This
    allows the user to enable and disable input to the line edit.
*/