diff options
Diffstat (limited to 'examples/tools/doc/src')
| -rw-r--r-- | examples/tools/doc/src/customcompleter.qdoc | 187 | ||||
| -rw-r--r-- | examples/tools/doc/src/customtype.qdoc | 143 |
2 files changed, 330 insertions, 0 deletions
diff --git a/examples/tools/doc/src/customcompleter.qdoc b/examples/tools/doc/src/customcompleter.qdoc new file mode 100644 index 0000000000..98a95e47a4 --- /dev/null +++ b/examples/tools/doc/src/customcompleter.qdoc @@ -0,0 +1,187 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example 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 +*/ diff --git a/examples/tools/doc/src/customtype.qdoc b/examples/tools/doc/src/customtype.qdoc new file mode 100644 index 0000000000..b2f86d6890 --- /dev/null +++ b/examples/tools/doc/src/customtype.qdoc @@ -0,0 +1,143 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/customtype + \title Custom Type Example + + The Custom Type example shows how to integrate a custom type into Qt's + meta-object system. + + Contents: + + \tableofcontents + + \section1 Overview + + Qt provides a range of standard value types that are used to provide + rich and meaningful APIs. These types are integrated with the meta-object + system, enabling them to be stored in QVariant objects, written out in + debugging information and sent between components in signal-slot + communication. + + Custom types can also be integrated with the meta-object system as long as + they are written to conform to some simple guidelines. In this example, we + introduce a simple \c Message class, we describe how we make it work with + QVariant, and we show how it can be extended to generate a printable + representation of itself for use in debugging output. + + \section1 The Message Class Definition + + The \c Message class is a simple value class that contains two pieces + of information (a QString and a QStringList), each of which can be read + using trivial getter functions: + + \snippet examples/tools/customtype/message.h custom type definition + + The default constructor, copy constructor and destructor are + all required, and must be public, if the type is to be integrated into the + meta-object system. Other than this, we are free to implement whatever we + need to make the type do what we want, so we also include a constructor + that lets us set the type's data members. + + To enable the type to be used with QVariant, we declare it using the + Q_DECLARE_METATYPE() macro: + + \snippet examples/tools/customtype/message.h custom type meta-type declaration + + We do not need to write any additional code to accompany this macro. + + To allow us to see a readable description of each \c Message object when it + is sent to the debug output stream, we define a streaming operator: + + \snippet examples/tools/customtype/message.h custom type streaming operator + + This facility is useful if you need to insert tracing statements in your + code for debugging purposes. + + \section1 The Message Class Implementation + + The implementation of the default constructor, copy constructor and destructor + are straightforward for the \c Message class: + + \snippet examples/tools/customtype/message.cpp Message class implementation + + The streaming operator is implemented in the following way: + + \snippet examples/tools/customtype/message.cpp custom type streaming operator + + Here, we want to represent each value depending on how many lines are stored + in the message body. We stream text to the QDebug object passed to the + operator and return the QDebug object obtained from its maybeSpace() member + function; this is described in more detail in the + \l{Creating Custom Qt Types#Making the Type Printable}{Creating Custom Qt Types} + document. + + We include the code for the getter functions for completeness: + + \snippet examples/tools/customtype/message.cpp getter functions + + With the type fully defined, implemented, and integrated with the + meta-object system, we can now use it. + + \section1 Using the Message + + In the example's \c{main()} function, we show how a \c Message object can + be printed to the console by sending it to the debug stream: + + \snippet examples/tools/customtype/main.cpp printing a custom type + + You can use the type with QVariant in exactly the same way as you would + use standard Qt value types. Here's how to store a value using the + QVariant::setValue() function: + + \snippet examples/tools/customtype/main.cpp storing a custom value + + Alternatively, the QVariant::fromValue() and qVariantSetValue() functions + can be used if you are using a compiler without support for member template + functions. + + The value can be retrieved using the QVariant::value() member template + function: + + \snippet examples/tools/customtype/main.cpp retrieving a custom value + + Alternatively, the qVariantValue() template function can be used if + you are using a compiler without support for member template functions. + + \section1 Further Reading + + The custom \c Message type can also be used with direct signal-slot + connections; see the \l{Custom Type Sending Example} for a demonstration + of this. + To register a custom type for use with queued signals and slots, such as + those used in cross-thread communication, see the + \l{Queued Custom Type Example}. + + More information on using custom types with Qt can be found in the + \l{Creating Custom Qt Types} document. +*/ |