diff options
Diffstat (limited to 'examples/widgets/doc/src/completer.qdoc')
| -rw-r--r-- | examples/widgets/doc/src/completer.qdoc | 249 |
1 files changed, 249 insertions, 0 deletions
diff --git a/examples/widgets/doc/src/completer.qdoc b/examples/widgets/doc/src/completer.qdoc new file mode 100644 index 0000000000..39be735245 --- /dev/null +++ b/examples/widgets/doc/src/completer.qdoc @@ -0,0 +1,249 @@ +/**************************************************************************** +** +** 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 tools/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 tools/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 tools/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 tools/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 tools/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 tools/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 tools/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 tools/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 tools/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 tools/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 tools/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 tools/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 tools/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 tools/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 tools/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 tools/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 tools/completer/mainwindow.cpp 9 + + The \c changeMode() function sets the \c{completer}'s mode, depending on + the value of \c index. + + \snippet tools/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 tools/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 tools/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 tools/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 tools/completer/mainwindow.cpp 14 + + The \c changeMaxVisible() update the maximum number of visible items in + the completer. + + \snippet tools/completer/mainwindow.cpp 15 + + The \c about() function provides a brief description about the example. + + \snippet tools/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 tools/completer/main.cpp 0 + */ |