MCL/sf/mw/qt: comparison doc/src/examples/customcompleter.qdoc

equal deleted inserted replaced

--1:000000000000
+:1918ee327afb
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\example tools/customcompleter
+\title Custom Completer Example
+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 examples/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 examples/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 examples/tools/customcompleter/textedit.cpp 0
+In addition, \c TextEdit also includes a default destructor:
+\snippet examples/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 examples/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 examples/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 examples/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 examples/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 examples/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 examples/tools/customcompleter/textedit.cpp 7
+We also handle other modifiers and shortcuts for which we do not want the
+completer to respond to.
+\snippet examples/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 examples/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 examples/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 examples/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 examples/tools/customcompleter/mainwindow.cpp 2
+The \c about() function provides a brief description about the Custom
+Completer example.
+\snippet examples/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 examples/tools/customcompleter/main.cpp 0
+*/