Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example tools/customcompleter
++ \title Custom Completer Example
++ \examplecategory {User Interface Components}
++
++
++ \ingroup examples-widgets-tools
++
++ \brief The Custom Completer example shows how to provide string-completion
++ facilities for an input widget based on data provided by a model. The
++ completer pops up suggestions for possible words based on the first three
++ characters input by the user and the user's choice of word is inserted
++ into the \c TextEdit using QTextCursor.
++
++ \image customcompleter-example.png {Text editor with the autocomplete feature}
++
++ \section1 Setting Up The Resource File
++
++ The Custom Completer example requires a resource file, \e wordlist.txt,
++ that has a list of words to help QCompleter complete words. This file
++ contains the following:
++
++ \quotefile tools/customcompleter/customcompleter.qrc
++
++ \section1 TextEdit Class Definition
++
++ The \c TextEdit class is a subclass of QTextEdit with a custom
++ \c insertCompletion() slot and it reimplements the
++ \l{QAbstractScrollArea::keyPressEvent()}{keyPressEvent()} and the
++ \l{QWidget::focusInEvent()}{focusInEvent()} functions. \c TextEdit also
++ contains a private function \c textUnderCursor() and a private instance
++ of QCompleter, \c c.
++
++ \snippet tools/customcompleter/textedit.h 0
++
++ \section1 TextEdit Class Implementation
++
++ The constructor for \c TextEdit constructs a \c TextEdit with a parent and
++ initializes \c c. The instructions to use the completer is displayed on
++ the \c TextEdit object, using the
++ \l{QTextEdit::setPlainText()}{setPlainText()} function.
++
++ \snippet tools/customcompleter/textedit.cpp 0
++
++ In addition, \c TextEdit also includes a default destructor:
++
++ \snippet tools/customcompleter/textedit.cpp 1
++
++ The \c setCompleter() function accepts a \a completer and sets it up.
++ We use \c{if (c)} to check if \c c has been initialized. If it has been
++ initialized, the QObject::disconnect() function is invoked to disconnect
++ the signal from the slot. This is to ensure that no previous completer
++ object is still connected to the slot.
++
++ \snippet tools/customcompleter/textedit.cpp 2
++
++ We then instantiate \c c with \a completer and set it as \c{TextEdit}'s
++ widget. The completion mode and case sensitivity are also set and then
++ we connect the \l{QCompleter::activated()}{activated()} signal to the
++ \c insertCompletion() slot.
++
++ The \c completer() function is a getter function that returns \c c.
++
++ \snippet tools/customcompleter/textedit.cpp 3
++
++ The completer pops up the options available, based on the contents of
++ \e wordlist.txt, but the text cursor is responsible for filling in the
++ missing characters, according to the user's choice of word.
++
++ Suppose the user inputs "ACT" and accepts the completer's suggestion of
++ "ACTUAL". The \c completion string is then sent to \c insertCompletion()
++ by the completer's \l{QCompleter::activated()}{activated()} signal.
++
++ The \c insertCompletion() function is responsible for completing the word
++ using a QTextCursor object, \c tc. It validates to ensure that the
++ completer's widget is \c TextEdit before using \c tc to insert the extra
++ characters to complete the word.
++
++ \snippet tools/customcompleter/textedit.cpp 4
++
++ The figure below illustrates this process:
++
++ \image customcompleter-insertcompletion.png
++ {Suggested completion string "ACTUAL" when user types "ACT"}
++
++ \c{completion.length()} = 6
++
++ \c{c->completionPrefix().length()}=3
++
++ The difference between these two values is \c extra, which is 3. This
++ means that the last three characters from the right, "U", "A", and "L",
++ will be inserted by \c tc.
++
++ The \c textUnderCursor() function uses a QTextCursor, \c tc, to select a
++ word under the cursor and return it.
++
++ \snippet tools/customcompleter/textedit.cpp 5
++
++ The \c TextEdit class reimplements \l{QWidget::focusInEvent()}
++ {focusInEvent()} function, which is an event handler used to receive
++ keyboard focus events for the widget.
++
++ \snippet tools/customcompleter/textedit.cpp 6
++
++ The \l{QAbstractScrollArea::keyPressEvent()}{keyPressEvent()} is
++ reimplemented to ignore key events like Qt::Key_Enter, Qt::Key_Return,
++ Qt::Key_Escape, Qt::Key_Tab, and Qt::Key_Backtab so the completer can
++ handle them.
++
++ If there is an active completer, we cannot process the shortcut, Ctrl+E.
++
++ \snippet tools/customcompleter/textedit.cpp 7
++
++ We also handle other modifiers and shortcuts for which we do not want the
++ completer to respond to.
++
++ \snippet tools/customcompleter/textedit.cpp 8
++
++ Finally, we pop up the completer.
++
++ \section1 MainWindow Class Definition
++
++ The \c MainWindow class is a subclass of QMainWindow and implements a
++ private slot, \c about(). This class also has two private functions,
++ \c createMenu() and \c modelFromFile() as well as private instances of
++ QCompleter and \c TextEdit.
++
++ \snippet tools/customcompleter/mainwindow.h 0
++
++ \section1 MainWindow Class Implementation
++
++ The constructor constructs a \c MainWindow with a parent and initializes
++ the \c completer. It also instantiates a \c TextEdit and sets its
++ completer. A QStringListModel, obtained from \c modelFromFile(), is used
++ to populate the \c completer. The \c{MainWindow}'s central widget is set
++ to \c TextEdit and its size is set to 500 x 300.
++
++ \snippet tools/customcompleter/mainwindow.cpp 0
++
++ The \c createMenu() function creates the necessary QAction objects needed
++ for the "File" and "Help" menu and their \l{QAction::triggered()}
++ {triggered()} signals are connected to the \c quit(), \c about(), and
++ \c aboutQt() slots respectively.
++
++ \snippet tools/customcompleter/mainwindow.cpp 1
++
++ The \c modelFromFile() function accepts a \a fileName and attempts to
++ extract the contents of this file into a QStringListModel. We display the
++ Qt::WaitCursor when we are populating the QStringList, \c words, and
++ restore the mouse cursor when we are done.
++
++ \snippet tools/customcompleter/mainwindow.cpp 2
++
++ The \c about() function provides a brief description about the Custom
++ Completer example.
++
++ \snippet tools/customcompleter/mainwindow.cpp 3
++
++ \section1 \c main() Function
++
++ The \c main() function instantiates \c MainWindow and invokes the
++ \l{QWidget::show()}{show()} function.
++
++ \snippet tools/customcompleter/main.cpp 0
++ */