qt 6.5.1 original

examples/widgets/tools/customcompleter/doc/src/customcompleter.qdoc

@@ -0,0 +1,165 @@
+// 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
+
+    \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
+
+    \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
+
+    \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
+*/