/****************************************************************************
**
** 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 dialogs/extension
    \title Extension Example
    \ingroup examples-dialogs

    \brief 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 lets the user add search parameters in
    a dialog and launch a simple or advanced search.

    The simple search has two options: \uicontrol {Match case} and \uicontrol
    {Search from start}. The advanced search offers search for \uicontrol {Whole words},
    \uicontrol {Search backward}, and \uicontrol {Search selection}.  The
    application starts with simple search as the default. Click the \uicontrol More button
    to show the advanced search options:

    \image extension_more.png Screenshot of the Extension example

    \section1 FindDialog Class Definition

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

    \snippet 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 the constructor, there are several child widgets:

    \list
    \li A QLineEdit with an associated QLabel to let the
    user type a word to search for.
    \li Several \l {QCheckBox}{QCheckBox}es to facilitate the search options.
    \li Three \l {QPushButton}{QPushButton}s:
        \list
        \li the \uicontrol Find button to start a search
        \li the \uicontrol More button to enable an advanced search
        \li a QWidget representing the application's extension part
        \endlist
    \endlist

    \section1 FindDialog Class Implementation

    Create the standard child widgets for the simple search in the constructor:
    the QLineEdit with the associated QLabel, two {QCheckBox}es and all the
    \l {QPushButton}{QPushButton}s.

    \snippet dialogs/extension/finddialog.cpp 0

    This snippet illustrates how you can define a shortcut key
    for a widget. A shortcut should be defined by putting the ampersand
    character (\c &) in front of the letter that should
    become the shortcut.
    For example, for \uicontrol {Find what}, pressing \uicontrol Alt
    and \uicontrol w transfers focus to the QLineEdit widget.
    Shortcuts can also be used for checking on or off a checkmark.
    For example, pressing \uicontrol Alt and \uicontrol c puts the check mark
    on \uicontrol {Match Case} if it was unchecked and vice versa.
    It is the QLabel::setBuddy() method that links a widget to the shortcut
    character if it has been defined.

    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 dialogs/extension/finddialog.cpp 2

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

    \snippet dialogs/extension/finddialog.cpp 3

    Now that the extension widget is created, 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 the \uicontrol More button is checkable, the connection makes
    sure that the extension widget is shown depending on the state of
    the \uicontrol More button.

    Create checkboxes associated with the advanced search options in
    a layout installed on the extension widget.

    \snippet dialogs/extension/finddialog.cpp 4

    Before creating the main layout, create several child layouts
    for the widgets. First align the QLabel and its buddy, the
    QLineEdit, using a QHBoxLayout. Then align the QLabel and the QLineEdit
    vertically with the checkboxes associated with the simple search,
    using a QVBoxLayout. Create also a QVBoxLayout for the buttons.
    Finally, lay out the two latter layouts and the extension widget
    using a QGridLayout.

    \snippet dialogs/extension/finddialog.cpp 5

    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.
*/