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