diff options
Diffstat (limited to 'doc/src/examples/findfiles.qdoc')
| -rw-r--r-- | doc/src/examples/findfiles.qdoc | 249 |
1 files changed, 0 insertions, 249 deletions
diff --git a/doc/src/examples/findfiles.qdoc b/doc/src/examples/findfiles.qdoc deleted file mode 100644 index 6654070d72..0000000000 --- a/doc/src/examples/findfiles.qdoc +++ /dev/null @@ -1,249 +0,0 @@ -/**************************************************************************** -** -** 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 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 \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 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 \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 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. -*/ - |