From f2162d04d23acd27ee641a07286f30f5581fe6bf Mon Sep 17 00:00:00 2001 From: Nico Vertriest Date: Tue, 5 Mar 2013 12:37:37 +0100 Subject: Doc: fixed snippet issues with customcompleter.qdoc Edited customcompleter.qdoc (paths snippets + ingroup statement) Moved customcompleter.qdoc to widgets/tools/customcompleter/doc/src Moved png files to doc/qtwidgets/images Task-number: QTBUG-29101 Change-Id: Iab66f178b92321257c4eb0e4e9704bb1e3043ef6 Reviewed-by: Jerome Pasion Reviewed-by: Laszlo Papp --- examples/tools/doc/src/customcompleter.qdoc | 187 -------------------- .../customcompleter/doc/src/customcompleter.qdoc | 189 +++++++++++++++++++++ 2 files changed, 189 insertions(+), 187 deletions(-) delete mode 100644 examples/tools/doc/src/customcompleter.qdoc create mode 100644 examples/widgets/tools/customcompleter/doc/src/customcompleter.qdoc (limited to 'examples') diff --git a/examples/tools/doc/src/customcompleter.qdoc b/examples/tools/doc/src/customcompleter.qdoc deleted file mode 100644 index f9ad3a43e9..0000000000 --- a/examples/tools/doc/src/customcompleter.qdoc +++ /dev/null @@ -1,187 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/legal -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example customcompleter - \title Custom Completer Example - - \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 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 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 customcompleter/textedit.cpp 0 - - In addition, \c TextEdit also includes a default destructor: - - \snippet 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 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 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 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 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 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 customcompleter/textedit.cpp 7 - - We also handle other modifiers and shortcuts for which we do not want the - completer to respond to. - - \snippet 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 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 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 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 customcompleter/mainwindow.cpp 2 - - The \c about() function provides a brief description about the Custom - Completer example. - - \snippet customcompleter/mainwindow.cpp 3 - - \section1 \c main() Function - - The \c main() function instantiates \c MainWindow and invokes the - \l{QWidget::show()}{show()} function. - - \snippet customcompleter/main.cpp 0 -*/ diff --git a/examples/widgets/tools/customcompleter/doc/src/customcompleter.qdoc b/examples/widgets/tools/customcompleter/doc/src/customcompleter.qdoc new file mode 100644 index 0000000000..a6c425d4c8 --- /dev/null +++ b/examples/widgets/tools/customcompleter/doc/src/customcompleter.qdoc @@ -0,0 +1,189 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \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 +*/ -- cgit v1.2.3