fc924ae47e
Widget examples were moved into a widgets subfolder, but qdoc references were not updated. Change-Id: Id2a4573e723745b9827c664c852807d6116f8f6d Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com>
250 lines
10 KiB
Plaintext
250 lines
10 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** 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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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.
|
|
*/
|
|
|