Long live Qt 4.5!

1 files changed, 263 insertions, 0 deletions

diff --git a/doc/src/examples/findfiles.qdoc b/doc/src/examples/findfiles.qdoc
new file mode 100644
index 0000000..db41f43
--- /dev/null
+++ b/doc/src/examples/findfiles.qdoc
@@ -0,0 +1,263 @@
+/****************************************************************************
+**
+** 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/findfiles
+    \title Find Files Example
+
+    The Find Files example shows how to use QProgressDialog to provide
+    feedback on the progress of a slow operation. The example also
+    shows how to use QFileDialog to facilitate browsing, how to use
+    QTextStream's streaming operators to read a file, and how to use
+    QTableWidget to provide standard table display facilities for
+    applications. In addition, files can be opened using the
+    QDesktopServices class.
+
+    \image findfiles-example.png Screenshot of the Find Files example
+
+    With the Find Files application the user can search for files in a
+    specified directory, matching a specified file name (using wild
+    cards if appropiate) and containing a specified text.
+
+    The user is provided with a \gui Browse option, and the result of
+    the search is displayed in a table with the names of the files
+    found and their sizes. In addition the application provides a
+    total count of the files found.
+
+    \section1 Window Class Definition
+
+    The \c Window class inherits QWidget, and is the main application
+    widget. It shows the search options, and displays the search
+    results.
+
+    \snippet examples/dialogs/findfiles/window.h 0
+
+    We need two private slots: The \c browse() slot is called whenever
+    the user wants to browse for a directory to search in, and the \c
+    find() slot is called whenever the user requests a search to be
+    performed by pressing the \gui Find button.
+
+    In addition we declare several private functions: We use the \c
+    findFiles() function to search for files matching the user's
+    specifications, we call the \c showFiles() function to display the
+    results, and we use \c createButton(), \c createComboBox() and \c
+    createFilesTable() when we are constructing the widget.
+
+    \section1 Window Class Implementation
+
+    In the constructor we first create the application's widgets.
+
+    \snippet examples/dialogs/findfiles/window.cpp 0
+
+    We create the application's buttons using the private \c
+    createButton() function. Then we create the comboboxes associated
+    with the search specifications, using the private \c
+    createComboBox() function. We also create the application's labels
+    before we use the private \c createFilesTable() function to create
+    the table displaying the search results.
+
+    \snippet examples/dialogs/findfiles/window.cpp 1
+
+    Then we add all the widgets to a main layout using QGridLayout. We
+    have, however, put the \c Find and \c Quit buttons and a
+    stretchable space in a separate QHBoxLayout first, to make the
+    buttons appear in the \c Window widget's bottom right corner.
+
+    \snippet examples/dialogs/findfiles/window.cpp 2
+
+    The \c browse() slot presents a file dialog to the user, using the
+    QFileDialog class. QFileDialog enables a user to traverse the file
+    system in order to select one or many files or a directory. The
+    easiest way to create a QFileDialog is to use the convenience
+    static functions.
+
+    Here we use the static QFileDialog::getExistingDirectory()
+    function which returns an existing directory selected by the
+    user. Then we display the directory in the directory combobox
+    using the QComboBox::addItem() function, and updates the current
+    index.
+
+    QComboBox::addItem() adds an item to the combobox with the given
+    text (if it is not already present in the list), and containing
+    the specified userData. The item is appended to the list of
+    existing items.
+
+    \snippet examples/dialogs/findfiles/window.cpp 3
+
+    The \c find() slot is called whenever the user requests a new
+    search by pressing the \gui Find button.
+
+    First we eliminate any previous search results by setting the
+    table widgets row count to zero. Then we retrieve the
+    specified file name, text and directory path from the respective
+    comboboxes.
+
+    \snippet examples/dialogs/findfiles/window.cpp 4
+
+    We use the directory's path to create a QDir; the QDir class
+    provides access to directory structures and their contents. We
+    create a list of the files (contained in the newly created QDir)
+    that match the specified file name. If the file name is empty
+    the list will contain all the files in the directory.
+
+    Then we search through all the files in the list, using the private
+    \c findFiles() function, eliminating the ones that don't contain
+    the specified text. And finally, we display the results using the
+    private \c showFiles() function.
+
+    If the user didn't specify any text, there is no reason to search
+    through the files, and we display the results immediately.
+
+    \image findfiles_progress_dialog.png Screenshot of the Progress Dialog
+
+    \snippet examples/dialogs/findfiles/window.cpp 5
+
+    In the private \c findFiles() function we search through a list of
+    files, looking for the ones that contain a specified text. This
+    can be a very slow operation depending on the number of files as
+    well as their sizes. In case there are a large number of files, or
+    there exists some large files on the list, we provide a
+    QProgressDialog.
+
+    The QProgressDialog class provides feedback on the progress of a
+    slow operation. It is used to give the user an indication of how
+    long an operation is going to take, and to demonstrate that the
+    application has not frozen. It can also give the user an
+    opportunity to abort the operation.
+
+    \snippet examples/dialogs/findfiles/window.cpp 6
+
+    We run through the files, one at a time, and for each file we
+    update the QProgressDialog value. This property holds the current
+    amount of progress made. We also update the progress dialog's
+    label.
+
+    Then we call the QCoreApplication::processEvents() function using
+    the QApplication object. In this way we interleave the display of
+    the progress made with the process of searching through the files
+    so the application doesn't appear to be frozen.
+
+    The QApplication class manages the GUI application's control flow
+    and main settings. It contains the main event loop, where all
+    events from the window system and other sources are processed and
+    dispatched. QApplication inherits QCoreApplication.  The
+    QCoreApplication::processEvents() function processes all pending
+    events according to the specified QEventLoop::ProcessEventFlags
+    until there are no more events to process. The default flags are
+    QEventLoop::AllEvents.
+
+    \snippet examples/dialogs/findfiles/window.cpp 7
+
+    After updating the QProgressDialog, we create a QFile using the
+    QDir::absoluteFilePath() function which returns the absolute path
+    name of a file in the directory. We open the file in read-only
+    mode, and read one line at a time using QTextStream.
+
+    The QTextStream class provides a convenient interface for reading
+    and writing text. Using QTextStream's streaming operators, you can
+    conveniently read and write words, lines and numbers.
+
+    For each line we read we check if the QProgressDialog has been
+    canceled. If it has, we abort the operation, otherwise we check if
+    the line contains the specified text. When we find the text within
+    one of the files, we add the file's name to a list of found files
+    that contain the specified text, and start searching a new file.
+
+    Finally, we return the list of the files found.
+
+    \snippet examples/dialogs/findfiles/window.cpp 8
+
+    Both the \c findFiles() and \c showFiles() functions are called from
+    the \c find() slot. In the \c showFiles() function we run through
+    the provided list of file names, adding each file name to the
+    first column in the table widget and retrieving the file's size using
+    QFile and QFileInfo for the second column.
+
+    We also update the total number of files found.
+
+    \snippet examples/dialogs/findfiles/window.cpp 9
+
+    The private \c createButton() function is called from the
+    constructor. We create a QPushButton with the provided text,
+    connect it to the provided slot, and return a pointer to the
+    button.
+
+    \snippet examples/dialogs/findfiles/window.cpp 10
+
+    The private \c createComboBox() function is also called from the
+    contructor. We create a QComboBox with the given text, and make it
+    editable.
+
+    When the user enters a new string in an editable combobox, the
+    widget may or may not insert it, and it can insert it in several
+    locations, depending on the QComboBox::InsertPolicy. The default
+    policy is is QComboBox::InsertAtBottom.
+
+    Then we add the provided text to the combobox, and specify the
+    widget's size policies, before we return a pointer to the
+    combobox.
+
+    \snippet examples/dialogs/findfiles/window.cpp 11
+
+    The private \c createFilesTable() function is called from the
+    constructor. In this function we create the QTableWidget that
+    will display the search results. We set its horizontal headers and
+    their resize mode.
+
+    QTableWidget inherits QTableView which provides a default
+    model/view implementation of a table view. The
+    QTableView::horizontalHeader() function returns the table view's
+    horizontal header as a QHeaderView. The QHeaderView class provides
+    a header row or header column for item views, and the
+    QHeaderView::setResizeMode() function sets the constraints on how
+    the section in the header can be resized.
+
+    Finally, we hide the QTableWidget's vertical headers using the
+    QWidget::hide() function, and remove the default grid drawn for
+    the table using the QTableView::setShowGrid() function.
+
+    \snippet examples/dialogs/findfiles/window.cpp 12
+
+    The \c openFileOfItem() slot is invoked when the user double
+    clicks on a cell in the table. The QDesktopServices::openUrl()
+    knows how to open a file given the file name.
+*/
+