From 806dda08d685bc5f9ed71dfe8b61f21848d48066 Mon Sep 17 00:00:00 2001 From: Gabriel de Dietrich Date: Fri, 17 Aug 2012 13:23:19 +0200 Subject: Moving .qdoc files under examples/widgets/doc Updated those .qdoc files to refer to the new relative examples emplacement. Images and snippets to be moved later. Also grouped all widgets related examples under widgets. Change-Id: Ib29696e2d8948524537f53e8dda88f9ee26a597f Reviewed-by: J-P Nurmi --- examples/widgets/doc/findfiles.qdoc | 249 ++++++++++++++++++++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 examples/widgets/doc/findfiles.qdoc (limited to 'examples/widgets/doc/findfiles.qdoc') diff --git a/examples/widgets/doc/findfiles.qdoc b/examples/widgets/doc/findfiles.qdoc new file mode 100644 index 0000000000..594d57472c --- /dev/null +++ b/examples/widgets/doc/findfiles.qdoc @@ -0,0 +1,249 @@ +/**************************************************************************** +** +** 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/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 appropriate) and containing a specified text. + + The user is provided with a \uicontrol 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 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 \uicontrol 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 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 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 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 dialogs/findfiles/window.cpp 3 + + The \c find() slot is called whenever the user requests a new + search by pressing the \uicontrol 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 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 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 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 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 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 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 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 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 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. +*/ + -- cgit v1.2.3