doc/src/examples/treemodelcompleter.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example tools/treemodelcompleter
  30     \title Tree Model Completer Example
  31
  32     \brief The Tree Model Completer example shows how to provide completion
  33     facilities for a hierarchical model, using a period as the separator
  34     to access Child, GrandChild and GrandGrandChild level objects.
  35
  36     \image treemodelcompleter-example.png
  37
  38     Similar to the \l{Completer Example}, we provide QComboBox objects to
  39     enable selection for completion mode and case sensitivity, as well as
  40     a QCheckBox for wrap completions.
  41
  42     \section1 The Resource File
  43
  44     The contents of the TreeModelCompleter is read from \e treemodel.txt.
  45     This file is embedded within the \e treemodelcompleter.qrc resource file,
  46     which contains the following:
  47
  48     \quotefile examples/tools/treemodelcompleter/treemodelcompleter.qrc
  49
  50     \section1 TreeModelCompleter Class Definition
  51
  52     The \c TreeModelCompleter is a subclass of QCompleter with two
  53     constructors - one with \a parent as an argument and another with
  54     \a parent and \a model as arguments.
  55
  56     \snippet examples/tools/treemodelcompleter/treemodelcompleter.h 0
  57
  58     The class reimplements the protected functions
  59     \l{QCompleter::splitPath()}{splitPath()}  and
  60     \l{QCompleter::pathFromIndex()}{pathFromIndex()} to suit a tree model.
  61     For more information on customizing QCompleter to suit tree models, refer
  62     to \l{QCompleter#Handling Tree Models}{Handling Tree Models}.
  63
  64     \c TreeModelCompleter also has a separator property which is declared
  65     using the Q_PROPERTY() macro. The separator has READ and WRITE attributes
  66     and the corresponding functions \c separator() and \c setSeparator(). For
  67     more information on Q_PROPERTY(), refer to \l{Qt's Property System}.
  68
  69     \section1 TreeModelCompleter Class Implementation
  70
  71     The first constructor constructs a \c TreeModelCompleter object with a
  72     parent while the second constructor constructs an object with a parent
  73     and a QAbstractItemModel, \a model.
  74
  75     \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 0
  76     \codeline
  77     \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 1
  78
  79     The \c separator() function is a getter function that returns the
  80     separator string.
  81
  82     \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 2
  83
  84     As mentioned earlier, the \c splitPath() function is reimplemented because
  85     the default implementation is more suited to QDirModel or list models. In
  86     order for QCompleter to split the path into a list of strings that are
  87     matched at each level, we split it using QString::split() with \c sep as its
  88     separator.
  89
  90     \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 3
  91
  92     The \c pathFromIndex() function returns data for the completionRole() for a
  93     tree model. This function is reimplemented as its default implementation is
  94     more suitable for list models. If there is no separator, we use
  95     \l{QCompleter}'s default implementation, otherwise we use the
  96     \l{QStringList::prepend()}{prepend()} function to navigate upwards and
  97     accumulate the data. The function then returns a QStringList, \c dataList,
  98     using a separator to join objects of different levels.
  99
 100     \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 4
 101
 102     \section1 MainWindow Class Definition
 103
 104     The \c MainWindow class is a subclass of QMainWindow and implements five
 105     custom slots: \c about(), \c changeCase(), \c changeMode(),
 106     \c highlight(), and \c updateContentsLabel().
 107
 108     \snippet examples/tools/treemodelcompleter/mainwindow.h 0
 109
 110     In addition, the class has two private functions, \c createMenu() and
 111     \c modelFromFile(), as well as private instances of QTreeView, QComboBox,
 112     QLabel, \c TreeModelCompleter and QLineEdit.
 113
 114     \snippet examples/tools/treemodelcompleter/mainwindow.h 1
 115
 116     \section1 MainWindow Class Implementation
 117
 118     The \c{MainWindow}'s constructor creates a \c MainWindow object with a
 119     parent and initializes the \c completer and \c lineEdit. The
 120     \c createMenu() function is invoked to set up the "File" menu and "Help"
 121     menu. The \c{completer}'s model is set to the QAbstractItemModel obtained
 122     from \c modelFromFile(), and the \l{QCompleter::highlighted()}
 123     {highlighted()} signal is connected to \c{MainWindow}'s \c highlight()
 124     slot.
 125
 126     \snippet examples/tools/treemodelcompleter/mainwindow.cpp 0
 127
 128     The QLabel objects \c modelLabel, \c modeLabel and \c caseLabel are
 129     instantiated. Also, the QComboBox objects, \c modeCombo and \c caseCombo,
 130     are instantiated and populated. By default, the \c{completer}'s mode is
 131     "Filtered Popup" and the case is insensitive.
 132
 133     \snippet examples/tools/treemodelcompleter/mainwindow.cpp 1
 134     \codeline
 135     \snippet examples/tools/treemodelcompleter/mainwindow.cpp 2
 136
 137     We use a QGridLayout to place all the objects in the \c MainWindow.
 138
 139     \snippet examples/tools/treemodelcompleter/mainwindow.cpp 3
 140
 141     The \c createMenu() function sets up the QAction objects required and
 142     adds them to the "File" menu and "Help" menu. The
 143     \l{QAction::triggered()}{triggered()} signals from these actions are
 144     connected to their respective slots.
 145
 146     \snippet examples/tools/treemodelcompleter/mainwindow.cpp 4
 147
 148     The \c changeMode() function accepts an \a index corresponding to the
 149     user's choice of completion mode and changes the \c{completer}'s mode
 150     accordingly.
 151
 152     \snippet examples/tools/treemodelcompleter/mainwindow.cpp 5
 153
 154     The \c about() function provides a brief description on the Tree Model
 155     Completer example.
 156
 157     \snippet examples/tools/treemodelcompleter/mainwindow.cpp 6
 158
 159     The \c changeCase() function alternates between \l{Qt::CaseSensitive}
 160     {Case Sensitive} and \l{Qt::CaseInsensitive}{Case Insensitive} modes,
 161     depending on the value of \a cs.
 162
 163     \snippet examples/tools/treemodelcompleter/mainwindow.cpp 7
 164
 165     \section1 \c main() Function
 166
 167     The \c main() function instantiates \c MainWindow and invokes the
 168     \l{QWidget::show()}{show()} function to display it.
 169
 170     \snippet examples/tools/treemodelcompleter/main.cpp 0
 171 */