Long live Qt 4.5!

1 files changed, 153 insertions, 0 deletions

diff --git a/doc/src/examples/extension.qdoc b/doc/src/examples/extension.qdoc
new file mode 100644
index 0000000..8a0ca3a
--- /dev/null
+++ b/doc/src/examples/extension.qdoc
@@ -0,0 +1,153 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $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: \gui {Match case} and \gui
+    {Search from start}. The advanced search options include the
+    possibilities to search for \gui {Whole words}, \gui {Search
+    backward} and \gui {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 \gui 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 examples/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 \gui Find button to
+    start a search, the \gui More button to enable an advanced search,
+    and the \gui Close button to exit the application. 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 examples/dialogs/extension/finddialog.cpp 0
+
+    We give the options and buttons a shortcut key using the &
+    character. In the \gui {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 \gui 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 examples/dialogs/extension/finddialog.cpp 2
+
+    Then we create the extension widget, and the \l
+    {QCheckBox}{QCheckBox}es associated with the advanced search
+    options.
+
+    \snippet examples/dialogs/extension/finddialog.cpp 3
+
+    Now that the extension widget is created, we can connect the \gui
+    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 \gui More button checkable when we created it,
+    the connection makes sure that the extension widget is shown
+    depending on the state of \gui More button.
+
+    We also connect the \gui Close button to the QWidget::close()
+    slot, and we put the checkboxes associated with the advanced
+    search options into a layout we install on the extension widget.
+
+    \snippet examples/dialogs/extension/finddialog.cpp 4
+
+    Before we create the main layout, we create several child layouts
+    for the widgets: First we allign the QLabel ans its buddy, the
+    QLineEdit, using a QHBoxLayout. Then we vertically allign the
+    QLabel and QLineEdit with the checkboxes 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 examples/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.
+*/