--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/completer.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,263 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 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
+ */