1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \example tools/completer

    44     \title Completer Example

    45 

    46     The Completer example shows how to provide string-completion facilities

    47     for an input widget based on data provided by a model.

    48 

    49     \image completer-example.png

    50 

    51     This example uses a custom item model, \c DirModel, and a QCompleter object.

    52     QCompleter is a class that provides completions based on an item model. The

    53     type of model, the completion mode, and the case sensitivity can be

    54     selected using combo boxes.

    55 

    56     \section1 The Resource File

    57 

    58     The Completer example requires a resource file in order to store the

    59     \e{countries.txt} and \e{words.txt}. The resource file contains the

    60     following code:

    61 

    62     \quotefile examples/tools/completer/completer.qrc

    63 

    64     \section1 DirModel Class Definition

    65 

    66     The \c DirModel class is a subclass of QDirModel, which provides a data

    67     model for the local filesystem.

    68 

    69     \snippet examples/tools/completer/dirmodel.h 0

    70 

    71     This class only has a constructor and a \c data() function as it is only

    72     created to enable \c data() to return the entire file path for the

    73     display role, unlike \l{QDirModel}'s \c data() function that only returns

    74     the folder and not the drive label. This is further explained in

    75     \c DirModel's implementation.

    76 

    77     \section1 DirModel Class Implementation

    78 

    79     The constructor for the \c DirModel class is used to pass \a parent to

    80     QDirModel.

    81 

    82     \snippet examples/tools/completer/dirmodel.cpp 0

    83 

    84     As mentioned earlier, the \c data() function is reimplemented in order to

    85     get it to return the entire file parth for the display role. For example,

    86     with a QDirModel, you will see "Program Files" in the view. However, with

    87     \c DirModel, you will see "C:\\Program Files".

    88 

    89     \snippet examples/tools/completer/dirmodel.cpp 1

    90 

    91     The screenshots below illustrate this difference:

    92 

    93     \table

    94     \row \o \inlineimage completer-example-qdirmodel.png

    95          \o \inlineimage completer-example-dirmodel.png

    96     \endtable

    97 

    98     The Qt::EditRole, which QCompleter uses to look for matches, is left

    99     unchanged.

   100 

   101     \section1 MainWindow Class Definition

   102 

   103     The \c MainWindow class is a subclass of QMainWindow and implements five

   104     private slots - \c about(), \c changeCase(), \c changeMode(), \c changeModel(),

   105     and \c changeMaxVisible().

   106 

   107     \snippet examples/tools/completer/mainwindow.h 0

   108 

   109     Within the \c MainWindow class, we have two private functions:

   110     \c createMenu() and \c modelFromFile(). We also declare the private widgets

   111     needed - three QComboBox objects, a QCheckBox, a QCompleter, a QLabel, and

   112     a QLineEdit.

   113 

   114     \snippet examples/tools/completer/mainwindow.h 1

   115 

   116     \section1 MainWindow Class Implementation

   117 

   118     The constructor of \c MainWindow constructs a \c MainWindow with a parent

   119     widget and initializes the private members. The \c createMenu() function

   120     is then invoked.

   121 

   122     We set up three QComboBox objects, \c modelComb, \c modeCombo and

   123     \c caseCombo. By default, the \c modelCombo is set to QDirModel,

   124     the \c modeCombo is set to "Filtered Popup" and the \c caseCombo is set

   125     to "Case Insensitive".

   126 

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

   128 

   129     The \c maxVisibleSpinBox is created and determines the number of visible

   130     item in the completer

   131 

   132     The \c wrapCheckBox is then set up. This \c checkBox determines if the

   133     \c{completer}'s \l{QCompleter::setWrapAround()}{setWrapAround()} property

   134     is enabled or disabled.

   135 

   136     \snippet examples/tools/completer/mainwindow.cpp 1

   137 

   138     We instantiate \c contentsLabel and set its size policy to

   139     \l{QSizePolicy::Fixed}{fixed}. The combo boxes' \l{QComboBox::activated()}

   140     {activated()} signals are then connected to their respective slots.

   141 

   142     \snippet examples/tools/completer/mainwindow.cpp 2

   143 

   144     The \c lineEdit is set up and then we arrange all the widgets using a

   145     QGridLayout. The \c changeModel() function is called, to initialize the

   146     \c completer.

   147 

   148     \snippet examples/tools/completer/mainwindow.cpp 3

   149 

   150     The \c createMenu() function is used to instantiate the QAction objects

   151     needed to fill the \c fileMenu and \c helpMenu. The actions'

   152     \l{QAction::triggered()}{triggered()} signals are connected to their

   153     respective slots.

   154 

   155     \snippet examples/tools/completer/mainwindow.cpp 4

   156 

   157     The \c modelFromFile() function accepts the \a fileName of a file and

   158     processes it depending on its contents.

   159 

   160     We first validate the \c file to ensure that it can be opened in

   161     QFile::ReadOnly mode. If this is unsuccessful, the function returns an

   162     empty QStringListModel.

   163 

   164     \snippet examples/tools/completer/mainwindow.cpp 5

   165 

   166     The mouse cursor is then overriden with Qt::WaitCursor before we fill

   167     a QStringList object, \c words, with the contents of \c file. Once this

   168     is done, we restore the mouse cursor.

   169 

   170     \snippet examples/tools/completer/mainwindow.cpp 6

   171 

   172     As mentioned earlier, the resources file contains two files -

   173     \e{countries.txt} and \e{words.txt}. If the \c file read is \e{words.txt},

   174     we return a QStringListModel with \c words as its QStringList and

   175     \c completer as its parent.

   176 

   177     \snippet examples/tools/completer/mainwindow.cpp 7

   178 

   179     If the \c file read is \e{countries.txt}, then we require a

   180     QStandardItemModel with \c words.count() rows, 2 columns, and \c completer

   181     as its parent.

   182 

   183     \snippet examples/tools/completer/mainwindow.cpp 8

   184 

   185     A standard line in \e{countries.txt} is:

   186     \quotation

   187         Norway                          NO

   188     \endquotation

   189 

   190     Hence, to populate the QStandardItemModel object, \c m, we have to

   191     split the country name and its symbol. Once this is done, we return

   192     \c m.

   193 

   194     \snippet examples/tools/completer/mainwindow.cpp 9

   195 

   196     The \c changeMode() function sets the \c{completer}'s mode, depending on

   197     the value of \c index.

   198 

   199     \snippet examples/tools/completer/mainwindow.cpp 10

   200 

   201     The \c changeModel() function changes the item model used based on the

   202     model selected by the user.

   203 

   204     A \c switch statement is used to change the item model based on the index

   205     of \c modelCombo. If \c case is 0, we use an unsorted QDirModel, providing

   206     us with a file path excluding the drive label.

   207 

   208     \snippet examples/tools/completer/mainwindow.cpp 11

   209 

   210     Note that we create the model with \c completer as the parent as this

   211     allows us to replace the model with a new model. The \c completer will

   212     ensure that the old one is deleted the moment a new model is assigned

   213     to it.

   214 

   215     If \c case is 1, we use the \c DirModel we defined earlier, resulting in

   216     full paths for the files.

   217 

   218     \snippet examples/tools/completer/mainwindow.cpp 12

   219 

   220     When \c case is 2, we attempt to complete names of countries. This requires

   221     a QTreeView object, \c treeView. The country names are extracted from

   222     \e{countries.txt} and set the popup used to display completions to

   223     \c treeView.

   224 

   225     \snippet examples/tools/completer/mainwindow.cpp 13

   226 

   227     The screenshot below shows the Completer with the country list model.

   228 

   229     \image completer-example-country.png

   230 

   231     If \c case is 3, we attempt to complete words. This is done using a

   232     QStringListModel that contains data extracted from \e{words.txt}. The

   233     model is sorted \l{QCompleter::CaseInsensitivelySortedModel}

   234     {case insensitively}.

   235 

   236     The screenshot below shows the Completer with the word list model.

   237 

   238     \image completer-example-word.png

   239 

   240     Once the model type is selected, we call the \c changeMode() function and

   241     the \c changeCase() function and set the wrap option accordingly. The

   242     \c{wrapCheckBox}'s \l{QCheckBox::clicked()}{clicked()} signal is connected

   243     to the \c{completer}'s \l{QCompleter::setWrapAround()}{setWrapAround()}

   244     slot.

   245 

   246     \snippet examples/tools/completer/mainwindow.cpp 14

   247 

   248     The \c changeMaxVisible() update the maximum number of visible items in

   249     the completer.

   250 

   251     \snippet examples/tools/completer/mainwindow.cpp 15

   252 

   253     The \c about() function provides a brief description about the example.

   254 

   255     \snippet examples/tools/completer/mainwindow.cpp 16

   256 

   257     \section1 \c main() Function

   258 

   259     The \c main() function instantiates QApplication and \c MainWindow and

   260     invokes the \l{QWidget::show()}{show()} function.

   261 

   262     \snippet examples/tools/completer/main.cpp 0

   263     */