qt5base-lts/examples/widgets/doc/extension.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/dialogs/extension
    \title Extension Example

    The Extension example shows how to add an extension to a QDialog
    using the QAbstractButton::toggled() signal and the
    QWidget::setVisible() slot.

    \image extension-example.png Screenshot of the Extension example

    The Extension application is a dialog that allows the user to
    perform a simple search as well as a more advanced search.

    The simple search has two options: \uicontrol {Match case} and \uicontrol
    {Search from start}. The advanced search options include the
    possibilities to search for \uicontrol {Whole words}, \uicontrol {Search
    backward} and \uicontrol {Search selection}. Only the simple search is
    visible when the application starts. The advanced search options
    are located in the application's extension part, and can be made
    visible by pressing the \uicontrol More button:

    \image extension_more.png Screenshot of the Extension example

    \section1 FindDialog Class Definition

    The \c FindDialog class inherits QDialog. The QDialog class is the
    base class of dialog windows. A dialog window is a top-level
    window mostly used for short-term tasks and brief communications
    with the user.

    \snippet widgets/dialogs/extension/finddialog.h 0

    The \c FindDialog widget is the main application widget, and
    displays the application's search options and controlling
    buttons.

    In addition to a constructor, we declare the several child
    widgets: We need a QLineEdit with an associated QLabel to let the
    user type a word to search for, we need several  \l
    {QCheckBox}{QCheckBox}es to facilitate the search options, and we
    need three \l {QPushButton}{QPushButton}s: the \uicontrol Find button to
    start a search and the \uicontrol More button to enable an advanced search.
    Finally, we need a QWidget representing the application's extension
    part.

    \section1 FindDialog Class Implementation

    In the constructor we first create the standard child widgets for
    the simple search: the QLineEdit with the associated QLabel, two
    of the \l {QCheckBox}{QCheckBox}es and all the \l
    {QPushButton}{QPushButton}s.

    \snippet widgets/dialogs/extension/finddialog.cpp 0

    We give the options and buttons a shortcut key using the &
    character. In the \uicontrol {Find what} option's case, we also need to
    use the QLabel::setBuddy() function to make the shortcut key work
    as expected; then, when the user presses the shortcut key
    indicated by the label, the keyboard focus is transferred to the
    label's buddy widget, the QLineEdit.

    We set the \uicontrol Find button's default property to true, using the
    QPushButton::setDefault() function. Then the push button will be
    pressed if the user presses the Enter (or Return) key. Note that a
    QDialog can only have one default button.

    \snippet widgets/dialogs/extension/finddialog.cpp 2

    Then we create the extension widget, and the \l
    {QCheckBox}{QCheckBox}es associated with the advanced search
    options.

    \snippet widgets/dialogs/extension/finddialog.cpp 3

    Now that the extension widget is created, we can connect the \uicontrol
    More button's \l{QAbstractButton::toggled()}{toggled()} signal to
    the extension widget's \l{QWidget::setVisible()}{setVisible()} slot.

    The QAbstractButton::toggled() signal is emitted whenever a
    checkable button changes its state. The signal's argument is true
    if the button is checked, or false if the button is unchecked. The
    QWidget::setVisible() slot sets the widget's visible status. If
    the status is true the widget is shown, otherwise the widget is
    hidden.

    Since we made the \uicontrol More button checkable when we created it,
    the connection makes sure that the extension widget is shown
    depending on the state of \uicontrol More button.

    We also put the check boxes associated with the advanced
    search options into a layout we install on the extension widget.

    \snippet widgets/dialogs/extension/finddialog.cpp 4

    Before we create the main layout, we create several child layouts
    for the widgets: First we align the QLabel and its buddy, the
    QLineEdit, using a QHBoxLayout. Then we vertically align the
    QLabel and QLineEdit with the check boxes associated with the
    simple search, using a QVBoxLayout. We also create a QVBoxLayout
    for the buttons. In the end we lay out the two latter layouts and
    the extension widget using a QGridLayout.

    \snippet widgets/dialogs/extension/finddialog.cpp 5

    Finally, we hide the extension widget using the QWidget::hide()
    function, making the application only show the simple search
    options when it starts. When the user wants to access the advanced
    search options, the dialog only needs to change the visibility of
    the extension widget. Qt's layout management takes care of the
    dialog's appearance.
*/