diff options
Diffstat (limited to 'examples/designer/doc')
12 files changed, 176 insertions, 165 deletions
diff --git a/examples/designer/doc/snippets/doc_src_examples_containerextension.pro b/examples/designer/doc/snippets/doc_src_examples_containerextension.pro index 36801f0ae..f2ad22298 100644 --- a/examples/designer/doc/snippets/doc_src_examples_containerextension.pro +++ b/examples/designer/doc/snippets/doc_src_examples_containerextension.pro @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 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. diff --git a/examples/designer/doc/snippets/doc_src_examples_customwidgetplugin.pro b/examples/designer/doc/snippets/doc_src_examples_customwidgetplugin.pro index 36801f0ae..f2ad22298 100644 --- a/examples/designer/doc/snippets/doc_src_examples_customwidgetplugin.pro +++ b/examples/designer/doc/snippets/doc_src_examples_customwidgetplugin.pro @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 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. diff --git a/examples/designer/doc/snippets/doc_src_examples_taskmenuextension.pro b/examples/designer/doc/snippets/doc_src_examples_taskmenuextension.pro index 36801f0ae..f2ad22298 100644 --- a/examples/designer/doc/snippets/doc_src_examples_taskmenuextension.pro +++ b/examples/designer/doc/snippets/doc_src_examples_taskmenuextension.pro @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 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. diff --git a/examples/designer/doc/snippets/doc_src_examples_worldtimeclockplugin.pro b/examples/designer/doc/snippets/doc_src_examples_worldtimeclockplugin.pro index 36801f0ae..f2ad22298 100644 --- a/examples/designer/doc/snippets/doc_src_examples_worldtimeclockplugin.pro +++ b/examples/designer/doc/snippets/doc_src_examples_worldtimeclockplugin.pro @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 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. diff --git a/examples/designer/doc/src/arthurplugin.qdoc b/examples/designer/doc/src/arthurplugin.qdoc index dedbd604d..0f5e5a2de 100644 --- a/examples/designer/doc/src/arthurplugin.qdoc +++ b/examples/designer/doc/src/arthurplugin.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 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. @@ -26,11 +26,11 @@ ****************************************************************************/ /*! - \example designer/arthurplugin + \example arthurplugin + \ingroup examples-designer \title Arthur Plugin - In this example we demonstrate the abilities of Qt's painting system - in combination with \QD's custom widget plugin facilities. + \brief Using the Qt painting system with \QD custom widget plugins. \image arthurplugin-demo.png diff --git a/examples/designer/doc/src/calculatorbuilder.qdoc b/examples/designer/doc/src/calculatorbuilder.qdoc index ce62acc16..054b0524d 100644 --- a/examples/designer/doc/src/calculatorbuilder.qdoc +++ b/examples/designer/doc/src/calculatorbuilder.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 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. @@ -26,21 +26,21 @@ ****************************************************************************/ /*! - \example designer/calculatorbuilder + \example calculatorbuilder + \ingroup examples-designer \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. + \brief Creating a user interface from a \QD form at run-time. \image calculatorbuilder-example.png - We use the form created in the \l{designer/calculatorform}{Calculator Form} + We use the form created in the \l{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 + The \l{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. @@ -49,7 +49,7 @@ \c QtUiTools module library. The project file we use contains all the necessary information to do this: - \snippet designer/calculatorbuilder/calculatorbuilder.pro 0 + \snippet calculatorbuilder/calculatorbuilder.pro 0 All the other necessary files are declared as usual. @@ -58,7 +58,7 @@ The \c CalculatorForm class defines the widget used to host the form's user interface: - \snippet designer/calculatorbuilder/calculatorform.h 0 + \snippet 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 @@ -72,13 +72,13 @@ \c libQtUiTools library, so we first ensure that we include the header file for the module: - \snippet designer/calculatorbuilder/calculatorform.cpp 0 + \snippet 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 + \snippet 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()} @@ -91,27 +91,27 @@ 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 + \snippet 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 + \snippet calculatorbuilder/calculatorform.cpp 3 The form widget is added to a layout, and the window title is set: - \snippet designer/calculatorbuilder/calculatorform.cpp 4 + \snippet 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 + in a similar way to those in the \l{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 + \snippet calculatorbuilder/calculatorform.cpp 5 \codeline - \snippet designer/calculatorbuilder/calculatorform.cpp 7 + \snippet 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 diff --git a/examples/designer/doc/src/calculatorform.qdoc b/examples/designer/doc/src/calculatorform.qdoc index 2fb033c4b..1b5aac885 100644 --- a/examples/designer/doc/src/calculatorform.qdoc +++ b/examples/designer/doc/src/calculatorform.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 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. @@ -26,9 +26,12 @@ ****************************************************************************/ /*! - \example designer/calculatorform + \example calculatorform + \ingroup examples-designer \title Calculator Form Example + \brief Using a form created with \QD in an application. + 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} @@ -51,7 +54,7 @@ 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 + \snippet calculatorform/calculatorform.pro 1 When the project is built, \c uic will create a header file that lets us construct the form. @@ -63,12 +66,12 @@ to include the \c ui_calculatorform.h header file created by \c uic during the build process: - \snippet designer/calculatorform/calculatorform.h 0 + \snippet 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 + \snippet 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 @@ -81,7 +84,7 @@ The constructor simply calls the base class's constructor and sets up the form's user interface. - \snippet designer/calculatorform/calculatorform.cpp 0 + \snippet 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 @@ -94,7 +97,7 @@ "inputSpinBox1" in the user interface emits the \l{QSpinBox::valueChanged()}{valueChanged()} signal: - \snippet designer/calculatorform/calculatorform.cpp 1 + \snippet 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 @@ -104,7 +107,7 @@ "inputSpinBox2", emits the \l{QSpinBox::valueChanged()}{valueChanged()} signal: - \snippet designer/calculatorform/calculatorform.cpp 2 + \snippet 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 diff --git a/examples/designer/doc/src/containerextension.qdoc b/examples/designer/doc/src/containerextension.qdoc index 4836db11d..d24f3360b 100644 --- a/examples/designer/doc/src/containerextension.qdoc +++ b/examples/designer/doc/src/containerextension.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 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. @@ -26,11 +26,14 @@ ****************************************************************************/ /*! - \example designer/containerextension + \example containerextension + \ingroup examples-designer \title Container Extension Example - The Container Extension example shows how to create a custom - multi-page plugin for Qt Designer using the + \brief Creating a custom multi-page plugin for \QD. + + The Container Extension example shows how to create a custom multi-page + plugin for \QD using the QDesignerContainerExtension class. \image containerextension-example.png @@ -64,7 +67,7 @@ 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}. + class. For more information, see \l{Qt Designer C++ Classes}. The Container Extension example consists of four classes: @@ -96,12 +99,12 @@ 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 + \snippet containerextension/containerextension.pro 0 + \snippet 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 + recognized as a plugin by Qt by using the Q_PLUGIN_METADATA() macro to export the relevant widget information. The \c CONFIG variable contains two values, \c designer and \c @@ -126,7 +129,7 @@ The header and source files for the widget are declared in the usual way: - \snippet designer/containerextension/containerextension.pro 2 + \snippet 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 @@ -138,7 +141,7 @@ 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 + \snippet 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 @@ -158,12 +161,12 @@ 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 + {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 + \snippet 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 @@ -181,7 +184,7 @@ 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 + {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. @@ -197,22 +200,22 @@ \section1 MultiPageWidgetPlugin Class Implementation The MultiPageWidgetPlugin class implementation is in most parts - equivalent to the \l {designer/customwidgetplugin}{Custom Widget + equivalent to the \l {customwidgetplugin}{Custom Widget Plugin} example's plugin class: - \snippet designer/containerextension/multipagewidgetplugin.cpp 0 + \snippet containerextension/multipagewidgetplugin.cpp 0 \codeline - \snippet designer/containerextension/multipagewidgetplugin.cpp 3 + \snippet 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 + \snippet containerextension/multipagewidgetplugin.cpp 1 Another function that differ is the function creating our custom widget: - \snippet designer/containerextension/multipagewidgetplugin.cpp 2 + \snippet 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 @@ -225,14 +228,14 @@ widget's currentIndexChanged() \e signal is emitted, i.e. whenever the user views another page: - \snippet designer/containerextension/multipagewidgetplugin.cpp 8 + \snippet 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 + \snippet containerextension/multipagewidgetplugin.cpp 9 Once we have the widget we can update the property editor. \QD uses the QDesignerPropertySheetExtension class to feed its @@ -259,8 +262,8 @@ 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 + \snippet containerextension/multipagewidgetplugin.cpp 10 + \snippet containerextension/multipagewidgetplugin.cpp 11 Again we first retrieve the widget emitting the signal, using the QObject::sender() and qobject_cast() functions. Then we retrieve @@ -268,7 +271,7 @@ use the static QDesignerFormWindowInterface::findFormWindow() function to retrieve the form containing our widget. - \snippet designer/containerextension/multipagewidgetplugin.cpp 12 + \snippet containerextension/multipagewidgetplugin.cpp 12 Now that we have the form window, the QDesignerFormWindowInterface class provides the \l @@ -279,7 +282,7 @@ QDesignerFormEditorInterface::extensionManager() function returns a reference to the current extension manager. - \snippet designer/containerextension/multipagewidgetplugin.cpp 13 + \snippet 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 @@ -289,17 +292,17 @@ 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}). + {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 + \snippet 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 + \snippet containerextension/multipagewidgetplugin.cpp 5 When creating extensions associated with custom widget plugins, we need to access \QD's current extension manager which we retrieve @@ -319,7 +322,7 @@ not created until \QD must know whether the associated widget is a container, or not. - \snippet designer/containerextension/multipagewidgetplugin.cpp 6 + \snippet containerextension/multipagewidgetplugin.cpp 6 We create a \c MultiPageWidgetExtensionFactory object that we register using \QD's current \l {QExtensionManager}{extension @@ -336,7 +339,7 @@ create a container extension for that widget. This factory will in turn create a \c MultiPageWidgetExtension object. - \snippet designer/containerextension/multipagewidgetplugin.cpp 7 + \snippet 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 @@ -344,9 +347,9 @@ page; any inital pages of a multi-page widget must be specified within this function. - \snippet designer/containerextension/multipagewidgetplugin.cpp 14 + \snippet containerextension/multipagewidgetplugin.h 1 - Remember to use the Q_EXPORT_PLUGIN2() macro to export the + Remember to use the Q_PLUGIN_METADATA() 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 @@ -357,7 +360,7 @@ The \c MultiPageWidgetExtensionFactory class inherits QExtensionFactory which provides a standard extension factory for \QD. - \snippet designer/containerextension/multipagewidgetextensionfactory.h 0 + \snippet containerextension/multipagewidgetextensionfactory.h 0 The subclass's purpose is to reimplement the QExtensionFactory::createExtension() function, making it able to @@ -369,12 +372,12 @@ The class constructor simply calls the QExtensionFactory base class constructor: - \snippet designer/containerextension/multipagewidgetextensionfactory.cpp 0 + \snippet 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 + \snippet 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 @@ -401,7 +404,7 @@ QDesignerContainerExtension which allows you to add (and delete) pages to a multi-page container plugin in \QD. - \snippet designer/containerextension/multipagewidgetcontainerextension.h 0 + \snippet containerextension/multipagewidgetcontainerextension.h 0 It is important to recognize that the QDesignerContainerExtension class only is intended to provide \QD access to your custom @@ -425,17 +428,17 @@ extension. We will need this later to access the custom multi-page widget performing the requested actions. - \snippet designer/containerextension/multipagewidgetcontainerextension.cpp 0 + \snippet 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 + \snippet containerextension/multipagewidgetcontainerextension.cpp 1 \codeline - \snippet designer/containerextension/multipagewidgetcontainerextension.cpp 2 + \snippet containerextension/multipagewidgetcontainerextension.cpp 2 \codeline - \snippet designer/containerextension/multipagewidgetcontainerextension.cpp 3 + \snippet containerextension/multipagewidgetcontainerextension.cpp 3 You must reimplement \l {QDesignerContainerExtension::addWidget()}{addWidget()} adding a @@ -445,13 +448,13 @@ {QDesignerContainerExtension::currentIndex()}{currentIndex()} returning the index of the currently selected page. - \snippet designer/containerextension/multipagewidgetcontainerextension.cpp 4 + \snippet containerextension/multipagewidgetcontainerextension.cpp 4 \codeline - \snippet designer/containerextension/multipagewidgetcontainerextension.cpp 5 + \snippet containerextension/multipagewidgetcontainerextension.cpp 5 \codeline - \snippet designer/containerextension/multipagewidgetcontainerextension.cpp 6 + \snippet containerextension/multipagewidgetcontainerextension.cpp 6 \codeline - \snippet designer/containerextension/multipagewidgetcontainerextension.cpp 7 + \snippet containerextension/multipagewidgetcontainerextension.cpp 7 You must reimplement \l {QDesignerContainerExtension::insertWidget()}{insertWidget()} @@ -469,7 +472,7 @@ the user manipulate and populate its pages, and navigate among these using a combobox. - \snippet designer/containerextension/multipagewidget.h 0 + \snippet containerextension/multipagewidget.h 0 The main detail to observe is that your custom multi-page widget must implement functionality corresponding to the @@ -499,6 +502,6 @@ page titles. See the MultiPageWidget class \l - {designer/containerextension/multipagewidget.cpp}{implementation} + {containerextension/multipagewidget.cpp}{implementation} for more details. */ diff --git a/examples/designer/doc/src/customwidgetplugin.qdoc b/examples/designer/doc/src/customwidgetplugin.qdoc index 51765568c..a85fd7b78 100644 --- a/examples/designer/doc/src/customwidgetplugin.qdoc +++ b/examples/designer/doc/src/customwidgetplugin.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 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. @@ -26,10 +26,11 @@ ****************************************************************************/ /*! - \example designer/customwidgetplugin + \example customwidgetplugin + \ingroup examples-designer \title Custom Widget Plugin Example - The Custom Widget example shows how to create a custom widget plugin for \QD. + \brief Creating a custom widget plugin for Qt Designer. \image customwidgetplugin-example.png @@ -48,12 +49,12 @@ 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 + \snippet customwidgetplugin/customwidgetplugin.pro 2 + \snippet 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 + recognized as a plugin by Qt by using the Q_PLUGIN_METADATA() macro to export the relevant widget information. The \c CONFIG variable contains two values, \c designer and \c @@ -82,20 +83,20 @@ and we provide an implementation of the plugin interface so that \QD can use the custom widget: - \snippet designer/customwidgetplugin/customwidgetplugin.pro 3 + \snippet 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 + \snippet 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 + using the Q_PLUGIN_METADATA() macro to export the relevant widget information. Note that if you want the plugins to appear in a Visual Studio @@ -122,7 +123,7 @@ the QDesignerCustomWidgetInterface class, and implements an interface defined by QDesignerCustomWidgetInterface: - \snippet designer/customwidgetplugin/customwidgetplugin.h 0 + \snippet 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}. @@ -137,12 +138,12 @@ 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 + \snippet 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 + \snippet 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 @@ -152,12 +153,12 @@ The \c isInitialized() function lets \QD know whether the plugin is ready for use: - \snippet designer/customwidgetplugin/customwidgetplugin.cpp 2 + \snippet 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 + \snippet 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 @@ -168,18 +169,18 @@ The \c name() function returns the name of class that provides the custom widget: - \snippet designer/customwidgetplugin/customwidgetplugin.cpp 4 + \snippet 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 + \snippet 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 + \snippet 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. @@ -188,17 +189,17 @@ entry in the widget box. The \c toolTip() function should return a short message describing the widget: - \snippet designer/customwidgetplugin/customwidgetplugin.cpp 7 + \snippet customwidgetplugin/customwidgetplugin.cpp 7 The \c whatsThis() function can return a longer description: - \snippet designer/customwidgetplugin/customwidgetplugin.cpp 8 + \snippet 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 + \snippet 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 @@ -210,7 +211,7 @@ 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 + \snippet 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 @@ -221,5 +222,5 @@ the \c includeFile() function to return the name of the header file containing the custom widget class definition: - \snippet designer/customwidgetplugin/customwidgetplugin.cpp 12 + \snippet customwidgetplugin/customwidgetplugin.cpp 12 */ diff --git a/examples/designer/doc/src/taskmenuextension.qdoc b/examples/designer/doc/src/taskmenuextension.qdoc index f42887345..315fc4484 100644 --- a/examples/designer/doc/src/taskmenuextension.qdoc +++ b/examples/designer/doc/src/taskmenuextension.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 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. @@ -26,9 +26,13 @@ ****************************************************************************/ /*! - \example designer/taskmenuextension + \example taskmenuextension + \ingroup examples-designer \title Task Menu Extension Example + \brief Creating a custom widget plugin for \QD and providing custom task + menu entries that are associated with the plugin. + 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 @@ -64,7 +68,7 @@ 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}. + class. For more information, see the \l{Qt Designer C++ Classes}. The Task Menu Extension example consists of five classes: @@ -96,12 +100,12 @@ 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 + \snippet taskmenuextension/taskmenuextension.pro 0 + \snippet 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 + recognized as a plugin by Qt by using the Q_PLUGIN_METADATA() macro to export the relevant widget information. The \c CONFIG variable contains two values, \c designer and \c @@ -127,7 +131,7 @@ The header and source files for the widget are declared in the usual way: - \snippet designer/taskmenuextension/taskmenuextension.pro 2 + \snippet 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 @@ -139,7 +143,7 @@ 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 + \snippet 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 @@ -159,12 +163,12 @@ 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 + {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 + \snippet 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 @@ -186,15 +190,15 @@ \section1 TicTacToePlugin Class Implementation The TicTacToePlugin class implementation is in most parts - equivalent to the \l {designer/customwidgetplugin}{Custom Widget + equivalent to the \l {customwidgetplugin}{Custom Widget Plugin} example's plugin class: - \snippet designer/taskmenuextension/tictactoeplugin.cpp 0 + \snippet taskmenuextension/tictactoeplugin.cpp 0 The only function that differs significantly is the initialize() function: - \snippet designer/taskmenuextension/tictactoeplugin.cpp 1 + \snippet taskmenuextension/tictactoeplugin.cpp 1 The \c initialize() function takes a QDesignerFormEditorInterface object as argument. The QDesignerFormEditorInterface class @@ -207,7 +211,7 @@ editor and the widget box. Custom widget plugins have access to the same components. - \snippet designer/taskmenuextension/tictactoeplugin.cpp 2 + \snippet taskmenuextension/tictactoeplugin.cpp 2 When creating extensions associated with custom widget plugins, we need to access \QD's current extension manager which we retrieve @@ -230,7 +234,7 @@ 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 + \snippet taskmenuextension/tictactoeplugin.cpp 3 We create a \c TicTacToeTaskMenuFactory object that we register using \QD's current \l {QExtensionManager}{extension manager} @@ -252,9 +256,9 @@ 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 + \snippet taskmenuextension/tictactoeplugin.h 1 - Finally, we use the Q_EXPORT_PLUGIN2() macro to export the + Finally, we use the Q_PLUGIN_METADATA() 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 @@ -265,7 +269,7 @@ The \c TicTacToeTaskMenuFactory class inherits QExtensionFactory which provides a standard extension factory for \QD. - \snippet designer/taskmenuextension/tictactoetaskmenu.h 1 + \snippet taskmenuextension/tictactoetaskmenu.h 1 The subclass's purpose is to reimplement the QExtensionFactory::createExtension() function, making it able to @@ -276,7 +280,7 @@ The class constructor simply calls the QExtensionFactory base class constructor: - \snippet designer/taskmenuextension/tictactoetaskmenu.cpp 4 + \snippet 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 @@ -288,7 +292,7 @@ extension factories calling \c createExtension() for each until one responds by creating the requested extension. - \snippet designer/taskmenuextension/tictactoetaskmenu.cpp 5 + \snippet taskmenuextension/tictactoetaskmenu.cpp 5 So the first thing we do in \c TicTacToeTaskMenuFactory::createExtension() is to check if the @@ -307,7 +311,7 @@ which allows you to add custom entries (in the form of QActions) to the task menu in \QD. - \snippet designer/taskmenuextension/tictactoetaskmenu.h 0 + \snippet taskmenuextension/tictactoetaskmenu.h 0 We reimplement the \c preferredEditAction() and \c taskActions() functions. Note that we implement a constructor that takes \e two @@ -320,7 +324,7 @@ \section1 TicTacToeTaskMenu Class Implementation - \snippet designer/taskmenuextension/tictactoetaskmenu.cpp 0 + \snippet 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 @@ -328,7 +332,7 @@ invoked. We also create our custom \c editStateAction and connect it to the \c editState() slot. - \snippet designer/taskmenuextension/tictactoetaskmenu.cpp 1 + \snippet 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 @@ -336,13 +340,13 @@ the widget, and allowing the user to edit its state by playing the game. - \snippet designer/taskmenuextension/tictactoetaskmenu.cpp 2 + \snippet 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 + \snippet 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 @@ -356,7 +360,7 @@ user modify the state of the currently selected Tic-Tac-Toe plugin. - \snippet designer/taskmenuextension/tictactoedialog.h 0 + \snippet taskmenuextension/tictactoedialog.h 0 We reimplement the \c sizeHint() function. We also declare two private slots: \c resetState() and \c saveState(). In addition to @@ -367,7 +371,7 @@ \section1 TicTacToeDialog Class Implementation - \snippet designer/taskmenuextension/tictactoedialog.cpp 0 + \snippet 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 @@ -376,19 +380,19 @@ Finally, we create the dialog's buttons and layout. - \snippet designer/taskmenuextension/tictactoedialog.cpp 1 + \snippet 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 + \snippet 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 + \snippet 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 @@ -406,7 +410,7 @@ widget, you can use the static QDesignerFormWindowInterface::findFormWindow() function: - \snippet designer/taskmenuextension/tictactoedialog.cpp 4 + \snippet taskmenuextension/tictactoedialog.cpp 4 After retrieving the form window of the widget (which state we want to modify), we use the QDesignerFormWindowInterface::cursor() @@ -417,7 +421,7 @@ finally set the state property using the QDesignerFormWindowCursorInterface::setProperty() function. - \snippet designer/taskmenuextension/tictactoedialog.cpp 5 + \snippet 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 @@ -429,7 +433,7 @@ The \c TicTacToe class is a custom widget that lets the user play the Tic-Tac-Toe game. - \snippet designer/taskmenuextension/tictactoe.h 0 + \snippet 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 diff --git a/examples/designer/doc/src/worldtimeclockbuilder.qdoc b/examples/designer/doc/src/worldtimeclockbuilder.qdoc index 1f2f055d9..f4d69f853 100644 --- a/examples/designer/doc/src/worldtimeclockbuilder.qdoc +++ b/examples/designer/doc/src/worldtimeclockbuilder.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 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. @@ -26,27 +26,27 @@ ****************************************************************************/ /*! - \example designer/worldtimeclockbuilder + \example worldtimeclockbuilder + \ingroup examples-designer \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. + \brief Creating forms with Qt Designer that contain custom widgets that 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 + \l{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 + As with the \l{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 + \snippet 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 @@ -56,7 +56,7 @@ 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 + \quotefile 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 @@ -70,12 +70,12 @@ required to write an application, we must include the appropriate header file: - \snippet designer/worldtimeclockbuilder/main.cpp 0 + \snippet 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 + \snippet worldtimeclockbuilder/main.cpp 1 We construct a QUiLoader object to handle the form we want to use. @@ -83,12 +83,12 @@ defined in the resource file. We use the form loader to load and construct the form: - \snippet designer/worldtimeclockbuilder/main.cpp 2 + \snippet 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 + \snippet 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 diff --git a/examples/designer/doc/src/worldtimeclockplugin.qdoc b/examples/designer/doc/src/worldtimeclockplugin.qdoc index 57ce8d9f3..90dfd01a6 100644 --- a/examples/designer/doc/src/worldtimeclockplugin.qdoc +++ b/examples/designer/doc/src/worldtimeclockplugin.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 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. @@ -26,16 +26,16 @@ ****************************************************************************/ /*! - \example designer/worldtimeclockplugin + \example worldtimeclockplugin + \ingroup examples-designer \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. + \brief Creating 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 + {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. @@ -48,17 +48,17 @@ \endlist First we will take a look at the \c WorldTimeClock class which - extends the \l {designer/customwidgetplugin}{Custom Widget Plugin} + extends the \l {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 + identical to the \l {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, + the \l {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. @@ -68,11 +68,11 @@ 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} + the \l {customwidgetplugin}{Custom Widget Plugin} example, is the introduction of the signal and slot in the custom widget class: - \snippet designer/worldtimeclockplugin/worldtimeclock.h 1 + \snippet 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 @@ -100,12 +100,12 @@ 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 + {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 + \snippet 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 @@ -126,13 +126,13 @@ The implementation of the \c WorldTimeClockPlugin is also equivalent to the plugin interface implementation in the \l - {designer/customwidgetplugin}{Custom Widget Plugin} example (only + {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 + to remember is to use the Q_PLUGIN_METADATA() macro to export the \c WorldTimeClockPlugin class for use with \QD: - \snippet designer/worldtimeclockplugin/worldtimeclockplugin.cpp 0 + \snippet worldtimeclockplugin/worldtimeclockplugin.h 1 Without this macro, there is no way for Qt Designer to use the widget. @@ -142,8 +142,8 @@ 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 + \snippet worldtimeclockplugin/worldtimeclockplugin.pro 0 + \snippet 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, @@ -170,19 +170,19 @@ 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 + \snippet 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 + \snippet 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 + using the Q_PLUGIN_METADATA() macro to export the relevant widget information. Note that if you want the plugins to appear in a Visual Studio |