source: trunk/doc/src/examples/completer.qdoc

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $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 examples/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 examples/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 examples/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 examples/tools/completer/fsmodel.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 QFileSystemModel,
    the \c modeCombo is set to "Filtered Popup" and the \c caseCombo is set
    to "Case Insensitive".

    \snippet examples/tools/completer/mainwindow.cpp 0