| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** 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. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \example tools/completer |
| \title Completer Example |
| \ingroup examples-widgets-tools |
| |
| \brief 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 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 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 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 tools/completer/fsmodel.cpp 1 |
| |
| The screenshots below illustrate this difference: |
| |
| \table |
| \row \li \inlineimage completer-example-qdirmodel.png |
| \li \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 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 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 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 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 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 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 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 tools/completer/mainwindow.cpp 5 |
| |
| The mouse cursor is then overridden 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 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 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 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 tools/completer/mainwindow.cpp 9 |
| |
| The \c changeMode() function sets the \c{completer}'s mode, depending on |
| the value of \c index. |
| |
| \snippet 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 QFileSystemModel, providing |
| us with a file path excluding the drive label. |
| |
| \snippet 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 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 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 tools/completer/mainwindow.cpp 14 |
| |
| The \c changeMaxVisible() update the maximum number of visible items in |
| the completer. |
| |
| \snippet tools/completer/mainwindow.cpp 15 |
| |
| The \c about() function provides a brief description about the example. |
| |
| \snippet 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 tools/completer/main.cpp 0 |
| */ |