diff -r dee5afe5301f -r 3f74d0d4af4c doc/src/examples/completer.qdoc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/src/examples/completer.qdoc Thu Apr 08 14:19:33 2010 +0300 @@ -0,0 +1,263 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $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 DirModel, 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 examples/tools/completer/completer.qrc + + \section1 DirModel Class Definition + + The \c DirModel class is a subclass of QDirModel, which provides a data + model for the local filesystem. + + \snippet examples/tools/completer/dirmodel.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{QDirModel}'s \c data() function that only returns + the folder and not the drive label. This is further explained in + \c DirModel's implementation. + + \section1 DirModel Class Implementation + + The constructor for the \c DirModel class is used to pass \a parent to + QDirModel. + + \snippet examples/tools/completer/dirmodel.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 QDirModel, you will see "Program Files" in the view. However, with + \c DirModel, you will see "C:\\Program Files". + + \snippet examples/tools/completer/dirmodel.cpp 1 + + The screenshots below illustrate this difference: + + \table + \row \o \inlineimage completer-example-qdirmodel.png + \o \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 examples/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 examples/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 QDirModel, + the \c modeCombo is set to "Filtered Popup" and the \c caseCombo is set + to "Case Insensitive". + + \snippet examples/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 examples/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 examples/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 examples/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 examples/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 examples/tools/completer/mainwindow.cpp 5 + + The mouse cursor is then overriden 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 examples/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 examples/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 examples/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 examples/tools/completer/mainwindow.cpp 9 + + The \c changeMode() function sets the \c{completer}'s mode, depending on + the value of \c index. + + \snippet examples/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 QDirModel, providing + us with a file path excluding the drive label. + + \snippet examples/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 examples/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 examples/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 examples/tools/completer/mainwindow.cpp 14 + + The \c changeMaxVisible() update the maximum number of visible items in + the completer. + + \snippet examples/tools/completer/mainwindow.cpp 15 + + The \c about() function provides a brief description about the example. + + \snippet examples/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 examples/tools/completer/main.cpp 0 + */