be15856f61
Change copyrights and license headers from Nokia to Digia Change-Id: If1cc974286d29fd01ec6c19dd4719a67f4c3f00e Reviewed-by: Lars Knoll <lars.knoll@digia.com> Reviewed-by: Sergio Ahumada <sergio.ahumada@digia.com>
250 lines
9.1 KiB
Plaintext
250 lines
9.1 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
|
|
** Contact: http://www.qt-project.org/legal
|
|
**
|
|
** This file is part of the documentation of the Qt Toolkit.
|
|
**
|
|
** $QT_BEGIN_LICENSE:FDL$
|
|
** Commercial License Usage
|
|
** Licensees holding valid commercial Qt licenses may use this file in
|
|
** accordance with the commercial license agreement provided with the
|
|
** Software or, alternatively, in accordance with the terms contained in
|
|
** a written agreement between you and Digia. For licensing terms and
|
|
** conditions see http://qt.digia.com/licensing. For further information
|
|
** use the contact form at http://qt.digia.com/contact-us.
|
|
**
|
|
** GNU Free Documentation License Usage
|
|
** 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. Please review the following information to ensure
|
|
** the GNU Free Documentation License version 1.3 requirements
|
|
** will be met: http://www.gnu.org/copyleft/fdl.html.
|
|
** $QT_END_LICENSE$
|
|
**
|
|
****************************************************************************/
|
|
|
|
/*!
|
|
\example completer
|
|
\title Completer Example
|
|
|
|
The Completer example shows how to provide string-completion facilities
|
|
for an input widget based on data provided by a model.
|
|
|
|
\image completer-example.png
|
|
|
|
This example uses a custom item model, \c FileSystemModel, and a QCompleter object.
|
|
QCompleter is a class that provides completions based on an item model. The
|
|
type of model, the completion mode, and the case sensitivity can be
|
|
selected using combo boxes.
|
|
|
|
\section1 The Resource File
|
|
|
|
The Completer example requires a resource file in order to store the
|
|
\e{countries.txt} and \e{words.txt}. The resource file contains the
|
|
following code:
|
|
|
|
\quotefile completer/completer.qrc
|
|
|
|
\section1 FileSystemModel Class Definition
|
|
|
|
The \c FileSystemModel class is a subclass of QFileSystemModel, which provides a data
|
|
model for the local filesystem.
|
|
|
|
\snippet completer/fsmodel.h 0
|
|
|
|
This class only has a constructor and a \c data() function as it is only
|
|
created to enable \c data() to return the entire file path for the
|
|
display role, unlike \l{QFileSystemModel}'s \c data() function that only returns
|
|
the folder and not the drive label. This is further explained in
|
|
\c FileSystemModel's implementation.
|
|
|
|
\section1 FileSystemModel Class Implementation
|
|
|
|
The constructor for the \c FileSystemModel class is used to pass \a parent to
|
|
QFileSystemModel.
|
|
|
|
\snippet completer/fsmodel.cpp 0
|
|
|
|
As mentioned earlier, the \c data() function is reimplemented in order to
|
|
get it to return the entire file parth for the display role. For example,
|
|
with a QFileSystemModel, you will see "Program Files" in the view. However, with
|
|
\c FileSystemModel, you will see "C:\\Program Files".
|
|
|
|
\snippet completer/fsmodel.cpp 1
|
|
|
|
The screenshots below illustrate this difference:
|
|
|
|
\table
|
|
\row \li \inlineimage completer-example-qdirmodel.png
|
|
\li \inlineimage completer-example-dirmodel.png
|
|
\endtable
|
|
|
|
The Qt::EditRole, which QCompleter uses to look for matches, is left
|
|
unchanged.
|
|
|
|
\section1 MainWindow Class Definition
|
|
|
|
The \c MainWindow class is a subclass of QMainWindow and implements five
|
|
private slots - \c about(), \c changeCase(), \c changeMode(), \c changeModel(),
|
|
and \c changeMaxVisible().
|
|
|
|
\snippet completer/mainwindow.h 0
|
|
|
|
Within the \c MainWindow class, we have two private functions:
|
|
\c createMenu() and \c modelFromFile(). We also declare the private widgets
|
|
needed - three QComboBox objects, a QCheckBox, a QCompleter, a QLabel, and
|
|
a QLineEdit.
|
|
|
|
\snippet completer/mainwindow.h 1
|
|
|
|
\section1 MainWindow Class Implementation
|
|
|
|
The constructor of \c MainWindow constructs a \c MainWindow with a parent
|
|
widget and initializes the private members. The \c createMenu() function
|
|
is then invoked.
|
|
|
|
We set up three QComboBox objects, \c modelComb, \c modeCombo and
|
|
\c caseCombo. By default, the \c modelCombo is set to QFileSystemModel,
|
|
the \c modeCombo is set to "Filtered Popup" and the \c caseCombo is set
|
|
to "Case Insensitive".
|
|
|
|
\snippet completer/mainwindow.cpp 0
|
|
|
|
The \c maxVisibleSpinBox is created and determines the number of visible
|
|
item in the completer
|
|
|
|
The \c wrapCheckBox is then set up. This \c checkBox determines if the
|
|
\c{completer}'s \l{QCompleter::setWrapAround()}{setWrapAround()} property
|
|
is enabled or disabled.
|
|
|
|
\snippet completer/mainwindow.cpp 1
|
|
|
|
We instantiate \c contentsLabel and set its size policy to
|
|
\l{QSizePolicy::Fixed}{fixed}. The combo boxes' \l{QComboBox::activated()}
|
|
{activated()} signals are then connected to their respective slots.
|
|
|
|
\snippet completer/mainwindow.cpp 2
|
|
|
|
The \c lineEdit is set up and then we arrange all the widgets using a
|
|
QGridLayout. The \c changeModel() function is called, to initialize the
|
|
\c completer.
|
|
|
|
\snippet completer/mainwindow.cpp 3
|
|
|
|
The \c createMenu() function is used to instantiate the QAction objects
|
|
needed to fill the \c fileMenu and \c helpMenu. The actions'
|
|
\l{QAction::triggered()}{triggered()} signals are connected to their
|
|
respective slots.
|
|
|
|
\snippet completer/mainwindow.cpp 4
|
|
|
|
The \c modelFromFile() function accepts the \a fileName of a file and
|
|
processes it depending on its contents.
|
|
|
|
We first validate the \c file to ensure that it can be opened in
|
|
QFile::ReadOnly mode. If this is unsuccessful, the function returns an
|
|
empty QStringListModel.
|
|
|
|
\snippet completer/mainwindow.cpp 5
|
|
|
|
The mouse cursor is then overridden with Qt::WaitCursor before we fill
|
|
a QStringList object, \c words, with the contents of \c file. Once this
|
|
is done, we restore the mouse cursor.
|
|
|
|
\snippet completer/mainwindow.cpp 6
|
|
|
|
As mentioned earlier, the resources file contains two files -
|
|
\e{countries.txt} and \e{words.txt}. If the \c file read is \e{words.txt},
|
|
we return a QStringListModel with \c words as its QStringList and
|
|
\c completer as its parent.
|
|
|
|
\snippet completer/mainwindow.cpp 7
|
|
|
|
If the \c file read is \e{countries.txt}, then we require a
|
|
QStandardItemModel with \c words.count() rows, 2 columns, and \c completer
|
|
as its parent.
|
|
|
|
\snippet completer/mainwindow.cpp 8
|
|
|
|
A standard line in \e{countries.txt} is:
|
|
\quotation
|
|
Norway NO
|
|
\endquotation
|
|
|
|
Hence, to populate the QStandardItemModel object, \c m, we have to
|
|
split the country name and its symbol. Once this is done, we return
|
|
\c m.
|
|
|
|
\snippet completer/mainwindow.cpp 9
|
|
|
|
The \c changeMode() function sets the \c{completer}'s mode, depending on
|
|
the value of \c index.
|
|
|
|
\snippet completer/mainwindow.cpp 10
|
|
|
|
The \c changeModel() function changes the item model used based on the
|
|
model selected by the user.
|
|
|
|
A \c switch statement is used to change the item model based on the index
|
|
of \c modelCombo. If \c case is 0, we use an unsorted QFileSystemModel, providing
|
|
us with a file path excluding the drive label.
|
|
|
|
\snippet completer/mainwindow.cpp 11
|
|
|
|
Note that we create the model with \c completer as the parent as this
|
|
allows us to replace the model with a new model. The \c completer will
|
|
ensure that the old one is deleted the moment a new model is assigned
|
|
to it.
|
|
|
|
If \c case is 1, we use the \c DirModel we defined earlier, resulting in
|
|
full paths for the files.
|
|
|
|
\snippet completer/mainwindow.cpp 12
|
|
|
|
When \c case is 2, we attempt to complete names of countries. This requires
|
|
a QTreeView object, \c treeView. The country names are extracted from
|
|
\e{countries.txt} and set the popup used to display completions to
|
|
\c treeView.
|
|
|
|
\snippet completer/mainwindow.cpp 13
|
|
|
|
The screenshot below shows the Completer with the country list model.
|
|
|
|
\image completer-example-country.png
|
|
|
|
If \c case is 3, we attempt to complete words. This is done using a
|
|
QStringListModel that contains data extracted from \e{words.txt}. The
|
|
model is sorted \l{QCompleter::CaseInsensitivelySortedModel}
|
|
{case insensitively}.
|
|
|
|
The screenshot below shows the Completer with the word list model.
|
|
|
|
\image completer-example-word.png
|
|
|
|
Once the model type is selected, we call the \c changeMode() function and
|
|
the \c changeCase() function and set the wrap option accordingly. The
|
|
\c{wrapCheckBox}'s \l{QCheckBox::clicked()}{clicked()} signal is connected
|
|
to the \c{completer}'s \l{QCompleter::setWrapAround()}{setWrapAround()}
|
|
slot.
|
|
|
|
\snippet completer/mainwindow.cpp 14
|
|
|
|
The \c changeMaxVisible() update the maximum number of visible items in
|
|
the completer.
|
|
|
|
\snippet completer/mainwindow.cpp 15
|
|
|
|
The \c about() function provides a brief description about the example.
|
|
|
|
\snippet completer/mainwindow.cpp 16
|
|
|
|
\section1 \c main() Function
|
|
|
|
The \c main() function instantiates QApplication and \c MainWindow and
|
|
invokes the \l{QWidget::show()}{show()} function.
|
|
|
|
\snippet completer/main.cpp 0
|
|
*/
|