| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** 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 The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \example tools/treemodelcompleter |
| \title Tree Model Completer Example |
| \ingroup examples-widgets-tools |
| |
| \brief 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 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 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 tools/treemodelcompleter/treemodelcompleter.cpp 0 |
| \codeline |
| \snippet tools/treemodelcompleter/treemodelcompleter.cpp 1 |
| |
| The \c separator() function is a getter function that returns the |
| separator string. |
| |
| \snippet tools/treemodelcompleter/treemodelcompleter.cpp 2 |
| |
| As mentioned earlier, the \c splitPath() function is reimplemented because |
| the default implementation is more suited to QFileSystemModel 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 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 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 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 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 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 tools/treemodelcompleter/mainwindow.cpp 1 |
| \codeline |
| \snippet tools/treemodelcompleter/mainwindow.cpp 2 |
| |
| We use a QGridLayout to place all the objects in the \c MainWindow. |
| |
| \snippet 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 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 tools/treemodelcompleter/mainwindow.cpp 5 |
| |
| The \c about() function provides a brief description on the Tree Model |
| Completer example. |
| |
| \snippet 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 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 tools/treemodelcompleter/main.cpp 0 |
| */ |