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