diff options
Diffstat (limited to 'doc/src/examples/treemodelcompleter.qdoc')
| -rw-r--r-- | doc/src/examples/treemodelcompleter.qdoc | 171 |
1 files changed, 171 insertions, 0 deletions
diff --git a/doc/src/examples/treemodelcompleter.qdoc b/doc/src/examples/treemodelcompleter.qdoc new file mode 100644 index 0000000000..6e9840a476 --- /dev/null +++ b/doc/src/examples/treemodelcompleter.qdoc @@ -0,0 +1,171 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/treemodelcompleter + \title Tree Model Completer Example + + The Tree Model Completer example shows how to provide completion + facilities for a hierarchical model, using a period as the separator + to access Child, GrandChild and GrandGrandChild level objects. + + \image treemodelcompleter-example.png + + Similar to the \l{Completer Example}, we provide QComboBox objects to + enable selection for completion mode and case sensitivity, as well as + a QCheckBox for wrap completions. + + \section1 The Resource File + + The contents of the TreeModelCompleter is read from \e treemodel.txt. + This file is embedded within the \e treemodelcompleter.qrc resource file, + which contains the following: + + \quotefile examples/tools/treemodelcompleter/treemodelcompleter.qrc + + \section1 TreeModelCompleter Class Definition + + The \c TreeModelCompleter is a subclass of QCompleter with two + constructors - one with \a parent as an argument and another with + \a parent and \a model as arguments. + + \snippet examples/tools/treemodelcompleter/treemodelcompleter.h 0 + + The class reimplements the protected functions + \l{QCompleter::splitPath()}{splitPath()} and + \l{QCompleter::pathFromIndex()}{pathFromIndex()} to suit a tree model. + For more information on customizing QCompleter to suit tree models, refer + to \l{QCompleter#Handling Tree Models}{Handling Tree Models}. + + \c TreeModelCompleter also has a separator property which is declared + using the Q_PROPERTY() macro. The separator has READ and WRITE attributes + and the corresponding functions \c separator() and \c setSeparator(). For + more information on Q_PROPERTY(), refer to \l{Qt's Property System}. + + \section1 TreeModelCompleter Class Implementation + + The first constructor constructs a \c TreeModelCompleter object with a + parent while the second constructor constructs an object with a parent + and a QAbstractItemModel, \a model. + + \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 0 + \codeline + \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 1 + + The \c separator() function is a getter function that returns the + separator string. + + \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 2 + + As mentioned earlier, the \c splitPath() function is reimplemented because + the default implementation is more suited to QDirModel or list models. In + order for QCompleter to split the path into a list of strings that are + matched at each level, we split it using QString::split() with \c sep as its + separator. + + \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 3 + + The \c pathFromIndex() function returns data for the completionRole() for a + tree model. This function is reimplemented as its default implementation is + more suitable for list models. If there is no separator, we use + \l{QCompleter}'s default implementation, otherwise we use the + \l{QStringList::prepend()}{prepend()} function to navigate upwards and + accumulate the data. The function then returns a QStringList, \c dataList, + using a separator to join objects of different levels. + + \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 4 + + \section1 MainWindow Class Definition + + The \c MainWindow class is a subclass of QMainWindow and implements five + custom slots: \c about(), \c changeCase(), \c changeMode(), + \c highlight(), and \c updateContentsLabel(). + + \snippet examples/tools/treemodelcompleter/mainwindow.h 0 + + In addition, the class has two private functions, \c createMenu() and + \c modelFromFile(), as well as private instances of QTreeView, QComboBox, + QLabel, \c TreeModelCompleter and QLineEdit. + + \snippet examples/tools/treemodelcompleter/mainwindow.h 1 + + \section1 MainWindow Class Implementation + + The \c{MainWindow}'s constructor creates a \c MainWindow object with a + parent and initializes the \c completer and \c lineEdit. The + \c createMenu() function is invoked to set up the "File" menu and "Help" + menu. The \c{completer}'s model is set to the QAbstractItemModel obtained + from \c modelFromFile(), and the \l{QCompleter::highlighted()} + {highlighted()} signal is connected to \c{MainWindow}'s \c highlight() + slot. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 0 + + The QLabel objects \c modelLabel, \c modeLabel and \c caseLabel are + instantiated. Also, the QComboBox objects, \c modeCombo and \c caseCombo, + are instantiated and populated. By default, the \c{completer}'s mode is + "Filtered Popup" and the case is insensitive. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 1 + \codeline + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 2 + + We use a QGridLayout to place all the objects in the \c MainWindow. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 3 + + The \c createMenu() function sets up the QAction objects required and + adds them to the "File" menu and "Help" menu. The + \l{QAction::triggered()}{triggered()} signals from these actions are + connected to their respective slots. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 4 + + The \c changeMode() function accepts an \a index corresponding to the + user's choice of completion mode and changes the \c{completer}'s mode + accordingly. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 5 + + The \c about() function provides a brief description on the Tree Model + Completer example. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 6 + + The \c changeCase() function alternates between \l{Qt::CaseSensitive} + {Case Sensitive} and \l{Qt::CaseInsensitive}{Case Insensitive} modes, + depending on the value of \a cs. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 7 + + \section1 \c main() Function + + The \c main() function instantiates \c MainWindow and invokes the + \l{QWidget::show()}{show()} function to display it. + + \snippet examples/tools/treemodelcompleter/main.cpp 0 +*/ |