diff options
Diffstat (limited to 'examples/widgets/doc/src')
-rw-r--r-- | examples/widgets/doc/src/completer.qdoc | 249 | ||||
-rw-r--r-- | examples/widgets/doc/src/echoplugin.qdoc | 208 | ||||
-rw-r--r-- | examples/widgets/doc/src/i18n.qdoc | 37 | ||||
-rw-r--r-- | examples/widgets/doc/src/plugandpaint.qdoc | 540 | ||||
-rw-r--r-- | examples/widgets/doc/src/regexp.qdoc | 37 | ||||
-rw-r--r-- | examples/widgets/doc/src/settingseditor.qdoc | 37 | ||||
-rw-r--r-- | examples/widgets/doc/src/styleplugin.qdoc | 137 | ||||
-rw-r--r-- | examples/widgets/doc/src/treemodelcompleter.qdoc | 171 | ||||
-rw-r--r-- | examples/widgets/doc/src/undo.qdoc | 43 | ||||
-rw-r--r-- | examples/widgets/doc/src/undoframework.qdoc | 291 |
10 files changed, 1750 insertions, 0 deletions
diff --git a/examples/widgets/doc/src/completer.qdoc b/examples/widgets/doc/src/completer.qdoc new file mode 100644 index 0000000000..39be735245 --- /dev/null +++ b/examples/widgets/doc/src/completer.qdoc @@ -0,0 +1,249 @@ +/**************************************************************************** +** +** 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/completer + \title Completer Example + + The Completer example shows how to provide string-completion facilities + for an input widget based on data provided by a model. + + \image completer-example.png + + This example uses a custom item model, \c FileSystemModel, and a QCompleter object. + QCompleter is a class that provides completions based on an item model. The + type of model, the completion mode, and the case sensitivity can be + selected using combo boxes. + + \section1 The Resource File + + The Completer example requires a resource file in order to store the + \e{countries.txt} and \e{words.txt}. The resource file contains the + following code: + + \quotefile tools/completer/completer.qrc + + \section1 FileSystemModel Class Definition + + The \c FileSystemModel class is a subclass of QFileSystemModel, which provides a data + model for the local filesystem. + + \snippet tools/completer/fsmodel.h 0 + + This class only has a constructor and a \c data() function as it is only + created to enable \c data() to return the entire file path for the + display role, unlike \l{QFileSystemModel}'s \c data() function that only returns + the folder and not the drive label. This is further explained in + \c FileSystemModel's implementation. + + \section1 FileSystemModel Class Implementation + + The constructor for the \c FileSystemModel class is used to pass \a parent to + QFileSystemModel. + + \snippet tools/completer/fsmodel.cpp 0 + + As mentioned earlier, the \c data() function is reimplemented in order to + get it to return the entire file parth for the display role. For example, + with a QFileSystemModel, you will see "Program Files" in the view. However, with + \c FileSystemModel, you will see "C:\\Program Files". + + \snippet tools/completer/fsmodel.cpp 1 + + The screenshots below illustrate this difference: + + \table + \row \li \inlineimage completer-example-qdirmodel.png + \li \inlineimage completer-example-dirmodel.png + \endtable + + The Qt::EditRole, which QCompleter uses to look for matches, is left + unchanged. + + \section1 MainWindow Class Definition + + The \c MainWindow class is a subclass of QMainWindow and implements five + private slots - \c about(), \c changeCase(), \c changeMode(), \c changeModel(), + and \c changeMaxVisible(). + + \snippet tools/completer/mainwindow.h 0 + + Within the \c MainWindow class, we have two private functions: + \c createMenu() and \c modelFromFile(). We also declare the private widgets + needed - three QComboBox objects, a QCheckBox, a QCompleter, a QLabel, and + a QLineEdit. + + \snippet tools/completer/mainwindow.h 1 + + \section1 MainWindow Class Implementation + + The constructor of \c MainWindow constructs a \c MainWindow with a parent + widget and initializes the private members. The \c createMenu() function + is then invoked. + + We set up three QComboBox objects, \c modelComb, \c modeCombo and + \c caseCombo. By default, the \c modelCombo is set to QFileSystemModel, + the \c modeCombo is set to "Filtered Popup" and the \c caseCombo is set + to "Case Insensitive". + + \snippet tools/completer/mainwindow.cpp 0 + + The \c maxVisibleSpinBox is created and determines the number of visible + item in the completer + + The \c wrapCheckBox is then set up. This \c checkBox determines if the + \c{completer}'s \l{QCompleter::setWrapAround()}{setWrapAround()} property + is enabled or disabled. + + \snippet tools/completer/mainwindow.cpp 1 + + We instantiate \c contentsLabel and set its size policy to + \l{QSizePolicy::Fixed}{fixed}. The combo boxes' \l{QComboBox::activated()} + {activated()} signals are then connected to their respective slots. + + \snippet tools/completer/mainwindow.cpp 2 + + The \c lineEdit is set up and then we arrange all the widgets using a + QGridLayout. The \c changeModel() function is called, to initialize the + \c completer. + + \snippet tools/completer/mainwindow.cpp 3 + + The \c createMenu() function is used to instantiate the QAction objects + needed to fill the \c fileMenu and \c helpMenu. The actions' + \l{QAction::triggered()}{triggered()} signals are connected to their + respective slots. + + \snippet tools/completer/mainwindow.cpp 4 + + The \c modelFromFile() function accepts the \a fileName of a file and + processes it depending on its contents. + + We first validate the \c file to ensure that it can be opened in + QFile::ReadOnly mode. If this is unsuccessful, the function returns an + empty QStringListModel. + + \snippet tools/completer/mainwindow.cpp 5 + + The mouse cursor is then overridden with Qt::WaitCursor before we fill + a QStringList object, \c words, with the contents of \c file. Once this + is done, we restore the mouse cursor. + + \snippet tools/completer/mainwindow.cpp 6 + + As mentioned earlier, the resources file contains two files - + \e{countries.txt} and \e{words.txt}. If the \c file read is \e{words.txt}, + we return a QStringListModel with \c words as its QStringList and + \c completer as its parent. + + \snippet tools/completer/mainwindow.cpp 7 + + If the \c file read is \e{countries.txt}, then we require a + QStandardItemModel with \c words.count() rows, 2 columns, and \c completer + as its parent. + + \snippet tools/completer/mainwindow.cpp 8 + + A standard line in \e{countries.txt} is: + \quotation + Norway NO + \endquotation + + Hence, to populate the QStandardItemModel object, \c m, we have to + split the country name and its symbol. Once this is done, we return + \c m. + + \snippet tools/completer/mainwindow.cpp 9 + + The \c changeMode() function sets the \c{completer}'s mode, depending on + the value of \c index. + + \snippet tools/completer/mainwindow.cpp 10 + + The \c changeModel() function changes the item model used based on the + model selected by the user. + + A \c switch statement is used to change the item model based on the index + of \c modelCombo. If \c case is 0, we use an unsorted QFileSystemModel, providing + us with a file path excluding the drive label. + + \snippet tools/completer/mainwindow.cpp 11 + + Note that we create the model with \c completer as the parent as this + allows us to replace the model with a new model. The \c completer will + ensure that the old one is deleted the moment a new model is assigned + to it. + + If \c case is 1, we use the \c DirModel we defined earlier, resulting in + full paths for the files. + + \snippet tools/completer/mainwindow.cpp 12 + + When \c case is 2, we attempt to complete names of countries. This requires + a QTreeView object, \c treeView. The country names are extracted from + \e{countries.txt} and set the popup used to display completions to + \c treeView. + + \snippet tools/completer/mainwindow.cpp 13 + + The screenshot below shows the Completer with the country list model. + + \image completer-example-country.png + + If \c case is 3, we attempt to complete words. This is done using a + QStringListModel that contains data extracted from \e{words.txt}. The + model is sorted \l{QCompleter::CaseInsensitivelySortedModel} + {case insensitively}. + + The screenshot below shows the Completer with the word list model. + + \image completer-example-word.png + + Once the model type is selected, we call the \c changeMode() function and + the \c changeCase() function and set the wrap option accordingly. The + \c{wrapCheckBox}'s \l{QCheckBox::clicked()}{clicked()} signal is connected + to the \c{completer}'s \l{QCompleter::setWrapAround()}{setWrapAround()} + slot. + + \snippet tools/completer/mainwindow.cpp 14 + + The \c changeMaxVisible() update the maximum number of visible items in + the completer. + + \snippet tools/completer/mainwindow.cpp 15 + + The \c about() function provides a brief description about the example. + + \snippet tools/completer/mainwindow.cpp 16 + + \section1 \c main() Function + + The \c main() function instantiates QApplication and \c MainWindow and + invokes the \l{QWidget::show()}{show()} function. + + \snippet tools/completer/main.cpp 0 + */ diff --git a/examples/widgets/doc/src/echoplugin.qdoc b/examples/widgets/doc/src/echoplugin.qdoc new file mode 100644 index 0000000000..81ba18cdff --- /dev/null +++ b/examples/widgets/doc/src/echoplugin.qdoc @@ -0,0 +1,208 @@ +/**************************************************************************** +** +** 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/echoplugin + \title Echo Plugin Example + + This example shows how to create a Qt plugin. + + \image echopluginexample.png + + There are two kinds of plugins in Qt: plugins that extend Qt + itself and plugins that extend applications written in Qt. In this + example, we show the procedure of implementing plugins that extend + applications. When you create a plugin you declare an interface, + which is a class with only pure virtual functions. This interface + is inherited by the class that implements the plugin. The class is + stored in a shared library and can therefore be loaded by + applications at run-time. When loaded, the plugin is dynamically + cast to the interface using Qt's \l{Meta-Object + System}{meta-object system}. The plugin \l{How to Create Qt + Plugins}{overview document} gives a high-level introduction to + plugins. + + We have implemented a plugin, the \c EchoPlugin, which implements + the \c EchoInterface. The interface consists of \c echo(), which + takes a QString as argument. The \c EchoPlugin returns the string + unaltered (i.e., it works as the familiar echo command found in + both Unix and Windows). + + We test the plugin in \c EchoWindow: when you push the QPushButton + (as seen in the image above), the application sends the text in + the QLineEdit to the plugin, which echoes it back to the + application. The answer from the plugin is displayed in the + QLabel. + + + \section1 EchoWindow Class Definition + + The \c EchoWindow class lets us test the \c EchoPlugin through a + GUI. + + \snippet tools/echoplugin/echowindow/echowindow.h 0 + + We load the plugin in \c loadPlugin() and cast it to \c + EchoInterface. When the user clicks the \c button we take the + text in \c lineEdit and call the interface's \c echo() with it. + + + \section1 EchoWindow Class Implementation + + We start with a look at the constructor: + + \snippet tools/echoplugin/echowindow/echowindow.cpp 0 + + We create the widgets and set a title for the window. We then load + the plugin. \c loadPlugin() returns false if the plugin could not + be loaded, in which case we disable the widgets. If you wish a + more detailed error message, you can use + \l{QPluginLoader::}{errorString()}; we will look more closely at + QPluginLoader later. + + Here is the implementation of \c sendEcho(): + + \snippet tools/echoplugin/echowindow/echowindow.cpp 1 + + This slot is called when the user pushes \c button or presses + enter in \c lineEdit. We call \c echo() of the echo interface. In + our example this is the \c EchoPlugin, but it could be any plugin + that inherit the \c EchoInterface. We take the QString returned + from \c echo() and display it in the \c label. + + Here is the implementation of \c createGUI(): + + \snippet tools/echoplugin/echowindow/echowindow.cpp 2 + + We create the widgets and lay them out in a grid layout. We + connect the label and line edit to our \c sendEcho() slot. + + Here is the \c loadPlugin() function: + + \snippet tools/echoplugin/echowindow/echowindow.cpp 3 + + Access to plugins at run-time is provided by QPluginLoader. You + supply it with the filename of the shared library the plugin is + stored in and call \l{QPluginLoader::}{instance()}, which loads + and returns the root component of the plugin (i.e., it resolves + the type of the plugin and creates a QObject instance of it). If + the plugin was not successfully loaded, it will be null, so we + return false. If it was loaded correctly, we can cast the plugin + to our \c EchoInterface and return true. In the case that the + plugin loaded does not implement the \c EchoInterface, \c + instance() will return null, but this cannot happen in our + example. Notice that the location of the plugin is not the same + for all platforms. + + + \section1 EchoInterface Class Definition + + The \c EchoInterface defines the functions that the plugin will + provide. An interface is a class that only consists of pure + virtual functions. If non virtual functions were present in the + class you would get misleading compile errors in the moc files. + + \snippet tools/echoplugin/echowindow/echointerface.h 0 + + We declare \c echo(). In our \c EchoPlugin we use this method to + return, or echo, \a message. + + We use the Q_DECLARE_INTERFACE macro to let \l{Meta-Object + System}{Qt's meta object system} aware of the interface. We do + this so that it will be possible to identify plugins that + implements the interface at run-time. The second argument is a + string that must identify the interface in a unique way. + + + \section1 EchoPlugin Class Definition + + We inherit both QObject and \c EchoInterface to make this class a + plugin. The Q_INTERFACES macro tells Qt which interfaces the class + implements. In our case we only implement the \c EchoInterface. + If a class implements more than one interface, they are given as + a comma separated list. + + \snippet tools/echoplugin/plugin/echoplugin.h 0 + + + \section1 EchoPlugin Class Implementation + + Here is the implementation of \c echo(): + + \snippet tools/echoplugin/plugin/echoplugin.cpp 0 + + We simply return the functions parameter. + + \snippet tools/echoplugin/plugin/echoplugin.cpp 1 + + We use the Q_EXPORT_PLUGIN2 macro to let Qt know that the \c + EchoPlugin class is a plugin. The first parameter is the name of + the plugin; it is usual to give the plugin and the library file it + is stored in the same name. + + \section1 The \c main() function + + \snippet tools/echoplugin/echowindow/main.cpp 0 + + We create an \c EchoWindow and display it as a top-level window. + + \section1 The Profiles + + When creating plugins the profiles need to be adjusted. + We show here what changes need to be done. + + The profile in the echoplugin directory uses the \c subdirs + template and simply includes includes to directories in which + the echo window and echo plugin lives: + + \snippet tools/echoplugin/echoplugin.pro 0 + + The profile for the echo window does not need any plugin specific + settings. We move on to the plugin profile: + + \snippet tools/echoplugin/plugin/plugin.pro 0 + + We need to set the TEMPLATE as we now want to make a library + instead of an executable. We also need to tell qmake that we are + creating a plugin. The \c EchoInterface that the plugin implements + lives in the \c echowindow directory, so we need to add that + directory to the include path. We set the TARGET of the project, + which is the name of the library file in which the plugin will be + stored; qmake appends the appropriate file extension depending on + the platform. By convention the target should have the same name + as the plugin (set with Q_EXPORT_PLUGIN2) + + \section1 Further reading and examples + + You can find an overview of the macros needed to create plugins + \l{Macros for Defining Plugins}{here}. + + We give an example of a plugin that extend Qt in the \l{Style + Plugin Example}{style plugin} example. The \l{Plug & Paint + Example}{plug and paint} example shows how to create static + plugins. +*/ diff --git a/examples/widgets/doc/src/i18n.qdoc b/examples/widgets/doc/src/i18n.qdoc new file mode 100644 index 0000000000..980319233d --- /dev/null +++ b/examples/widgets/doc/src/i18n.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** 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/i18n + \title I18N Example + + The Internationalization (I18N) example demonstrates Qt's support for translated + text. Developers can write the initial application text in one language, and + translations can be provided later without any modifications to the code. + + \image i18n-example.png +*/ diff --git a/examples/widgets/doc/src/plugandpaint.qdoc b/examples/widgets/doc/src/plugandpaint.qdoc new file mode 100644 index 0000000000..24fb4ab1b9 --- /dev/null +++ b/examples/widgets/doc/src/plugandpaint.qdoc @@ -0,0 +1,540 @@ +/**************************************************************************** +** +** 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/plugandpaint + \title Plug & Paint Example + + The Plug & Paint example demonstrates how to write Qt + applications that can be extended through plugins. + + \image plugandpaint.png Screenshot of the Plug & Paint example + + A plugin is a dynamic library that can be loaded at run-time to + extend an application. Qt makes it possible to create custom + plugins and to load them using QPluginLoader. To ensure that + plugins don't get lost, it is also possible to link them + statically to the executable. The Plug & Paint example uses + plugins to support custom brushes, shapes, and image filters. A + single plugin can provide multiple brushes, shapes, and/or + filters. + + If you want to learn how to make your own application extensible + through plugins, we recommend that you start by reading this + overview, which explains how to make an application use plugins. + Afterward, you can read the + \l{plugandpaintplugins/basictools}{Basic Tools} and + \l{plugandpaintplugins/extrafilters}{Extra Filters} + overviews, which show how to implement static and dynamic + plugins, respectively. + + Plug & Paint consists of the following classes: + + \list + \li \c MainWindow is a QMainWindow subclass that provides the menu + system and that contains a \c PaintArea as the central widget. + \li \c PaintArea is a QWidget that allows the user to draw using a + brush and to insert shapes. + \li \c PluginDialog is a dialog that shows information about the + plugins detected by the application. + \li \c BrushInterface, \c ShapeInterface, and \c FilterInterface are + abstract base classes that can be implemented by plugins to + provide custom brushes, shapes, and image filters. + \endlist + + \section1 The Plugin Interfaces + + We will start by reviewing the interfaces defined in \c + interfaces.h. These interfaces are used by the Plug & Paint + application to access extra functionality. They are implemented + in the plugins. + + + \snippet tools/plugandpaint/interfaces.h 0 + + The \c BrushInterface class declares four pure virtual functions. + The first pure virtual function, \c brushes(), returns a list of + strings that identify the brushes provided by the plugin. By + returning a QStringList instead of a QString, we make it possible + for a single plugin to provide multiple brushes. The other + functions have a \c brush parameter to identify which brush + (among those returned by \c brushes()) is used. + + \c mousePress(), \c mouseMove(), and \c mouseRelease() take a + QPainter and one or two \l{QPoint}s, and return a QRect + identifying which portion of the image was altered by the brush. + + The class also has a virtual destructor. Interface classes + usually don't need such a destructor (because it would make + little sense to \c delete the object that implements the + interface through a pointer to the interface), but some compilers + emit a warning for classes that declare virtual functions but no + virtual destructor. We provide the destructor to keep these + compilers happy. + + \snippet tools/plugandpaint/interfaces.h 1 + + The \c ShapeInterface class declares a \c shapes() function that + works the same as \c{BrushInterface}'s \c brushes() function, and + a \c generateShape() function that has a \c shape parameter. + Shapes are represented by a QPainterPath, a data type that can + represent arbitrary 2D shapes or combinations of shapes. The \c + parent parameter can be used by the plugin to pop up a dialog + asking the user to specify more information. + + \snippet tools/plugandpaint/interfaces.h 2 + + The \c FilterInterface class declares a \c filters() function + that returns a list of filter names, and a \c filterImage() + function that applies a filter to an image. + + \snippet tools/plugandpaint/interfaces.h 4 + + To make it possible to query at run-time whether a plugin + implements a given interface, we must use the \c + Q_DECLARE_INTERFACE() macro. The first argument is the name of + the interface. The second argument is a string identifying the + interface in a unique way. By convention, we use a "Java package + name" syntax to identify interfaces. If we later change the + interfaces, we must use a different string to identify the new + interface; otherwise, the application might crash. It is therefore + a good idea to include a version number in the string, as we did + above. + + The \l{plugandpaintplugins/basictools}{Basic Tools} plugin + and the \l{plugandpaintplugins/extrafilters}{Extra Filters} + plugin shows how to derive from \c BrushInterface, \c + ShapeInterface, and \c FilterInterface. + + A note on naming: It might have been tempting to give the \c + brushes(), \c shapes(), and \c filters() functions a more generic + name, such as \c keys() or \c features(). However, that would + have made multiple inheritance impractical. When creating + interfaces, we should always try to give unique names to the pure + virtual functions. + + \section1 The MainWindow Class + + The \c MainWindow class is a standard QMainWindow subclass, as + found in many of the other examples (e.g., + \l{mainwindows/application}{Application}). Here, we'll + concentrate on the parts of the code that are related to plugins. + + \snippet tools/plugandpaint/mainwindow.cpp 4 + + The \c loadPlugins() function is called from the \c MainWindow + constructor to detect plugins and update the \uicontrol{Brush}, + \uicontrol{Shapes}, and \uicontrol{Filters} menus. We start by handling static + plugins (available through QPluginLoader::staticInstances()) + + To the application that uses the plugin, a Qt plugin is simply a + QObject. That QObject implements plugin interfaces using multiple + inheritance. + + \snippet tools/plugandpaint/mainwindow.cpp 5 + + The next step is to load dynamic plugins. We initialize the \c + pluginsDir member variable to refer to the \c plugins + subdirectory of the Plug & Paint example. On Unix, this is just a + matter of initializing the QDir variable with + QApplication::applicationDirPath(), the path of the executable + file, and to do a \l{QDir::cd()}{cd()}. On Windows and Mac OS X, + this file is usually located in a subdirectory, so we need to + take this into account. + + \snippet tools/plugandpaint/mainwindow.cpp 6 + \snippet tools/plugandpaint/mainwindow.cpp 7 + \snippet tools/plugandpaint/mainwindow.cpp 8 + + We use QDir::entryList() to get a list of all files in that + directory. Then we iterate over the result using \l foreach and + try to load the plugin using QPluginLoader. + + The QObject provided by the plugin is accessible through + QPluginLoader::instance(). If the dynamic library isn't a Qt + plugin, or if it was compiled against an incompatible version of + the Qt library, QPluginLoader::instance() returns a null pointer. + + If QPluginLoader::instance() is non-null, we add it to the menus. + + \snippet tools/plugandpaint/mainwindow.cpp 9 + + At the end, we enable or disable the \uicontrol{Brush}, \uicontrol{Shapes}, + and \uicontrol{Filters} menus based on whether they contain any items. + + \snippet tools/plugandpaint/mainwindow.cpp 10 + + For each plugin (static or dynamic), we check which interfaces it + implements using \l qobject_cast(). First, we try to cast the + plugin instance to a \c BrushInterface; if it works, we call the + private function \c addToMenu() with the list of brushes returned + by \c brushes(). Then we do the same with the \c ShapeInterface + and the \c FilterInterface. + + \snippet tools/plugandpaint/mainwindow.cpp 3 + + The \c aboutPlugins() slot is called on startup and can be + invoked at any time through the \uicontrol{About Plugins} action. It + pops up a \c PluginDialog, providing information about the loaded + plugins. + + \image plugandpaint-plugindialog.png Screenshot of the Plugin dialog + + + The \c addToMenu() function is called from \c loadPlugin() to + create \l{QAction}s for custom brushes, shapes, or filters and + add them to the relevant menu. The QAction is created with the + plugin from which it comes from as the parent; this makes it + convenient to get access to the plugin later. + + \snippet tools/plugandpaint/mainwindow.cpp 0 + + The \c changeBrush() slot is invoked when the user chooses one of + the brushes from the \uicontrol{Brush} menu. We start by finding out + which action invoked the slot using QObject::sender(). Then we + get the \c BrushInterface out of the plugin (which we + conveniently passed as the QAction's parent) and we call \c + PaintArea::setBrush() with the \c BrushInterface and the string + identifying the brush. Next time the user draws on the paint + area, \c PaintArea will use this brush. + + \snippet tools/plugandpaint/mainwindow.cpp 1 + + The \c insertShape() is invoked when the use chooses one of the + shapes from the \uicontrol{Shapes} menu. We retrieve the QAction that + invoked the slot, then the \c ShapeInterface associated with that + QAction, and finally we call \c ShapeInterface::generateShape() + to obtain a QPainterPath. + + \snippet tools/plugandpaint/mainwindow.cpp 2 + + The \c applyFilter() slot is similar: We retrieve the QAction + that invoked the slot, then the \c FilterInterface associated to + that QAction, and finally we call \c + FilterInterface::filterImage() to apply the filter onto the + current image. + + \section1 The PaintArea Class + + The \c PaintArea class contains some code that deals with \c + BrushInterface, so we'll review it briefly. + + \snippet tools/plugandpaint/paintarea.cpp 0 + + In \c setBrush(), we simply store the \c BrushInterface and the + brush that are given to us by \c MainWindow. + + \snippet tools/plugandpaint/paintarea.cpp 1 + + In the \l{QWidget::mouseMoveEvent()}{mouse move event handler}, + we call the \c BrushInterface::mouseMove() function on the + current \c BrushInterface, with the current brush. The mouse + press and mouse release handlers are very similar. + + \section1 The PluginDialog Class + + The \c PluginDialog class provides information about the loaded + plugins to the user. Its constructor takes a path to the plugins + and a list of plugin file names. It calls \c findPlugins() + to fill the QTreeWdiget with information about the plugins: + + \snippet tools/plugandpaint/plugindialog.cpp 0 + + The \c findPlugins() is very similar to \c + MainWindow::loadPlugins(). It uses QPluginLoader to access the + static and dynamic plugins. Its helper function \c + populateTreeWidget() uses \l qobject_cast() to find out which + interfaces are implemented by the plugins: + + \snippet tools/plugandpaint/plugindialog.cpp 1 + + \section1 Importing Static Plugins + + The \l{plugandpaintplugins/basictools}{Basic Tools} plugin + is built as a static plugin, to ensure that it is always + available to the application. This requires using the + Q_IMPORT_PLUGIN() macro somewhere in the application (in a \c + .cpp file) and specifying the plugin in the \c .pro file. + + For Plug & Paint, we have chosen to put Q_IMPORT_PLUGIN() in \c + main.cpp: + + \snippet tools/plugandpaint/main.cpp 0 + + The argument to Q_IMPORT_PLUGIN() is the plugin's name, as + specified with Q_EXPORT_PLUGIN2() in the \l{Exporting the + Plugin}{plugin}. + + In the \c .pro file, we need to specify the static library. + Here's the project file for building Plug & Paint: + + \snippet tools/plugandpaint/plugandpaint.pro 0 + + The \c LIBS line variable specifies the library \c pnp_basictools + located in the \c ../plugandpaintplugins/basictools directory. + (Although the \c LIBS syntax has a distinct Unix flavor, \c qmake + supports it on all platforms.) + + The \c CONFIG() code at the end is necessary for this example + because the example is part of the Qt distribution and Qt can be + configured to be built simultaneously in debug and in release + modes. You don't need to for your own plugin applications. + + This completes our review of the Plug & Paint application. At + this point, you might want to take a look at the + \l{plugandpaintplugins/basictools}{Basic Tools} example + plugin. +*/ + +/*! + \example tools/plugandpaintplugins/basictools + \title Plug & Paint Basic Tools Example + + The Basic Tools example is a static plugin for the + \l{plugandpaint}{Plug & Paint} example. It provides a set + of basic brushes, shapes, and filters. Through the Basic Tools + example, we will review the four steps involved in writing a Qt + plugin: + + \list 1 + \li Declare a plugin class. + \li Implement the interfaces provided by the plugin. + \li Export the plugin using the Q_EXPORT_PLUGIN2() macro. + \li Build the plugin using an adequate \c .pro file. + \endlist + + \section1 Declaration of the Plugin Class + + \snippet tools/plugandpaintplugins/basictools/basictoolsplugin.h 0 + + We start by including \c interfaces.h, which defines the plugin + interfaces for the \l{plugandpaint}{Plug & Paint} + application. For the \c #include to work, we need to add an \c + INCLUDEPATH entry to the \c .pro file with the path to Qt's \c + examples/tools directory. + + The \c BasicToolsPlugin class is a QObject subclass that + implements the \c BrushInterface, the \c ShapeInterface, and the + \c FilterInterface. This is done through multiple inheritance. + The \c Q_INTERFACES() macro is necessary to tell \l{moc}, Qt's + meta-object compiler, that the base classes are plugin + interfaces. Without the \c Q_INTERFACES() macro, we couldn't use + \l qobject_cast() in the \l{plugandpaint}{Plug & Paint} + application to detect interfaces. + + \snippet tools/plugandpaintplugins/basictools/basictoolsplugin.h 2 + + In the \c public section of the class, we declare all the + functions from the three interfaces. + + \section1 Implementation of the Brush Interface + + Let's now review the implementation of the \c BasicToolsPlugin + member functions inherited from \c BrushInterface. + + \snippet tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 0 + + The \c brushes() function returns a list of brushes provided by + this plugin. We provide three brushes: \uicontrol{Pencil}, \uicontrol{Air + Brush}, and \uicontrol{Random Letters}. + + \snippet tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 1 + + On a mouse press event, we just call \c mouseMove() to draw the + spot where the event occurred. + + \snippet tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 2 + + In \c mouseMove(), we start by saving the state of the QPainter + and we compute a few variables that we'll need later. + + \snippet tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 3 + + Then comes the brush-dependent part of the code: + + \list + \li If the brush is \uicontrol{Pencil}, we just call + QPainter::drawLine() with the current QPen. + + \li If the brush is \uicontrol{Air Brush}, we start by setting the + painter's QBrush to Qt::Dense6Pattern to obtain a dotted + pattern. Then we draw a circle filled with that QBrush several + times, resulting in a thick line. + + \li If the brush is \uicontrol{Random Letters}, we draw a random letter + at the new cursor position. Most of the code is for setting + the font to be bold and larger than the default font and for + computing an appropriate bounding rect. + \endlist + + At the end, we restore the painter state to what it was upon + entering the function and we return the bounding rectangle. + + \snippet tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 4 + + When the user releases the mouse, we do nothing and return an + empty QRect. + + \section1 Implementation of the Shape Interface + + \snippet tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 5 + + The plugin provides three shapes: \uicontrol{Circle}, \uicontrol{Star}, and + \uicontrol{Text...}. The three dots after \uicontrol{Text} are there because + the shape pops up a dialog asking for more information. We know + that the shape names will end up in a menu, so we include the + three dots in the shape name. + + A cleaner but more complicated design would have been to + distinguish between the internal shape name and the name used in + the user interface. + + \snippet tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 6 + + The \c generateShape() creates a QPainterPath for the specified + shape. If the shape is \uicontrol{Text}, we pop up a QInputDialog to + let the user enter some text. + + \section1 Implementation of the Filter Interface + + \snippet tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 7 + + The plugin provides three filters: \uicontrol{Invert Pixels}, \uicontrol{Swap + RGB}, and \uicontrol{Grayscale}. + + \snippet tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 8 + + The \c filterImage() function takes a filter name and a QImage as + parameters and returns an altered QImage. The first thing we do + is to convert the image to a 32-bit RGB format, to ensure that + the algorithms will work as expected. For example, + QImage::invertPixels(), which is used to implement the + \uicontrol{Invert Pixels} filter, gives counterintuitive results for + 8-bit images, because they invert the indices into the color + table instead of inverting the color table's entries. + + \section1 Exporting the Plugin + + Whereas applications have a \c main() function as their entry + point, plugins need to contain exactly one occurrence of the + Q_EXPORT_PLUGIN2() macro to specify which class provides the + plugin: + + \snippet tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 9 + + This line may appear in any \c .cpp file that is part of the + plugin's source code. + + \section1 The .pro File + + Here's the project file for building the Basic Tools plugin: + + \snippet tools/plugandpaintplugins/basictools/basictools.pro 0 + + The \c .pro file differs from typical \c .pro files in many + respects. First, it starts with a \c TEMPLATE entry specifying \c + lib. (The default template is \c app.) It also adds \c plugin to + the \c CONFIG variable. This is necessary on some platforms to + avoid generating symbolic links with version numbers in the file + name, which is appropriate for most dynamic libraries but not for + plugins. + + To make the plugin a static plugin, all that is required is to + specify \c static in addition to \c plugin. The + \l{plugandpaintplugins/extrafilters}{Extra Filters} plugin, + which is compiled as a dynamic plugin, doesn't specify \c static + in its \c .pro file. + + The \c INCLUDEPATH variable sets the search paths for global + headers (i.e., header files included using \c{#include <...>}). + We add Qt's \c examples/tools directory (strictly speaking, + \c{examples/tools/plugandpaintplugins/basictools/../..}) to the + list, so that we can include \c <plugandpaint/interfaces.h>. + + The \c TARGET variable specifies which name we want to give the + target library. We use \c pnp_ as the prefix to show that the + plugin is designed to work with Plug & Paint. On Unix, \c lib is + also prepended to that name. On all platforms, a + platform-specific suffix is appended (e.g., \c .dll on Windows, + \c .a on Linux). + + The \c CONFIG() code at the end is necessary for this example + because the example is part of the Qt distribution and Qt can be + configured to be built simultaneously in debug and in release + modes. You don't need to for your own plugins. +*/ + +/*! + \example tools/plugandpaintplugins/extrafilters + \title Plug & Paint Extra Filters Example + + The Extra Filters example is a plugin for the + \l{plugandpaint}{Plug & Paint} example. It provides a set + of filters in addition to those provided by the + \l{plugandpaintplugins/basictools}{Basic Tools} plugin. + + Since the approach is identical to + \l{plugandpaintplugins/basictools}{Basic Tools}, we won't + review the code here. The only part of interest is the + \c .pro file, since Extra Filters is a dynamic plugin + (\l{plugandpaintplugins/basictools}{Basic Tools} is + linked statically into the Plug & Paint executable). + + Here's the project file for building the Extra Filters plugin: + + \snippet tools/plugandpaintplugins/extrafilters/extrafilters.pro 0 + + The \c .pro file differs from typical \c .pro files in many + respects. First, it starts with a \c TEMPLATE entry specifying \c + lib. (The default template is \c app.) It also adds \c plugin to + the \c CONFIG variable. This is necessary on some platforms to + avoid generating symbolic links with version numbers in the file + name, which is appropriate for most dynamic libraries but not for + plugins. + + The \c INCLUDEPATH variable sets the search paths for global + headers (i.e., header files included using \c{#include <...>}). + We add Qt's \c examples/tools directory (strictly speaking, + \c{examples/tools/plugandpaintplugins/basictools/../..}) to the + list, so that we can include \c <plugandpaint/interfaces.h>. + + The \c TARGET variable specifies which name we want to give the + target library. We use \c pnp_ as the prefix to show that the + plugin is designed to work with Plug & Paint. On Unix, \c lib is + also prepended to that name. On all platforms, a + platform-specific suffix is appended (e.g., \c .dll on Windows, + \c .so on Linux). + + The \c DESTDIR variable specifies where we want to install the + plugin. We put it in Plug & Paint's \c plugins subdirectory, + since that's where the application looks for dynamic plugins. + + The \c CONFIG() code at the end is necessary for this example + because the example is part of the Qt distribution and Qt can be + configured to be built simultaneously in debug and in release + modes. You don't need to for your own plugins. +*/ diff --git a/examples/widgets/doc/src/regexp.qdoc b/examples/widgets/doc/src/regexp.qdoc new file mode 100644 index 0000000000..a2c7b53ed2 --- /dev/null +++ b/examples/widgets/doc/src/regexp.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** 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/regexp + \title Regular Expressions Example + + The Regular Expressions (RegExp) example shows how regular expressions in Qt are + applied to text by providing an environment in which new regular expressions can be + created and tested on custom text strings. + + \image regexp-example.png +*/ diff --git a/examples/widgets/doc/src/settingseditor.qdoc b/examples/widgets/doc/src/settingseditor.qdoc new file mode 100644 index 0000000000..6d295bb928 --- /dev/null +++ b/examples/widgets/doc/src/settingseditor.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** 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/settingseditor + \title Settings Editor Example + + The Settings Editor example shows how Qt's standard settings support is used in an + application by providing an editor that enables the user to view the settings for + installed applications, and modify those that can be edited. + + \image settingseditor-example.png +*/ diff --git a/examples/widgets/doc/src/styleplugin.qdoc b/examples/widgets/doc/src/styleplugin.qdoc new file mode 100644 index 0000000000..42f35f2141 --- /dev/null +++ b/examples/widgets/doc/src/styleplugin.qdoc @@ -0,0 +1,137 @@ +/**************************************************************************** +** +** 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/styleplugin + \title Style Plugin Example + + This example shows how to create a plugin that extends Qt with a new + GUI look and feel. + + \image stylepluginexample.png + + A plugin in Qt is a class stored in a shared library that can be + loaded by a QPluginLoader at run-time. When you create plugins in + Qt, they either extend a Qt application or Qt itself. Writing a + plugin that extends Qt itself is achieved by inheriting one of the + plugin \l{Plugin Classes}{base classes}, reimplementing functions + from that class, and adding a macro. In this example we extend Qt + by adding a new GUI look and feel (i.e., making a new QStyle + available). A high-level introduction to plugins is given in the + plugin \l{How to Create Qt Plugins}{overview document}. + + Plugins that provide new styles inherit the QStylePlugin base + class. Style plugins are loaded by Qt and made available through + QStyleFactory; we will look at this later. We have implemented \c + SimpleStylePlugin, which provides \c SimpleStyle. The new style + contributes to widget styling by drawing button backgrounds in + red - not a major contribution, but it still makes a new style. + + The new style is platform agnostic in the sense that it is not + based on any specific style implementation, but uses QProxyStyle + to merely tweak the looks in the current application style that + defaults to the native system style. + + \note On some platforms, the native style will prevent the button + from having a red background. In this case, try to run the example + in another style (e.g., fusion). + + We test the plugin with \c StyleWindow, in which we display a + QPushButton. The \c SimpleStyle and \c StyleWindow classes do not + contain any plugin specific functionality and their implementations + are trivial; we will therefore leap past them and head on to the \c + SimpleStylePlugin and the \c main() function. After we have looked + at that, we examine the plugin's profile. + + + \section1 SimpleStylePlugin Class Definition + + \c SimpleStylePlugin inherits QStylePlugin and is the plugin + class. + + \snippet tools/styleplugin/plugin/simplestyleplugin.h 0 + + \c keys() returns a list of style names that this plugin can + create, while \c create() takes such a string and returns the + QStyle corresponding to the key. Both functions are pure virtual + functions reimplemented from QStylePlugin. When an application + requests an instance of the \c SimpleStyle style, which this + plugin creates, Qt will create it with this plugin. + + + \section1 SimpleStylePlugin Class Implementation + + Here is the implementation of \c keys(): + + \snippet tools/styleplugin/plugin/simplestyleplugin.cpp 0 + + Since this plugin only supports one style, we return a QStringList + with the class name of that style. + + Here is the \c create() function: + + \snippet tools/styleplugin/plugin/simplestyleplugin.cpp 1 + + Note that the key for style plugins are case insensitive. + The case sensitivity varies from plugin to plugin, so you need to + check this when implementing new plugins. + + \section1 The \c main() function + + \snippet tools/styleplugin/stylewindow/main.cpp 0 + + Qt loads the available style plugins when the QApplication object + is initialized. The QStyleFactory class knows about all styles and + produces them with \l{QStyleFactory::}{create()} (it is a + wrapper around all the style plugins). + + \section1 The Simple Style Plugin Profile + + The \c SimpleStylePlugin lives in its own directory and have + its own profile: + + \snippet tools/styleplugin/plugin/plugin.pro 0 + + In the plugin profile we need to set the lib template as we are + building a shared library instead of an executable. We must also + set the config to plugin. We set the library to be stored in the + styles folder under stylewindow because this is a path in which Qt + will search for style plugins. + + \section1 Related articles and examples + + In addition to the plugin \l{How to Create Qt Plugins}{overview + document}, we have other examples and articles that concern + plugins. + + In the \l{Echo Plugin Example}{echo plugin example} we show how to + implement plugins that extends Qt applications rather than Qt + itself, which is the case with the style plugin of this example. + The \l{Plug & Paint Example}{plug & paint} example shows how to + implement a static plugin as well as being a more involved example + on plugins that extend applications. +*/ diff --git a/examples/widgets/doc/src/treemodelcompleter.qdoc b/examples/widgets/doc/src/treemodelcompleter.qdoc new file mode 100644 index 0000000000..c6b7768976 --- /dev/null +++ b/examples/widgets/doc/src/treemodelcompleter.qdoc @@ -0,0 +1,171 @@ +/**************************************************************************** +** +** 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/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 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 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 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 +*/ diff --git a/examples/widgets/doc/src/undo.qdoc b/examples/widgets/doc/src/undo.qdoc new file mode 100644 index 0000000000..03920e44dd --- /dev/null +++ b/examples/widgets/doc/src/undo.qdoc @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** 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/undo + \title Undo Framework + + This example shows Qt's undo framework in action. + + \image undodemo.png + + Qt's undo framework is an implementation of the Command + pattern, which provides advanced undo/redo functionality. + + To show the abilities of the framework, we have implemented a + small diagram application in which the diagram items are geometric + primitives. You can edit the diagram in the following ways: add, + move, change the color of, and delete the items. +*/ diff --git a/examples/widgets/doc/src/undoframework.qdoc b/examples/widgets/doc/src/undoframework.qdoc new file mode 100644 index 0000000000..849b2e6143 --- /dev/null +++ b/examples/widgets/doc/src/undoframework.qdoc @@ -0,0 +1,291 @@ +/**************************************************************************** +** +** 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/undoframework + \title Undo Framework Example + + This example shows how to implement undo/redo functionality + with the Qt undo framework. + + \image undoframeworkexample.png The Undo Diagram Example + + In the Qt undo framework, all actions that the user performs are + implemented in classes that inherit QUndoCommand. An undo command + class knows how to both \l{QUndoCommand::}{redo()} - or just do + the first time - and \l{QUndoCommand::}{undo()} an action. For + each action the user performs, a command is placed on a + QUndoStack. Since the stack contains all commands executed + (stacked in chronological order) on the document, it can roll the + state of the document backwards and forwards by undoing and redoing + its commands. See the \l{Overview of Qt's Undo Framework}{overview + document} for a high-level introduction to the undo framework. + + The undo example implements a simple diagram application. It is + possible to add and delete items, which are either box or + rectangular shaped, and move the items by dragging them with the + mouse. The undo stack is shown in a QUndoView, which is a list in + which the commands are shown as list items. Undo and redo are + available through the edit menu. The user can also select a command + from the undo view. + + We use the \l{Graphics View Framework}{graphics view + framework} to implement the diagram. We only treat the related + code briefly as the framework has examples of its own (e.g., the + \l{Diagram Scene Example}). + + The example consists of the following classes: + + \list + \li \c MainWindow is the main window and arranges the + example's widgets. It creates the commands based + on user input and keeps them on the command stack. + \li \c AddCommand adds an item to the scene. + \li \c DeleteCommand deletes an item from the scene. + \li \c MoveCommand when an item is moved the MoveCommand keeps record + of the start and stop positions of the move, and it + moves the item according to these when \c redo() and \c undo() + is called. + \li \c DiagramScene inherits QGraphicsScene and + emits signals for the \c MoveComands when an item is moved. + \li \c DiagramItem inherits QGraphicsPolygonItem and represents + an item in the diagram. + \endlist + + \section1 MainWindow Class Definition + + \snippet tools/undoframework/mainwindow.h 0 + + The \c MainWindow class maintains the undo stack, i.e., it creates + \l{QUndoCommand}s and pushes and pops them from the stack when it + receives the \c triggered() signal from \c undoAction and \c + redoAction. + + \section1 MainWindow Class Implementation + + We will start with a look at the constructor: + + \snippet tools/undoframework/mainwindow.cpp 0 + + In the constructor, we set up the DiagramScene and QGraphicsView. + + Here is the \c createUndoView() function: + + \snippet tools/undoframework/mainwindow.cpp 1 + + The QUndoView is a widget that display the text, which is set with + the \l{QUndoCommand::}{setText()} function, for each QUndoCommand + in the undo stack in a list. + + Here is the \c createActions() function: + + \snippet tools/undoframework/mainwindow.cpp 2 + \codeline + \snippet tools/undoframework/mainwindow.cpp 3 + \dots + \snippet tools/undoframework/mainwindow.cpp 5 + + The \c createActions() function sets up all the examples actions + in the manner shown above. The + \l{QUndoStack::}{createUndoAction()} and + \l{QUndoStack::}{createRedoAction()} helps us crate actions that + are disabled and enabled based on the state of the stack. Also, + the text of the action will be updated automatically based on the + \l{QUndoCommand::}{text()} of the undo commands. For the other + actions we have implemented slots in the \c MainWindow class. + + Here is the \c createMenus() function: + + \snippet tools/undoframework/mainwindow.cpp 6 + + \dots + \snippet tools/undoframework/mainwindow.cpp 7 + \dots + \snippet tools/undoframework/mainwindow.cpp 8 + + We have to use the QMenu \c aboutToShow() and \c aboutToHide() + signals since we only want \c deleteAction to be enabled when we + have selected an item. + + Here is the \c itemMoved() slot: + + \snippet tools/undoframework/mainwindow.cpp 9 + + We simply push a MoveCommand on the stack, which calls \c redo() + on it. + + Here is the \c deleteItem() slot: + + \snippet tools/undoframework/mainwindow.cpp 10 + + An item must be selected to be deleted. We need to check if it is + selected as the \c deleteAction may be enabled even if an item is + not selected. This can happen as we do not catch a signal or event + when an item is selected. + + Here is the \c itemMenuAboutToShow() and itemMenuAboutToHide() slots: + + \snippet tools/undoframework/mainwindow.cpp 11 + \codeline + \snippet tools/undoframework/mainwindow.cpp 12 + + We implement \c itemMenuAboutToShow() and \c itemMenuAboutToHide() + to get a dynamic item menu. These slots are connected to the + \l{QMenu::}{aboutToShow()} and \l{QMenu::}{aboutToHide()} signals. + We need this to disable or enable the \c deleteAction. + + Here is the \c addBox() slot: + + \snippet tools/undoframework/mainwindow.cpp 13 + + The \c addBox() function creates an AddCommand and pushes it on + the undo stack. + + Here is the \c addTriangle() sot: + + \snippet tools/undoframework/mainwindow.cpp 14 + + The \c addTriangle() function creates an AddCommand and pushes it + on the undo stack. + + Here is the implementation of \c about(): + + \snippet tools/undoframework/mainwindow.cpp 15 + + The about slot is triggered by the \c aboutAction and displays an + about box for the example. + + \section1 AddCommand Class Definition + + \snippet tools/undoframework/commands.h 2 + + The \c AddCommand class adds DiagramItem graphics items to the + DiagramScene. + + \section1 AddCommand Class Implementation + + We start with the constructor: + + \snippet tools/undoframework/commands.cpp 7 + + We first create the DiagramItem to add to the DiagramScene. The + \l{QUndoCommand::}{setText()} function let us set a QString that + describes the command. We use this to get custom messages in the + QUndoView and in the menu of the main window. + + \snippet tools/undoframework/commands.cpp 8 + + \c undo() removes the item from the scene. + + \snippet tools/undoframework/commands.cpp 9 + + We set the position of the item as we do not do this in the + constructor. + + \section1 DeleteCommand Class Definition + + \snippet tools/undoframework/commands.h 1 + + The DeleteCommand class implements the functionality to remove an + item from the scene. + + \section1 DeleteCommand Class Implementation + + \snippet tools/undoframework/commands.cpp 4 + + We know that there must be one selected item as it is not possible + to create a DeleteCommand unless the item to be deleted is + selected and that only one item can be selected at any time. + The item must be unselected if it is inserted back into the + scene. + + \snippet tools/undoframework/commands.cpp 5 + + The item is simply reinserted into the scene. + + \snippet tools/undoframework/commands.cpp 6 + + The item is removed from the scene. + + \section1 MoveCommand Class Definition + + \snippet tools/undoframework/commands.h 0 + + The \l{QUndoCommand::}{mergeWith()} is reimplemented to make + consecutive moves of an item one MoveCommand, i.e, the item will + be moved back to the start position of the first move. + + \section1 MoveCommand Class Implementation + + + The constructor of MoveCommand looks like this: + + \snippet tools/undoframework/commands.cpp 0 + + We save both the old and new positions for undo and redo + respectively. + + \snippet tools/undoframework/commands.cpp 2 + + We simply set the items old position and update the scene. + + \snippet tools/undoframework/commands.cpp 3 + + We set the item to its new position. + + \snippet tools/undoframework/commands.cpp 1 + + Whenever a MoveCommand is created, this function is called to + check if it should be merged with the previous command. It is the + previous command object that is kept on the stack. The function + returns true if the command is merged; otherwise false. + + We first check whether it is the same item that has been moved + twice, in which case we merge the commands. We update the position + of the item so that it will take the last position in the move + sequence when undone. + + \section1 DiagramScene Class Definition + + \snippet tools/undoframework/diagramscene.h 0 + + The DiagramScene implements the functionality to move a + DiagramItem with the mouse. It emits a signal when a move is + completed. This is caught by the \c MainWindow, which makes + MoveCommands. We do not examine the implementation of DiagramScene + as it only deals with graphics framework issues. + + \section1 The \c main() Function + + The \c main() function of the program looks like this: + + \snippet tools/undoframework/main.cpp 0 + + We draw a grid in the background of the DiagramScene, so we use a + resource file. The rest of the function creates the \c MainWindow and + shows it as a top level window. +*/ |