diff options
Diffstat (limited to 'examples')
25 files changed, 1927 insertions, 0 deletions
diff --git a/examples/designer/doc/images/arthurplugin-demo.png b/examples/designer/doc/images/arthurplugin-demo.png Binary files differnew file mode 100644 index 000000000..6d372c258 --- /dev/null +++ b/examples/designer/doc/images/arthurplugin-demo.png diff --git a/examples/designer/doc/images/calculatorbuilder-example.png b/examples/designer/doc/images/calculatorbuilder-example.png Binary files differnew file mode 100644 index 000000000..561e50005 --- /dev/null +++ b/examples/designer/doc/images/calculatorbuilder-example.png diff --git a/examples/designer/doc/images/calculatorform-example.png b/examples/designer/doc/images/calculatorform-example.png Binary files differnew file mode 100644 index 000000000..91432ac8b --- /dev/null +++ b/examples/designer/doc/images/calculatorform-example.png diff --git a/examples/designer/doc/images/containerextension-example.png b/examples/designer/doc/images/containerextension-example.png Binary files differnew file mode 100644 index 000000000..2427f9101 --- /dev/null +++ b/examples/designer/doc/images/containerextension-example.png diff --git a/examples/designer/doc/images/customwidgetplugin-example.png b/examples/designer/doc/images/customwidgetplugin-example.png Binary files differnew file mode 100644 index 000000000..87fde81a3 --- /dev/null +++ b/examples/designer/doc/images/customwidgetplugin-example.png diff --git a/examples/designer/doc/images/taskmenuextension-dialog.png b/examples/designer/doc/images/taskmenuextension-dialog.png Binary files differnew file mode 100644 index 000000000..7ad6d40bd --- /dev/null +++ b/examples/designer/doc/images/taskmenuextension-dialog.png diff --git a/examples/designer/doc/images/taskmenuextension-example-faded.png b/examples/designer/doc/images/taskmenuextension-example-faded.png Binary files differnew file mode 100644 index 000000000..7e96f3ad8 --- /dev/null +++ b/examples/designer/doc/images/taskmenuextension-example-faded.png diff --git a/examples/designer/doc/images/taskmenuextension-example.png b/examples/designer/doc/images/taskmenuextension-example.png Binary files differnew file mode 100644 index 000000000..f1d46d2b4 --- /dev/null +++ b/examples/designer/doc/images/taskmenuextension-example.png diff --git a/examples/designer/doc/images/taskmenuextension-menu.png b/examples/designer/doc/images/taskmenuextension-menu.png Binary files differnew file mode 100644 index 000000000..d626c81da --- /dev/null +++ b/examples/designer/doc/images/taskmenuextension-menu.png diff --git a/examples/designer/doc/images/worldtimeclock-connection.png b/examples/designer/doc/images/worldtimeclock-connection.png Binary files differnew file mode 100644 index 000000000..42c256003 --- /dev/null +++ b/examples/designer/doc/images/worldtimeclock-connection.png diff --git a/examples/designer/doc/images/worldtimeclock-signalandslot.png b/examples/designer/doc/images/worldtimeclock-signalandslot.png Binary files differnew file mode 100644 index 000000000..d9d3271f4 --- /dev/null +++ b/examples/designer/doc/images/worldtimeclock-signalandslot.png diff --git a/examples/designer/doc/images/worldtimeclockbuilder-example.png b/examples/designer/doc/images/worldtimeclockbuilder-example.png Binary files differnew file mode 100644 index 000000000..4b91af3ff --- /dev/null +++ b/examples/designer/doc/images/worldtimeclockbuilder-example.png diff --git a/examples/designer/doc/images/worldtimeclockplugin-example.png b/examples/designer/doc/images/worldtimeclockplugin-example.png Binary files differnew file mode 100644 index 000000000..89481ade8 --- /dev/null +++ b/examples/designer/doc/images/worldtimeclockplugin-example.png diff --git a/examples/designer/doc/snippets/doc_src_examples_containerextension.pro b/examples/designer/doc/snippets/doc_src_examples_containerextension.pro new file mode 100644 index 000000000..36801f0ae --- /dev/null +++ b/examples/designer/doc/snippets/doc_src_examples_containerextension.pro @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [0] +target.path = $$[QT_INSTALL_PLUGINS]/designer +INSTALLS += target +#! [0] diff --git a/examples/designer/doc/snippets/doc_src_examples_customwidgetplugin.pro b/examples/designer/doc/snippets/doc_src_examples_customwidgetplugin.pro new file mode 100644 index 000000000..36801f0ae --- /dev/null +++ b/examples/designer/doc/snippets/doc_src_examples_customwidgetplugin.pro @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [0] +target.path = $$[QT_INSTALL_PLUGINS]/designer +INSTALLS += target +#! [0] diff --git a/examples/designer/doc/snippets/doc_src_examples_taskmenuextension.pro b/examples/designer/doc/snippets/doc_src_examples_taskmenuextension.pro new file mode 100644 index 000000000..36801f0ae --- /dev/null +++ b/examples/designer/doc/snippets/doc_src_examples_taskmenuextension.pro @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [0] +target.path = $$[QT_INSTALL_PLUGINS]/designer +INSTALLS += target +#! [0] diff --git a/examples/designer/doc/snippets/doc_src_examples_worldtimeclockplugin.pro b/examples/designer/doc/snippets/doc_src_examples_worldtimeclockplugin.pro new file mode 100644 index 000000000..36801f0ae --- /dev/null +++ b/examples/designer/doc/snippets/doc_src_examples_worldtimeclockplugin.pro @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [0] +target.path = $$[QT_INSTALL_PLUGINS]/designer +INSTALLS += target +#! [0] diff --git a/examples/designer/doc/src/arthurplugin.qdoc b/examples/designer/doc/src/arthurplugin.qdoc new file mode 100644 index 000000000..dedbd604d --- /dev/null +++ b/examples/designer/doc/src/arthurplugin.qdoc @@ -0,0 +1,42 @@ +/**************************************************************************** +** +** 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 designer/arthurplugin + \title Arthur Plugin + + In this example we demonstrate the abilities of Qt's painting system + in combination with \QD's custom widget plugin facilities. + + \image arthurplugin-demo.png + + The specialized widgets used in the other examples of the Arthur + painting system are provided as custom widgets to be used with \QD. + Since each of the widgets provides a set of signals and slots, the + effects they show can be controlled by connecting them up to standard + input widgets. +*/ diff --git a/examples/designer/doc/src/calculatorbuilder.qdoc b/examples/designer/doc/src/calculatorbuilder.qdoc new file mode 100644 index 000000000..ce62acc16 --- /dev/null +++ b/examples/designer/doc/src/calculatorbuilder.qdoc @@ -0,0 +1,119 @@ +/**************************************************************************** +** +** 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 designer/calculatorbuilder + \title Calculator Builder Example + + The Calculator Builder example shows how to create a user interface from + a \QD form at run-time, using the QUiLoader class. + + \image calculatorbuilder-example.png + + We use the form created in the \l{designer/calculatorform}{Calculator Form} + example to show that the same user interface can be generated when the + application is executed or defined when the application is built. + + \section1 Preparation + + The \l{designer/calculatorform}{Calculator Form} example defines a user + interface that we can use without modification. In this example, we use a + \l{The Qt Resource System}{resource file} to contain the \c{calculatorform.ui} + file created in the previous example, but it could be stored on disk instead. + + To generate a form at run time, we need to link the example against the + \c QtUiTools module library. The project file we use contains all the + necessary information to do this: + + \snippet designer/calculatorbuilder/calculatorbuilder.pro 0 + + All the other necessary files are declared as usual. + + \section1 CalculatorForm Class Definition + + The \c CalculatorForm class defines the widget used to host the form's + user interface: + + \snippet designer/calculatorbuilder/calculatorform.h 0 + + Note that we do not need to include a header file to describe the user + interface. We only define two public slots, using the auto-connection + naming convention required by \c uic, and declare private variables + that we will use to access widgets provided by the form after they are + constructed. + + \section1 CalculatorForm Class Implementation + + We will need to use the QUiLoader class that is provided by the + \c libQtUiTools library, so we first ensure that we include the header + file for the module: + + \snippet designer/calculatorbuilder/calculatorform.cpp 0 + + The constructor uses a form loader object to construct the user + interface that we retrieve, via a QFile object, from the example's + resources: + + \snippet designer/calculatorbuilder/calculatorform.cpp 1 + + By including the user interface in the example's resources, we ensure + that it will be present when the example is run. The \c{loader.load()} + function takes the user interface description contained in the file + and constructs the form widget as a child widget of the \c{CalculatorForm}. + + We are interested in three widgets in the generated user interface: + two spin boxes and a label. For convenience, we retrieve pointers to + these widgets from the widget that was constructed by the \c FormBuilder, + and we record them for later use. The \c qFindChild() template function + allows us to query widgets in order to find named child widgets. + + \snippet designer/calculatorbuilder/calculatorform.cpp 2 + + The widgets created by the form loader need to be connected to the + specially-named slots in the \c CalculatorForm object. We use Qt's + meta-object system to enable these connections: + + \snippet designer/calculatorbuilder/calculatorform.cpp 3 + + The form widget is added to a layout, and the window title is set: + + \snippet designer/calculatorbuilder/calculatorform.cpp 4 + + The two slots that modify widgets provided by the form are defined + in a similar way to those in the \l{designer/calculatorform}{Calculator + Form} example, except that we read the values from the spin boxes and + write the result to the output widget via the pointers we recorded in + the constructor: + + \snippet designer/calculatorbuilder/calculatorform.cpp 5 + \codeline + \snippet designer/calculatorbuilder/calculatorform.cpp 7 + + The advantage of this approach is that we can replace the form when the + application is run, but we can still manipulate the widgets it contains + as long as they are given appropriate names. +*/ diff --git a/examples/designer/doc/src/calculatorform.qdoc b/examples/designer/doc/src/calculatorform.qdoc new file mode 100644 index 000000000..2fb033c4b --- /dev/null +++ b/examples/designer/doc/src/calculatorform.qdoc @@ -0,0 +1,112 @@ +/**************************************************************************** +** +** 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 designer/calculatorform + \title Calculator Form Example + + The Calculator Form Example shows how to use a form created with + \QD in an application by using the user interface information from + a QWidget subclass. We use \l{Using a Designer UI File in Your Application} + {uic's auto-connection} feature to automatically connect signals + from widgets on the form to slots in our code. + + \image calculatorform-example.png Screenshot of the Calculator Form example + + The example presents two spin boxes that are used to input integer values + and a label that shows their sum. Whenever either of the spin boxes are + updated, the signal-slot connections between the widgets and the form + ensure that the label is also updated. + + \section1 Preparation + + The user interface for this example is designed completely using \QD. The + result is a UI file describing the form, the widgets used, any signal-slot + connections between them, and other standard user interface properties. + + To ensure that the example can use this file, we need to include a \c FORMS + declaration in the example's project file: + + \snippet designer/calculatorform/calculatorform.pro 1 + + When the project is built, \c uic will create a header file that lets us + construct the form. + + \section1 CalculatorForm Class Definition + + The \c CalculatorForm class uses the user interface described in the + \c calculatorform.ui file. To access the form and its contents, we need + to include the \c ui_calculatorform.h header file created by \c uic + during the build process: + + \snippet designer/calculatorform/calculatorform.h 0 + + We define the \c CalculatorForm class by subclassing QWidget because the + form itself is based on QWidget: + + \snippet designer/calculatorform/calculatorform.h 1 + + Apart from the constructor, the class contains two private slots that + are named according to the auto-connection naming convention required + by \c uic. + The private \c ui member variable refers to the form, and is used to + access the contents of the user interface. + + \section1 CalculatorForm Class Implementation + + The constructor simply calls the base class's constructor and + sets up the form's user interface. + + \snippet designer/calculatorform/calculatorform.cpp 0 + + The user interface is set up with the \c setupUI() function. We pass + \c this as the argument to this function to use the \c CalculatorForm + widget itself as the container for the user interface. + + To automatically connect signals from the spin boxes defined in the + user interface, we use the naming convention that indicates which + widgets and their signals in the user interface should be connected + to each slot. The first slot is called whenever the spin box called + "inputSpinBox1" in the user interface emits the + \l{QSpinBox::valueChanged()}{valueChanged()} signal: + + \snippet designer/calculatorform/calculatorform.cpp 1 + + When this occurs, we use the value supplied by the signal to update the + output label by setting its new text directly. We access the output label + and the other spin box via the class's private \c ui variable. + + The second slot is called whenever the second spin box, called + "inputSpinBox2", emits the \l{QSpinBox::valueChanged()}{valueChanged()} + signal: + + \snippet designer/calculatorform/calculatorform.cpp 2 + + In this case, the value from the first spin box is read and combined + with the value supplied by the signal. Again, the output label is + updated directly via the \c ui variable. +*/ diff --git a/examples/designer/doc/src/containerextension.qdoc b/examples/designer/doc/src/containerextension.qdoc new file mode 100644 index 000000000..4836db11d --- /dev/null +++ b/examples/designer/doc/src/containerextension.qdoc @@ -0,0 +1,504 @@ +/**************************************************************************** +** +** 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 designer/containerextension + \title Container Extension Example + + The Container Extension example shows how to create a custom + multi-page plugin for Qt Designer using the + QDesignerContainerExtension class. + + \image containerextension-example.png + + To provide a custom widget that can be used with \QD, we need to + supply a self-contained implementation. In this example we use a + custom multi-page widget designed to show the container extension + feature. + + An extension is an object which modifies the behavior of \QD. The + QDesignerContainerExtension enables \QD to manage and manipulate a + custom multi-page widget, i.e. adding and deleting pages to the + widget. + + There are four available types of extensions in \QD: + + \list + \li QDesignerMemberSheetExtension provides an extension that allows + you to manipulate a widget's member functions which is displayed + when configuring connections using Qt Designer's mode for editing + signals and slots. + \li QDesignerPropertySheetExtension provides an extension that + allows you to manipulate a widget's properties which is displayed + in Qt Designer's property editor. + \li QDesignerTaskMenuExtension provides an extension that allows + you to add custom menu entries to \QD's task menu. + \li QDesignerContainerExtension provides an extension that allows + you to add (and delete) pages to a multi-page container plugin + in \QD. + \endlist + + You can use all the extensions following the same pattern as in + this example, only replacing the respective extension base + class. For more information, see the \l {QtDesigner Module}. + + The Container Extension example consists of four classes: + + \list + \li \c MultiPageWidget is a custom container widget that lets the user + manipulate and populate its pages, and navigate among these + using a combobox. + \li \c MultiPageWidgetPlugin exposes the \c MultiPageWidget class + to \QD. + \li \c MultiPageWidgetExtensionFactory creates a + \c MultiPageWidgetContainerExtension object. + \li \c MultiPageWidgetContainerExtension provides the container + extension. + \endlist + + The project file for custom widget plugins needs some additional + information to ensure that they will work within \QD. For example, + custom widget plugins rely on components supplied with \QD, and + this must be specified in the project file that we use. We will + first take a look at the plugin's project file. + + Then we will continue by reviewing the \c MultiPageWidgetPlugin + class, and take a look at the \c MultiPageWidgetExtensionFactory + and \c MultiPageWidgetContainerExtension classes. Finally, we will + take a quick look at the \c MultiPageWidget class definition. + + \section1 The Project File: containerextension.pro + + The project file must contain some additional information to + ensure that the plugin will work as expected: + + \snippet designer/containerextension/containerextension.pro 0 + \snippet designer/containerextension/containerextension.pro 1 + + The \c TEMPLATE variable's value makes \c qmake create the custom + widget as a library. Later, we will ensure that the widget will be + recognized as a plugin by Qt by using the Q_EXPORT_PLUGIN2() macro + to export the relevant widget information. + + The \c CONFIG variable contains two values, \c designer and \c + plugin: + + \list + \li \c designer: Since custom widgets plugins rely on components + supplied with \QD, this value ensures that our plugin links against + \QD's library (\c libQtDesigner.so). + + \li \c plugin: We also need to ensure that \c qmake considers the + custom widget a \e plugin library. + \endlist + + When Qt is configured to build in both debug and release modes, + \QD will be built in release mode. When this occurs, it is + necessary to ensure that plugins are also built in release + mode. For that reason we add a \c debug_and_release value to the + \c CONFIG variable. Otherwise, if a plugin is built in a mode that + is incompatible with \QD, it won't be loaded and installed. + + The header and source files for the widget are declared in the + usual way: + + \snippet designer/containerextension/containerextension.pro 2 + + We provide an implementation of the plugin interface so that \QD + can use the custom widget. In this particular example we also + provide implementations of the container extension interface and + the extension factory. + + It is important to ensure that the plugin is installed in a + location that is searched by \QD. We do this by specifying a + target path for the project and adding it to the list of items to + install: + + \snippet designer/doc/snippets/doc_src_examples_containerextension.pro 0 + + The container extension is created as a library, and will be + installed alongside the other \QD plugins when the project is + installed (using \c{make install} or an equivalent installation + procedure). + + Note that if you want the plugins to appear in a Visual Studio + integration, the plugins must be built in release mode and their + libraries must be copied into the plugin directory in the install + path of the integration (for an example, see \c {C:/program + files/trolltech as/visual studio integration/plugins}). + + For more information about plugins, see the \l {How to Create Qt + Plugins} documentation. + + \section1 MultiPageWidgetPlugin Class Definition + + The \c MultiPageWidgetPlugin class exposes the \c MultiPageWidget + class to \QD. Its definition is similar to the \l + {designer/customwidgetplugin}{Custom Widget Plugin} example's + plugin class which is explained in detail. The parts of the class + definition that is specific to this particular custom widget is + the class name and a couple of private slots: + + \snippet designer/containerextension/multipagewidgetplugin.h 0 + + The plugin class provides \QD with basic information about our + plugin, such as its class name and its include file. Furthermore + it knows how to create instances of the \c MultiPageWidget widget. + \c MultiPageWidgetPlugin also defines the \l + {QDesignerCustomWidgetInterface::initialize()}{initialize()} + function which is called after the plugin is loaded into \QD. The + function's QDesignerFormEditorInterface parameter provides the + plugin with a gateway to all of \QD's API's. + + In the case of a multipage widget such as ours, we must also implement + two private slots, currentIndexChanged() and pageTitleChanged(), + to be able to update \QD's property editor whenever the user views + another page or changes one of the page titles. To be able to give + each page their own title, we have chosen to use the + QWidget::windowTitle property to store the page title (for more + information see the MultiPageWidget class \l + {designer/containerextension/multipagewidget.cpp}{implementation}). Note + that currently there is no way of adding a custom property (e.g., + a page title) to the pages without using a predefined property as + placeholder. + + The \c MultiPageWidgetPlugin class inherits from both QObject and + QDesignerCustomWidgetInterface. It is important to remember, when + using multiple inheritance, to ensure that all the interfaces + (i.e. the classes that doesn't inherit Q_OBJECT) are made known to + the meta object system using the Q_INTERFACES() macro. This + enables \QD to use \l qobject_cast() to query for supported + interfaces using nothing but a QObject pointer. + + \section1 MultiPageWidgetPlugin Class Implementation + + The MultiPageWidgetPlugin class implementation is in most parts + equivalent to the \l {designer/customwidgetplugin}{Custom Widget + Plugin} example's plugin class: + + \snippet designer/containerextension/multipagewidgetplugin.cpp 0 + \codeline + \snippet designer/containerextension/multipagewidgetplugin.cpp 3 + + One of the functions that differ is the isContainer() function + which returns true in this example since our custom widget is + intended to be used as a container. + + \snippet designer/containerextension/multipagewidgetplugin.cpp 1 + + Another function that differ is the function creating our custom widget: + + \snippet designer/containerextension/multipagewidgetplugin.cpp 2 + + In addition to create and return the widget, we connect our custom + container widget's currentIndexChanged() signal to the plugin's + currentIndexChanged() slot to ensure that \QD's property editor is + updated whenever the user views another page. We also connect the + widget's pageTitleChanged() signal to the plugin's + pageTitleChanged() slot. + + The currentIndexChanged() slot is called whenever our custom + widget's currentIndexChanged() \e signal is emitted, i.e. whenever + the user views another page: + + \snippet designer/containerextension/multipagewidgetplugin.cpp 8 + + First, we retrieve the object emitting the signal using the + QObject::sender() and qobject_cast() functions. If it's called in + a slot activated by a signal, QObject::sender() returns a pointer + to the object that sent the signal; otherwise it returns 0. + + \snippet designer/containerextension/multipagewidgetplugin.cpp 9 + + Once we have the widget we can update the property editor. \QD + uses the QDesignerPropertySheetExtension class to feed its + property editor, and whenever a widget is selected in its + workspace, Qt Designer will query for the widget's property sheet + extension and update the property editor. + + So what we want to achieve is to notify \QD that our widget's \e + internal selection has changed: First we use the static + QDesignerFormWindowInterface::findFormWindow() function to + retrieve the QDesignerFormWindowInterface object containing the + widget. The QDesignerFormWindowInterface class allows you to query + and manipulate form windows appearing in Qt Designer's + workspace. Then, all we have to do is to emit its \l + {QDesignerFormWindowInterface::emitSelectionChanged()}{emitSelectionChanged()} + signal, forcing an update of the property editor. + + When changing a page title a generic refresh of the property + editor is not enough because it is actually the page's property + extension that needs to be updated. For that reason we need to + access the QDesignerPropertySheetExtension object for the page + which title we want to change. The QDesignerPropertySheetExtension + class also allows you to manipulate a widget's properties, but to + get hold of the extension we must first retrieve access to \QD's + extension manager: + + \snippet designer/containerextension/multipagewidgetplugin.cpp 10 + \snippet designer/containerextension/multipagewidgetplugin.cpp 11 + + Again we first retrieve the widget emitting the signal, using the + QObject::sender() and qobject_cast() functions. Then we retrieve + the current page from the widget that emitted the signal, and we + use the static QDesignerFormWindowInterface::findFormWindow() + function to retrieve the form containing our widget. + + \snippet designer/containerextension/multipagewidgetplugin.cpp 12 + + Now that we have the form window, the QDesignerFormWindowInterface + class provides the \l + {QDesignerFormWindowInterface::core()}{core()} function which + returns the current QDesignerFormEditorInterface object. The + QDesignerFormEditorInterface class allows you to access Qt + Designer's various components. In particular, the + QDesignerFormEditorInterface::extensionManager() function returns + a reference to the current extension manager. + + \snippet designer/containerextension/multipagewidgetplugin.cpp 13 + + Once we have the extension manager we can update the extension + sheet: First we retrieve the property extension for the page which + title we want to change, using the qt_extension() function. Then + we retrieve the index for the page title using the + QDesignerPropertySheetExtension::indexOf() function. As previously + mentioned, we have chosen to use the QWidget::windowTitle property + to store the page title (for more information see the + MultiPageWidget class \l + {designer/containerextension/multipagewidget.cpp}{implementation}). + Finally, we implicitly force an update of the page's property + sheet by calling the + QDesignerPropertySheetExtension::setChanged() function. + + \snippet designer/containerextension/multipagewidgetplugin.cpp 4 + + Note also the initialize() function: The \c initialize() function + takes a QDesignerFormEditorInterface object as argument. + + \snippet designer/containerextension/multipagewidgetplugin.cpp 5 + + When creating extensions associated with custom widget plugins, we + need to access \QD's current extension manager which we retrieve + from the QDesignerFormEditorInterface parameter. + + In addition to allowing you to manipulate a widget's properties, + the QExtensionManager class provides extension management + facilities for \QD. Using \QD's current extension manager you can + retrieve the extension for a given object. You can also register + and unregister an extension for a given object. Remember that an + extension is an object which modifies the behavior of \QD. + + When registrering an extension, it is actually the associated + extension factory that is registered. In \QD, extension factories + are used to look up and create named extensions as they are + required. So, in this example, the container extension itself is + not created until \QD must know whether the associated widget is a + container, or not. + + \snippet designer/containerextension/multipagewidgetplugin.cpp 6 + + We create a \c MultiPageWidgetExtensionFactory object that we + register using \QD's current \l {QExtensionManager}{extension + manager} retrieved from the QDesignerFormEditorInterface + parameter. The first argument is the newly created factory and the + second argument is an extension identifier which is a string. The + \c Q_TYPEID() macro simply convert the string into a + QLatin1String. + + The \c MultiPageWidgetExtensionFactory class is a subclass of + QExtensionFactory. When \QD must know whether a widget is a + container, or not, \QD's extension manager will run through all + its registered factories invoking the first one which is able to + create a container extension for that widget. This factory will in + turn create a \c MultiPageWidgetExtension object. + + \snippet designer/containerextension/multipagewidgetplugin.cpp 7 + + Finally, take a look at the \c domXml() function. This function + includes default settings for the widget in the standard XML + format used by \QD. In this case, we specify the container's first + page; any inital pages of a multi-page widget must be specified + within this function. + + \snippet designer/containerextension/multipagewidgetplugin.cpp 14 + + Remember to use the Q_EXPORT_PLUGIN2() macro to export the + MultiPageWidgetPlugin class for use with Qt's plugin handling + classes: This macro ensures that \QD can access and construct the + custom widget. Without this macro, there is no way for \QD to use + the widget. + + \section1 MultiPageWidgetExtensionFactory Class Definition + + The \c MultiPageWidgetExtensionFactory class inherits QExtensionFactory + which provides a standard extension factory for \QD. + + \snippet designer/containerextension/multipagewidgetextensionfactory.h 0 + + The subclass's purpose is to reimplement the + QExtensionFactory::createExtension() function, making it able to + create a \c MultiPageWidget container extension. + + + \section1 MultiPageWidgetExtensionFactory Class Implementation + + The class constructor simply calls the QExtensionFactory base + class constructor: + + \snippet designer/containerextension/multipagewidgetextensionfactory.cpp 0 + + As described above, the factory is invoked when \QD must know + whether the associated widget is a container, or not. + + \snippet designer/containerextension/multipagewidgetextensionfactory.cpp 1 + + \QD's behavior is the same whether the requested extension is + associated with a container, a member sheet, a property sheet or a + task menu: Its extension manager runs through all its registered + extension factories calling \c createExtension() for each until + one responds by creating the requested extension. + + So the first thing we do in \c + MultiPageWidgetExtensionFactory::createExtension() is to check if + the QObject, for which the extension is requested, is in fact a \c + MultiPageWidget object. Then we check if the requested extension + is a container extension. + + If the object is a MultiPageWidget requesting a container + extension, we create and return a \c MultiPageWidgetExtension + object. Otherwise, we simply return a null pointer, allowing \QD's + extension manager to continue its search through the registered + factories. + + + \section1 MultiPageWidgetContainerExtension Class Definition + + The \c MultiPageWidgetContainerExtension class inherits + QDesignerContainerExtension which allows you to add (and delete) + pages to a multi-page container plugin in \QD. + + \snippet designer/containerextension/multipagewidgetcontainerextension.h 0 + + It is important to recognize that the QDesignerContainerExtension + class only is intended to provide \QD access to your custom + multi-page widget's functionality; your custom multi-page widget + must implement functionality corresponding to the extension's + functions. + + Note also that we implement a constructor that takes \e two + arguments: the parent widget, and the \c MultiPageWidget object + for which the task menu is requested. + + QDesignerContainerExtension provides a couple of menu entries in + \QD's task menu by default, enabling the user to add or delete + pages to the associated custom multi-page widget in \QD's + workspace. + + \section1 MultiPageWidgetContainerExtension Class Implementation + + In the constructor we save the reference to the \c MultiPageWidget + object sent as parameter, i.e the widget associated with the + extension. We will need this later to access the custom multi-page + widget performing the requested actions. + + \snippet designer/containerextension/multipagewidgetcontainerextension.cpp 0 + + To fully enable \QD to manage and manipulate your custom + multi-page widget, you must reimplement all the functions of + QDesignerContainerExtension: + + \snippet designer/containerextension/multipagewidgetcontainerextension.cpp 1 + \codeline + \snippet designer/containerextension/multipagewidgetcontainerextension.cpp 2 + \codeline + \snippet designer/containerextension/multipagewidgetcontainerextension.cpp 3 + + You must reimplement \l + {QDesignerContainerExtension::addWidget()}{addWidget()} adding a + given page to the container, \l + {QDesignerContainerExtension::count()}{count()} returning the + number of pages in the container, and \l + {QDesignerContainerExtension::currentIndex()}{currentIndex()} + returning the index of the currently selected page. + + \snippet designer/containerextension/multipagewidgetcontainerextension.cpp 4 + \codeline + \snippet designer/containerextension/multipagewidgetcontainerextension.cpp 5 + \codeline + \snippet designer/containerextension/multipagewidgetcontainerextension.cpp 6 + \codeline + \snippet designer/containerextension/multipagewidgetcontainerextension.cpp 7 + + You must reimplement \l + {QDesignerContainerExtension::insertWidget()}{insertWidget()} + adding a given page to the container at a given index, \l + {QDesignerContainerExtension::remove()}{remove()} deleting the + page at a given index, \l + {QDesignerContainerExtension::setCurrentIndex()}{setCurrentIndex()} + setting the index of the currently selected page, and finally \l + {QDesignerContainerExtension::widget()}{widget()} returning the + page at a given index. + + \section1 MultiPageWidget Class Definition + + The MultiPageWidget class is a custom container widget that lets + the user manipulate and populate its pages, and navigate among + these using a combobox. + + \snippet designer/containerextension/multipagewidget.h 0 + + The main detail to observe is that your custom multi-page widget + must implement functionality corresponding to the + QDesignerContainerExtension's member functions since the + QDesignerContainerExtension class only is intended to provide Qt + Designer access to your custom multi-page widget's functionality. + + In addition, we declare the \c currentIndex and \c pageTitle + properties, and their associated set and get functions. By + declaring these attributes as properties, we allow \QD to manage + them in the same way it manages the properties the MultiPageWidget + widget inherits from QWidget and QObject, for example featuring + the property editor. + + Note the \c STORED attribute in the declaration of the \c + pageTitle property: The \c STORED attribute indicates persistence, + i.e. it declares whether the property's value must be remembered + when storing an object's state. As mentioned above, we have chosen + to store the page title using the QWidget::windowTitle property to + be able to give each page their own title. For that reason the \c + pageTitle property is a "fake" property, provided for editing + purposes, and doesn't need to be stored. + + We must also implement and emit the currentIndexChanged() and + pageTitleChanged() signals to ensure that \QD's property editor is + updated whenever the user views another page or changes one of the + page titles. + + See the MultiPageWidget class \l + {designer/containerextension/multipagewidget.cpp}{implementation} + for more details. +*/ diff --git a/examples/designer/doc/src/customwidgetplugin.qdoc b/examples/designer/doc/src/customwidgetplugin.qdoc new file mode 100644 index 000000000..0e6ca3aa5 --- /dev/null +++ b/examples/designer/doc/src/customwidgetplugin.qdoc @@ -0,0 +1,238 @@ +/**************************************************************************** +** +** 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 designer/customwidgetplugin + \title Custom Widget Plugin Example + + The Custom Widget example shows how to create a custom widget plugin for \QD. + + \image customwidgetplugin-example.png + + In this example, the custom widget used is based on the + \l{widgets/analogclock}{Analog Clock example}, and does not provide any custom + signals or slots. + + \section1 Preparation + + To provide a custom widget that can be used with \QD, we need to supply a + self-contained implementation and provide a plugin interface. In this + example, we reuse the \l{widgets/analogclock}{Analog Clock example} for + convenience. + + Since custom widgets plugins rely on components supplied with \QD, the + project file that we use needs to contain information about \QD's + library components: + + \snippet designer/customwidgetplugin/customwidgetplugin.pro 2 + \snippet designer/customwidgetplugin/customwidgetplugin.pro 0 + + The \c TEMPLATE variable's value makes \c qmake create the custom + widget as a library. Later, we will ensure that the widget will be + recognized as a plugin by Qt by using the Q_EXPORT_PLUGIN2() macro + to export the relevant widget information. + + The \c CONFIG variable contains two values, \c designer and \c + plugin: + + \list + + \li \c designer: Since custom widgets plugins rely on components + supplied with \QD, this value ensures that our plugin links + against \QD's library (\c libQtDesigner.so). + + \li \c plugin: We also need to ensure that \c qmake considers the + custom widget a plugin library. + + \endlist + + When Qt is configured to build in both debug and release modes, + \QD will be built in release mode. When this occurs, it is + necessary to ensure that plugins are also built in release + mode. For that reason we add the \c debug_and_release value to the + \c CONFIG variable. Otherwise, if a plugin is built in a mode that + is incompatible with \QD, it won't be loaded and + installed. + + The header and source files for the widget are declared in the usual way, + and we provide an implementation of the plugin interface so that \QD can + use the custom widget: + + \snippet designer/customwidgetplugin/customwidgetplugin.pro 3 + + It is also important to ensure that the plugin is installed in a + location that is searched by \QD. We do this by specifying a + target path for the project and adding it to the list of items to + install: + + \snippet designer/doc/snippets/doc_src_examples_customwidgetplugin.pro 0 + + The custom widget is created as a library, and will be installed + alongside the other \QD plugins when the project is installed + (using \c{make install} or an equivalent installation procedure). + Later, we will ensure that it is recognized as a plugin by \QD by + using the Q_EXPORT_PLUGIN2() macro to export the relevant widget + information. + + Note that if you want the plugins to appear in a Visual Studio + integration, the plugins must be built in release mode and their + libraries must be copied into the plugin directory in the install + path of the integration (for an example, see \c {C:/program + files/trolltech as/visual studio integration/plugins}). + + For more information about plugins, see the \l {How to + Create Qt Plugins} documentation. + + \section1 AnalogClock Class Definition and Implementation + + The \c AnalogClock class is defined and implemented in exactly the same + way as described in the \l{widgets/analogclock}{Analog Clock example}. + Since the class is self-contained, and does not require any external + configuration, it can be used without modification as a custom widget in + \QD. + + \section1 AnalogClockPlugin Class Definition + + The \c AnalogClock class is exposed to \QD through the \c + AnalogClockPlugin class. This class inherits from both QObject and + the QDesignerCustomWidgetInterface class, and implements an + interface defined by QDesignerCustomWidgetInterface: + + \snippet designer/customwidgetplugin/customwidgetplugin.h 0 + + The functions provide information about the widget that \QD can use in + the \l{Getting to Know Qt Designer#WidgetBox}{widget box}. + The \c initialized private member variable is used to record whether + the plugin has been initialized by \QD. + + Note that the only part of the class definition that is specific to + this particular custom widget is the class name. + + \section1 AnalogClockPlugin Implementation + + The class constructor simply calls the QObject base class constructor + and sets the \c initialized variable to \c false. + + \snippet designer/customwidgetplugin/customwidgetplugin.cpp 0 + + \QD will initialize the plugin when it is required by calling the + \c initialize() function: + + \snippet designer/customwidgetplugin/customwidgetplugin.cpp 1 + + In this example, the \c initialized private variable is tested, and only + set to \c true if the plugin is not already initialized. Although, this + plugin does not require any special code to be executed when it is + initialized, we could include such code after the test for initialization. + + The \c isInitialized() function lets \QD know whether the plugin is + ready for use: + + \snippet designer/customwidgetplugin/customwidgetplugin.cpp 2 + + Instances of the custom widget are supplied by the \c createWidget() + function. The implementation for the analog clock is straightforward: + + \snippet designer/customwidgetplugin/customwidgetplugin.cpp 3 + + In this case, the custom widget only requires a \c parent to be specified. + If other arguments need to be supplied to the widget, they can be + introduced here. + + The following functions provide information for \QD to use to represent + the widget in the widget box. + The \c name() function returns the name of class that provides the + custom widget: + + \snippet designer/customwidgetplugin/customwidgetplugin.cpp 4 + + The \c group() function is used to describe the type of widget that the + custom widget belongs to: + + \snippet designer/customwidgetplugin/customwidgetplugin.cpp 5 + + The widget plugin will be placed in a section identified by its + group name in \QD's widget box. The icon used to represent the + widget in the widget box is returned by the \c icon() function: + + \snippet designer/customwidgetplugin/customwidgetplugin.cpp 6 + + In this case, we return a null icon to indicate that we have no icon + that can be used to represent the widget. + + A tool tip and "What's This?" help can be supplied for the custom widget's + entry in the widget box. The \c toolTip() function should return a short + message describing the widget: + + \snippet designer/customwidgetplugin/customwidgetplugin.cpp 7 + + The \c whatsThis() function can return a longer description: + + \snippet designer/customwidgetplugin/customwidgetplugin.cpp 8 + + The \c isContainer() function tells \QD whether the widget is supposed to + be used as a container for other widgets. If not, \QD will not allow the + user to place widgets inside it. + + \snippet designer/customwidgetplugin/customwidgetplugin.cpp 9 + + Most widgets in Qt can contain child widgets, but it only makes sense + to use dedicated container widgets for this purpose in \QD. By returning + \c false, we indicate that the custom widget cannot hold other widgets; + if we returned true, \QD would allow other widgets to be placed inside + the analog clock and a layout to be defined. + + The \c domXml() function provides a way to include default settings for + the widget in the standard XML format used by \QD. In this case, we only + specify the widget's geometry: + + \snippet designer/customwidgetplugin/customwidgetplugin.cpp 10 + + If the widget provides a reasonable size hint, it is not necessary to + define it here. In addition, returning an empty string instead of a + \c{<widget>} element will tell \QD not to install the widget in the + widget box. + + To make the analog clock widget usable by applications, we implement + the \c includeFile() function to return the name of the header file + containing the custom widget class definition: + + \snippet designer/customwidgetplugin/customwidgetplugin.cpp 12 + + Finally, we use the Q_EXPORT_PLUGIN2() macro to export the \c + AnalogClockPlugin class for use with \QD: + + \snippet designer/customwidgetplugin/customwidgetplugin.cpp 13 + + This macro ensures that \QD can access and construct the custom widget. + Without this macro, there is no way for \QD to use the widget. + + It is important to note that you can only use the Q_EXPORT_PLUGIN2() + macro once in any implementation. If you have several custom widgets in + an implementation that you wish to make available to \QD, you will need + to implement \l{QDesignerCustomWidgetCollectionInterface}. +*/ diff --git a/examples/designer/doc/src/taskmenuextension.qdoc b/examples/designer/doc/src/taskmenuextension.qdoc new file mode 100644 index 000000000..f42887345 --- /dev/null +++ b/examples/designer/doc/src/taskmenuextension.qdoc @@ -0,0 +1,443 @@ +/**************************************************************************** +** +** 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 designer/taskmenuextension + \title Task Menu Extension Example + + The Task Menu Extension example shows how to create a custom + widget plugin for \l {Qt Designer Manual}{\QD}, and how to to use + the QDesignerTaskMenuExtension class to provide custom task menu + entries associated with the plugin. + + \image taskmenuextension-example-faded.png + + To provide a custom widget that can be used with \QD, we need to + supply a self-contained implementation. In this example we use a + custom widget designed to show the task menu extension feature: + The TicTacToe widget. + + An extension is an object which modifies the behavior of \QD. The + QDesignerTaskMenuExtension can provide custom task menu entries + when a widget with this extension is selected. + + There are four available types of extensions in \QD: + + \list + \li QDesignerContainerExtension provides an extension that allows + you to add (and delete) pages to a multi-page container plugin + in \QD. + \li QDesignerMemberSheetExtension provides an extension that allows + you to manipulate a widget's member functions which is displayed + when configuring connections using Qt Designer's mode for editing + signals and slots. + \li QDesignerPropertySheetExtension provides an extension that + allows you to manipulate a widget's properties which is displayed + in Qt Designer's property editor. + \li QDesignerTaskMenuExtension provides an extension that allows + you to add custom menu entries to \QD's task menu. + \endlist + + You can use all the extensions following the same pattern as in + this example, only replacing the respective extension base + class. For more information, see the \l {QtDesigner Module}. + + The Task Menu Extension example consists of five classes: + + \list + \li \c TicTacToe is a custom widget that lets the user play + the Tic-Tac-Toe game. + \li \c TicTacToePlugin exposes the \c TicTacToe class to \QD. + \li \c TicTacToeTaskMenuFactory creates a \c TicTacToeTaskMenu object. + \li \c TicTacToeTaskMenu provides the task menu extension, i.e the + plugin's associated task menu entries. + \li \c TicTacToeDialog lets the user modify the state of a + Tic-Tac-Toe plugin loaded into \QD. + \endlist + + The project file for custom widget plugins needs some additional + information to ensure that they will work within \QD. For example, + custom widget plugins rely on components supplied with \QD, and + this must be specified in the project file that we use. We will + first take a look at the plugin's project file. + + Then we will continue by reviewing the \c TicTacToePlugin class, + and take a look at the \c TicTacToeTaskMenuFactory and \c + TicTacToeTaskMenu classes. Finally, we will review the \c + TicTacToeDialog class before we take a quick look at the \c + TicTacToe widget's class definition. + + \section1 The Project File: taskmenuextension.pro + + The project file must contain some additional information to + ensure that the plugin will work as expected: + + \snippet designer/taskmenuextension/taskmenuextension.pro 0 + \snippet designer/taskmenuextension/taskmenuextension.pro 1 + + The \c TEMPLATE variable's value makes \c qmake create the custom + widget as a library. Later, we will ensure that the widget will be + recognized as a plugin by Qt by using the Q_EXPORT_PLUGIN2() macro to + export the relevant widget information. + + The \c CONFIG variable contains two values, \c designer and \c + plugin: + + \list + \li \c designer: Since custom widgets plugins rely on components + supplied with \QD, this value ensures that our plugin links against + \QD's library (\c libQtDesigner.so). + + \li \c plugin: We also need to ensure that \c qmake considers the + custom widget a \e plugin library. + \endlist + + When Qt is configured to build in both debug and release modes, + \QD will be built in release mode. When this occurs, it is + necessary to ensure that plugins are also built in release + mode. For that reason we add the \c debug_and_release value to + the \c CONFIG variable. Otherwise, if a plugin is built in a mode + that is incompatible with \QD, it won't be loaded and + installed. + + The header and source files for the widget are declared in the + usual way: + + \snippet designer/taskmenuextension/taskmenuextension.pro 2 + + We provide an implementation of the plugin interface so that \QD + can use the custom widget. In this particular example we also + provide implementations of the task menu extension and the + extension factory as well as a dialog implementation. + + It is important to ensure that the plugin is installed in a + location that is searched by \QD. We do this by specifying a + target path for the project and adding it to the list of items to + install: + + \snippet designer/doc/snippets/doc_src_examples_taskmenuextension.pro 0 + + The task menu extension is created as a library, and will be + installed alongside the other \QD plugins when the project is + installed (using \c{make install} or an equivalent installation + procedure). + + Note that if you want the plugins to appear in a Visual Studio + integration, the plugins must be built in release mode and their + libraries must be copied into the plugin directory in the install + path of the integration (for an example, see \c {C:/program + files/trolltech as/visual studio integration/plugins}). + + For more information about plugins, see the \l {How to Create Qt + Plugins} documentation. + + \section1 TicTacToePlugin Class Definition + + The \c TicTacToePlugin class exposes \c the TicTacToe class to + \QD. Its definition is equivalent to the \l + {designer/customwidgetplugin}{Custom Widget Plugin} example's + plugin class which is explained in detail. The only part of the + class definition that is specific to this particular custom widget + is the class name: + + \snippet designer/taskmenuextension/tictactoeplugin.h 0 + + The plugin class provides \QD with basic information about our + plugin, such as its class name and its include file. Furthermore + it knows how to create instances of the \c TicTacToe widget. + TicTacToePlugin also defines the \l + {QDesignerCustomWidgetInterface::initialize()}{initialize()} + function which is called after the plugin is loaded into \QD. The + function's QDesignerFormEditorInterface parameter provides the + plugin with a gateway to all of \QD's API's. + + The \c TicTacToePlugin class inherits from both QObject and + QDesignerCustomWidgetInterface. It is important to remember, when + using multiple inheritance, to ensure that all the interfaces + (i.e. the classes that doesn't inherit Q_OBJECT) are made known to + the meta object system using the Q_INTERFACES() macro. This + enables \QD to use \l qobject_cast() to query for supported + interfaces using nothing but a QObject pointer. + + \section1 TicTacToePlugin Class Implementation + + The TicTacToePlugin class implementation is in most parts + equivalent to the \l {designer/customwidgetplugin}{Custom Widget + Plugin} example's plugin class: + + \snippet designer/taskmenuextension/tictactoeplugin.cpp 0 + + The only function that differs significantly is the initialize() + function: + + \snippet designer/taskmenuextension/tictactoeplugin.cpp 1 + + The \c initialize() function takes a QDesignerFormEditorInterface + object as argument. The QDesignerFormEditorInterface class + provides access to Qt Designer's components. + + In \QD you can create two kinds of plugins: custom widget plugins + and tool plugins. QDesignerFormEditorInterface provides access to + all the \QD components that you normally need to create a tool + plugin: the extension manager, the object inspector, the property + editor and the widget box. Custom widget plugins have access to + the same components. + + \snippet designer/taskmenuextension/tictactoeplugin.cpp 2 + + When creating extensions associated with custom widget plugins, we + need to access \QD's current extension manager which we retrieve + from the QDesignerFormEditorInterface parameter. + + \QD's QDesignerFormEditorInterface holds information about all Qt + Designer's components: The action editor, the object inspector, + the property editor, the widget box, and the extension and form + window managers. + + The QExtensionManager class provides extension management + facilities for \QD. Using \QD's current extension manager you can + retrieve the extension for a given object. You can also register + and unregister an extension for a given object. Remember that an + extension is an object which modifies the behavior of \QD. + + When registrering an extension, it is actually the associated + extension factory that is registered. In \QD, extension factories + are used to look up and create named extensions as they are + required. So, in this example, the task menu extension itself is + not created until a task menu is requested by the user. + + \snippet designer/taskmenuextension/tictactoeplugin.cpp 3 + + We create a \c TicTacToeTaskMenuFactory object that we register + using \QD's current \l {QExtensionManager}{extension manager} + retrieved from the QDesignerFormEditorInterface parameter. The + first argument is the newly created factory and the second + argument is an extension identifier which is a string. The \c + Q_TYPEID() macro simply converts the string into a QLatin1String. + + The \c TicTacToeTaskMenuFactory class is a subclass of + QExtensionFactory. When the user request a task menu by clicking + the right mouse button over a widget with the specified task menu + extension, \QD's extension manager will run through all its + registered factories invoking the first one that is able to create + a task menu extension for the selected widget. This factory will + in turn create a \c TicTacToeTaskMenu object (the extension). + + We omit to reimplement the + QDesignerCustomWidgetInterface::domXml() function (which include + default settings for the widget in the standard XML format used by + Qt Designer), since no default values are necessary. + + \snippet designer/taskmenuextension/tictactoeplugin.cpp 4 + + Finally, we use the Q_EXPORT_PLUGIN2() macro to export the + TicTacToePlugin class for use with Qt's plugin handling classes: + This macro ensures that \QD can access and construct the custom + widget. Without this macro, there is no way for \QD to use the + widget. + + \section1 TicTacToeTaskMenuFactory Class Definition + + The \c TicTacToeTaskMenuFactory class inherits QExtensionFactory + which provides a standard extension factory for \QD. + + \snippet designer/taskmenuextension/tictactoetaskmenu.h 1 + + The subclass's purpose is to reimplement the + QExtensionFactory::createExtension() function, making it able to + create a \c TicTacToe task menu extension. + + \section1 TicTacToeTaskMenuFactory Class Implementation + + The class constructor simply calls the QExtensionFactory base + class constructor: + + \snippet designer/taskmenuextension/tictactoetaskmenu.cpp 4 + + As described above, the factory is invoked when the user request a + task menu by clicking the right mouse button over a widget with + the specified task menu extension in \QD. + + \QD's behavior is the same whether the requested extension is + associated with a container, a member sheet, a property sheet or a + task menu: Its extension manager runs through all its registered + extension factories calling \c createExtension() for each until + one responds by creating the requested extension. + + \snippet designer/taskmenuextension/tictactoetaskmenu.cpp 5 + + So the first thing we do in \c + TicTacToeTaskMenuFactory::createExtension() is to check if the + requested extension is a task menu extension. If it is, and the + widget requesting it is a \c TicTacToe widget, we create and + return a \c TicTacToeTaskMenu object. Otherwise, we simply return + a null pointer, allowing \QD's extension manager to continue its + search through the registered factories. + + + \section1 TicTacToeTaskMenu Class Definition + + \image taskmenuextension-menu.png + + The \c TicTacToeTaskMenu class inherits QDesignerTaskMenuExtension + which allows you to add custom entries (in the form of QActions) + to the task menu in \QD. + + \snippet designer/taskmenuextension/tictactoetaskmenu.h 0 + + We reimplement the \c preferredEditAction() and \c taskActions() + functions. Note that we implement a constructor that takes \e two + arguments: the parent widget, and the \c TicTacToe widget for + which the task menu is requested. + + In addition we declare the private \c editState() slot, our custom + \c editStateAction and a private pointer to the \c TicTacToe + widget which state we want to modify. + + \section1 TicTacToeTaskMenu Class Implementation + + \snippet designer/taskmenuextension/tictactoetaskmenu.cpp 0 + + In the constructor we first save the reference to the \c TicTacToe + widget sent as parameter, i.e the widget which state we want to + modify. We will need this later when our custom action is + invoked. We also create our custom \c editStateAction and connect + it to the \c editState() slot. + + \snippet designer/taskmenuextension/tictactoetaskmenu.cpp 1 + + The \c editState() slot is called whenever the user chooses the + \gui {Edit State...} option in a \c TicTacToe widget's task menu. The + slot creates a \c TicTacToeDialog presenting the current state of + the widget, and allowing the user to edit its state by playing the + game. + + \snippet designer/taskmenuextension/tictactoetaskmenu.cpp 2 + + We reimplement the \c preferredEditAction() function to return our + custom \c editStateAction as the action that should be invoked + when selecting a \c TicTacToe widget and pressing \key F2 . + + \snippet designer/taskmenuextension/tictactoetaskmenu.cpp 3 + + We reimplement the \c taskActions() function to return a list of + our custom actions making these appear on top of the default menu + entries in a \c TicTacToe widget's task menu. + + \section1 TicTacToeDialog Class Definition + + \image taskmenuextension-dialog.png + + The \c TicTacToeDialog class inherits QDialog. The dialog lets the + user modify the state of the currently selected Tic-Tac-Toe + plugin. + + \snippet designer/taskmenuextension/tictactoedialog.h 0 + + We reimplement the \c sizeHint() function. We also declare two + private slots: \c resetState() and \c saveState(). In addition to + the dialog's buttons and layouts we declare two \c TicTacToe + pointers, one to the widget the user can interact with and the + other to the original custom widget plugin which state the user + wants to edit. + + \section1 TicTacToeDialog Class Implementation + + \snippet designer/taskmenuextension/tictactoedialog.cpp 0 + + In the constructor we first save the reference to the TicTacToe + widget sent as parameter, i.e the widget which state the user want + to modify. Then we create a new \c TicTacToe widget, and set its + state to be equivalent to the parameter widget's state. + + Finally, we create the dialog's buttons and layout. + + \snippet designer/taskmenuextension/tictactoedialog.cpp 1 + + We reimplement the \c sizeHint() function to ensure that the + dialog is given a reasonable size. + + \snippet designer/taskmenuextension/tictactoedialog.cpp 2 + + The \c resetState() slot is called whenever the user press the + \gui Reset button. The only thing we do is to call the \c + clearBoard() function for the editor widget, i.e. the \c TicTacToe + widget we created in the dialog's constructor. + + \snippet designer/taskmenuextension/tictactoedialog.cpp 3 + + The \c saveState() slot is called whenever the user press the \gui + OK button, and transfers the state of the editor widget to the + widget which state we want to modify. In order to make the change + of state visible to \QD we need to set the latter widget's state + property using the QDesignerFormWindowInterface class. + + QDesignerFormWindowInterface provides you with information about + the associated form window as well as allowing you to alter its + properties. The interface is not intended to be instantiated + directly, but to provide access to Qt Designer's current form + windows controlled by Qt Designer's form window manager. + + If you are looking for the form window containing a specific + widget, you can use the static + QDesignerFormWindowInterface::findFormWindow() function: + + \snippet designer/taskmenuextension/tictactoedialog.cpp 4 + + After retrieving the form window of the widget (which state we + want to modify), we use the QDesignerFormWindowInterface::cursor() + function to retrieve the form window's cursor. + + The QDesignerFormWindowCursorInterface class provides an interface + to the form window's text cursor. Once we have cursor, we can + finally set the state property using the + QDesignerFormWindowCursorInterface::setProperty() function. + + \snippet designer/taskmenuextension/tictactoedialog.cpp 5 + + In the end we call the QEvent::accept() function which sets the + accept flag of the event object. Setting the \c accept parameter + indicates that the event receiver wants the event. Unwanted events + might be propagated to the parent widget. + + \section1 TicTacToe Class Definition + + The \c TicTacToe class is a custom widget that lets the user play + the Tic-Tac-Toe game. + + \snippet designer/taskmenuextension/tictactoe.h 0 + + The main details to observe in the \c TicTacToe class defintion is + the declaration of the \c state property and its \c state() and \c + setState() functions. + + We need to declare the \c TicTacToe widget's state as a property + to make it visible to \QD; allowing \QD to manage it in the same + way it manages the properties the \c TicTacToe widget inherits + from QWidget and QObject, for example featuring the property + editor. +*/ diff --git a/examples/designer/doc/src/worldtimeclockbuilder.qdoc b/examples/designer/doc/src/worldtimeclockbuilder.qdoc new file mode 100644 index 000000000..1f2f055d9 --- /dev/null +++ b/examples/designer/doc/src/worldtimeclockbuilder.qdoc @@ -0,0 +1,97 @@ +/**************************************************************************** +** +** 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 designer/worldtimeclockbuilder + \title World Time Clock Builder Example + + The World Time Clock Builder example shows how forms created with Qt + Designer that contain custom widgets can be dynamically generated at + run-time. + + \image worldtimeclockbuilder-example.png + + This example uses a form containing the custom widget plugin described in the + \l{designer/worldtimeclockplugin}{World Time Clock Plugin} example, and + dynamically generates a user interface using the QUiLoader class, part of + the QtUiTools module. + + \section1 Preparation + + As with the \l{designer/calculatorbuilder}{Calculator Builder} example, the + project file for this example needs to include the appropriate definitions + to ensure that it is built against the required Qt modules. + + \snippet designer/worldtimeclockbuilder/worldtimeclockbuilder.pro 0 + + By appending \c form to the \c CONFIG declaration, we instruct \c qmake to + generate a dependency on the \c libQtUiTools library containing the QtUiTools + classes. + + Note that we do not inform \c qmake about any UI files, and so none will + be processed and built into the application. The resource file contains + an entry for the particular form that we wish to use: + + \quotefile designer/worldtimeclockbuilder/worldtimeclockbuilder.qrc + + Forms do not need to be included with the application in this way. We only + include a form in the application's resources for convenience, and to keep + the example short. + + \section1 Loading and Building the Form + + Since this example only loads and displays a pre-prepared form, all of the + work can be done in the main() function. We are using a class from the + QtUiTools library so, in addition to any other Qt classes that are normally + required to write an application, we must include the appropriate header + file: + + \snippet designer/worldtimeclockbuilder/main.cpp 0 + + The main function initializes the resource system with the Q_INIT_RESOURCE() + macro and constructs an QApplication instance in the usual way: + + \snippet designer/worldtimeclockbuilder/main.cpp 1 + + We construct a QUiLoader object to handle the form we want to use. + + The form itself is obtained from the resource file system using the path + defined in the resource file. We use the form loader to load and construct + the form: + + \snippet designer/worldtimeclockbuilder/main.cpp 2 + + Once the form has been loaded, the resource file can be closed and the + widget is shown. + + \snippet designer/worldtimeclockbuilder/main.cpp 3 + + The form loader ensures that all the signal and slot connections between + objects in the form are set up correctly when the form is loaded. As a + result, the time is updated by the World Time Clock widget, and the time + zone spin box can be used to change the position of the hour hand. +*/ diff --git a/examples/designer/doc/src/worldtimeclockplugin.qdoc b/examples/designer/doc/src/worldtimeclockplugin.qdoc new file mode 100644 index 000000000..57ce8d9f3 --- /dev/null +++ b/examples/designer/doc/src/worldtimeclockplugin.qdoc @@ -0,0 +1,196 @@ +/**************************************************************************** +** +** 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 designer/worldtimeclockplugin + \title World Time Clock Plugin Example + + The World Time Clock Plugin example shows how to create a custom + widget plugin for \QD that uses signals and slots. + + \image worldtimeclockplugin-example.png + + In this example, we simply extend the \l + {designer/customwidgetplugin}{Custom Widget Plugin} example and + its custom widget (based on the \l{widgets/analogclock}{Analog + Clock} example), by introducing the concept of signals and slots. + + The World Time Clock Plugin example consists of two classes: + + \list + \li \c WorldTimeClock is a custom clock widget with hour and + minute hands that is automatically updated every few seconds. + \li \c WorldTimeClockPlugin exposes the \c WorldTimeClock class to \QD. + \endlist + + First we will take a look at the \c WorldTimeClock class which + extends the \l {designer/customwidgetplugin}{Custom Widget Plugin} + example's \c AnalogClock class by providing a signal and a + slot. Then we will take a quick look at the \c + WorldTimeClockPlugin class, but this class is in most parts + identical to the \l {designer/customwidgetplugin}{Custom Widget + Plugin} example's implementation. + + Finally we take a look at the plugin's project file. The project + file for custom widget plugins needs some additional information + to ensure that they will work within \QD. This is also covered in + the \l {designer/customwidgetplugin}{Custom Widget Plugin} example, + but due to its importance (custom widget plugins rely on + components supplied with \QD which must be specified in the + project file that we use) we will repeat it here. + + \section1 WorldTimeClock Class + + The \c WorldTimeClock class inherits QWidget, and is a custom + clock widget with hour and minute hands that is automatically + updated every few seconds. What makes this example different from + the \l {designer/customwidgetplugin}{Custom Widget Plugin} + example, is the introduction of the signal and slot in the custom + widget class: + + \snippet designer/worldtimeclockplugin/worldtimeclock.h 1 + + Note the use of the QDESIGNER_WIDGET_EXPORT macro. This is needed + to ensure that \QD can create instances of the widget on some + platforms, but it is a good idea to use it on all platforms. + + We declare the \c setTimeZone() slot with an associated \c + timeZoneOffset variable, and we declare an \c updated() signal + which takes the current time as argument and is emitted whenever + the widget is repainted. + + \image worldtimeclock-connection.png + + In \QD's workspace we can then, for example, connect the \c + WorldTimeClock widget's \c updated() signal to a QTimeEdit's \l + {QDateTimeEdit::setTime()}{setTime()} slot using \QD's mode + for editing signal and slots. + + \image worldtimeclock-signalandslot.png + + We can also connect a QSpinBox's \l + {QSpinBox::valueChanged()}{valueChanged()} signal to the \c + WorldTimeClock's \c setTimeZone() slot. + + \section1 WorldTimeClockPlugin Class + + The \c WorldTimeClockPlugin class exposes the \c WorldTimeClock + class to \QD. Its definition is equivalent to the \l + {designer/customwidgetplugin}{Custom Widget Plugin} example's + plugin class which is explained in detail. The only part of the + class definition that is specific to this particular custom widget + is the class name: + + \snippet designer/worldtimeclockplugin/worldtimeclockplugin.h 0 + + The plugin class provides \QD with basic information about our + plugin, such as its class name and its include file. Furthermore + it knows how to create instances of the \c WorldTimeClockPlugin + widget. \c WorldTimeClockPlugin also defines the \l + {QDesignerCustomWidgetInterface::initialize()}{initialize()} + function which is called after the plugin is loaded into \QD. The + function's QDesignerFormEditorInterface parameter provides the + plugin with a gateway to all of \QD's API's. + + The \c WorldTimeClockPlugin class inherits from both QObject and + QDesignerCustomWidgetInterface. It is important to remember, when + using multiple inheritance, to ensure that all the interfaces + (i.e. the classes that doesn't inherit Q_OBJECT) are made known to + the meta object system using the Q_INTERFACES() macro. This + enables \QD to use \l qobject_cast() to query for supported + interfaces using nothing but a QObject pointer. + + The implementation of the \c WorldTimeClockPlugin is also + equivalent to the plugin interface implementation in the \l + {designer/customwidgetplugin}{Custom Widget Plugin} example (only + the class name and the implementation of + QDesignerCustomWidgetInterface::domXml() differ). The main thing + to remember is to use the Q_EXPORT_PLUGIN2() macro to export the \c + WorldTimeClockPlugin class for use with \QD: + + \snippet designer/worldtimeclockplugin/worldtimeclockplugin.cpp 0 + + Without this macro, there is no way for Qt Designer to use the + widget. + + \section1 The Project File: worldtimeclockplugin.pro + + The project file for custom widget plugins needs some additional + information to ensure that they will work as expected within \QD: + + \snippet designer/worldtimeclockplugin/worldtimeclockplugin.pro 0 + \snippet designer/worldtimeclockplugin/worldtimeclockplugin.pro 1 + + The \c TEMPLATE variable's value make \c qmake create the custom + widget as a library. The \c CONFIG variable contains two values, + \c designer and \c plugin: + + \list + \li \c designer: Since custom widgets plugins rely on components + supplied with \QD, this value ensures that our plugin links against + \QD's library (\c libQtDesigner.so). + + \li \c plugin: We also need to ensure that \c qmake considers the + custom widget a \e plugin library. + \endlist + + When Qt is configured to build in both debug and release modes, + \QD will be built in release mode. When this occurs, it is + necessary to ensure that plugins are also built in release + mode. For that reason you might have to add a \c release value to + your \c CONFIG variable. Otherwise, if a plugin is built in a mode + that is incompatible with \QD, it won't be loaded and + installed. + + The header and source files for the widget are declared in the + usual way, and in addition we provide an implementation of the + plugin interface so that \QD can use the custom widget. + + \snippet designer/worldtimeclockplugin/worldtimeclockplugin.pro 2 + + It is important to ensure that the plugin is installed in a location that + is searched by \QD. We do this by specifying a target path for the project + and adding it to the list of items to install: + + \snippet designer/doc/snippets/doc_src_examples_worldtimeclockplugin.pro 0 + + The custom widget is created as a library, and will be installed + alongside the other \QD plugins when the project is installed + (using \c{make install} or an equivalent installation procedure). + Later, we will ensure that it is recognized as a plugin by \QD by + using the Q_EXPORT_PLUGIN2() macro to export the relevant widget + information. + + Note that if you want the plugins to appear in a Visual Studio + integration, the plugins must be built in release mode and their + libraries must be copied into the plugin directory in the install + path of the integration (for an example, see \c {C:/program + files/trolltech as/visual studio integration/plugins}). + + For more information about plugins, see the \l {How to Create Qt + Plugins} document. +*/ |