diff options
Diffstat (limited to 'examples/tools/doc/styleplugin.qdoc')
-rw-r--r-- | examples/tools/doc/styleplugin.qdoc | 133 |
1 files changed, 133 insertions, 0 deletions
diff --git a/examples/tools/doc/styleplugin.qdoc b/examples/tools/doc/styleplugin.qdoc new file mode 100644 index 0000000000..0a55a7c29d --- /dev/null +++ b/examples/tools/doc/styleplugin.qdoc @@ -0,0 +1,133 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example 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 + + 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., plastique). + + 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 + inherits QWindowsStyle and contributes to widget styling by + drawing button backgrounds in red - not a major contribution, but + it still makes a new style. 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 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 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 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 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 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. +*/ |