diff options
Diffstat (limited to 'examples/widgets/doc/src/extension.qdoc')
| -rw-r--r-- | examples/widgets/doc/src/extension.qdoc | 138 |
1 files changed, 138 insertions, 0 deletions
diff --git a/examples/widgets/doc/src/extension.qdoc b/examples/widgets/doc/src/extension.qdoc new file mode 100644 index 0000000000..040d5d38d9 --- /dev/null +++ b/examples/widgets/doc/src/extension.qdoc @@ -0,0 +1,138 @@ +/**************************************************************************** +** +** 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 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 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 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 dialogs/extension/finddialog.cpp 2 + + Then we 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, 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 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 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. +*/ |