/****************************************************************************

**

** 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

    */