Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example tools/completer
++ \title Completer Example
++ \examplecategory {User Interface Components}
++ \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
++ {Application showing various options and settings}
++
++ 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 path 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 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
++ {Application showing the country list model contents}
++
++ 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
++ {Application showing the word list model contents}
++
++ 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() updates 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
++ */