source: trunk/doc/src/examples/treemodelcompleter.qdoc@ 846

Last change on this file since 846 was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
File size: 7.1 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation (qt-info@nokia.com)
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
15**
16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at qt-info@nokia.com.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \example tools/treemodelcompleter
30 \title Tree Model Completer Example
31
32 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*/
Note: See TracBrowser for help on using the repository browser.