Редактирование: Extending Qt Designer

{{menu_Qt_Издания}}

by Vivi Glьckstad Karlsen

<blockquote>'''The Qt 4 release incorporated a new multi-component[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]].One of the main ideas behind the new version of ''Qt Designer'' was toprovide the application as a collection of interchangeable components. It iscomplemented by the QtDesigner module, a library that you can use to writeplugins and extensions for [[Qt:Документация_4.3.2/designer-manual  | Qt Designer]],as this article will show.'''
__TOC__
</blockquote>
This article begins by taking a closer look at how you can create yourown custom widget plugins, and then goes on to describe how you canextend and access [[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'scomponents using the classes provided by the[[Qt:Документация_4.3.2/qtdesigner  | QtDesigner]] module.

The module also makes it possible to embed[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s components intoIntegrated Development Environments (IDEs), a more advanced topic thatwe will not cover here.

== Creating a Custom Widget Plugin ==
In [[Qt:Документация_4.3.2/designer-manual  | Qt Designer]], the widget boxcomponent provides a selection of standard Qt widgets, layouts, and otherobjects that can be added to the forms by dragging them from the widget boxand dropping them where they are required.

Using the [[Qt:Документация_4.3.2/qtdesigner  | QtDesigner]] module, you can createcustom widget plugins that will appear in the widget box, and that can beadded to forms using the same simple approach. In fact, writing acustom widget plugin is one of the more common ways to extend[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]],and all the Qt 3 support widgets are integrated into[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]] this way.

When creating a custom widget plugin, you must supply a self-containedimplementation of the custom widget. If you want the plugin's properties to beavailable and editable in [[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'sproperty editor, you must ensure that the properties are declared using the[http://www.crossplatform.ru/documentation/qtdoc4.3/qobject.php#Q_PROPERTY Q_PROPERTY()] macro.[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]] uses Qt's propertysystem to populate the editor, and if a property is declared in some other way,[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]] won't know about it.

You can implement several different extensions to make your widget even moreinteractive with [[Qt:Документация_4.3.2/designer-manual  | Qt Designer]].A container extension, for example, allows the user to add pages and widgetsto a custom ''multi-page container'' widget (like a widget stack or tabwidget) within [[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'sworkspace. We will come back to the subject of extensions later.

== Exposing the Plugin to Qt Designer ==
To expose a custom widget to[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]], and give enoughinformation to construct the widget, you must provide it with an interfacederived from the[[Qt:Документация_4.3.2/qdesignercustomwidgetinterface  | QDesignerCustomWidgetInterface]]class, located in the QtDesigner module.

{| align="center"
|- 
|[[Image:qq16-creatingplugin.png|center]]
|}

While some of the[[Qt:Документация_4.3.2/qdesignercustomwidgetinterface  | QDesignerCustomWidgetInterface]]functions are pure virtual and must be reimplemented, others are not alwaysrelevant and can safely be omitted, such as the <tt>codeTemplate()</tt> thatreturns code to be included in <tt>.ui</tt> files, and the <tt>domXml()</tt>function that returns XML to describe the custom widget's default properties in[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]].

Custom plugins also declare the interface that they expose with the[http://www.crossplatform.ru/documentation/qtdoc4.3/qobject.php#Q_INTERFACES Q_INTERFACES()] macro.

A typical custom widget plugin is defined like this:
<source lang="cpp-qt">
#include <QDesignerCustomWidgetInterface>

class MyPlugin : public QObject,
                 public QDesignerCustomWidgetInterface
{
    Q_OBJECT
    Q_INTERFACES(QDesignerCustomWidgetInterface)

public:
    MyPlugin(QObject *parent = 0);

    QString name() const;
    QString group() const;
    QString toolTip() const;
    QString whatsThis() const;
    QString includeFile() const;
    QIcon icon() const;
    bool isContainer() const;
    QWidget *createWidget(QWidget *parent);
    bool isInitialized() const;
    void initialize(QDesignerFormEditorInterface *editor);
    QString codeTemplate() const;
    QString domXml() const;

private:
    bool initialized;
};
</source> 
The documentation for the[[Qt:Документация_4.3.2/designer-customwidgetplugin  | Custom Widget Plugin]]example, supplied with Qt, provides a detailed description of these functions.The main issue to have in mind when implementing the plugin class, is that youmust remember to export the plugin:
<source lang="cpp-qt">
Q_EXPORT_PLUGIN2(mypluginsname, MyPlugin)
</source> 
This macro ensures that the plugin can be accessed and constructed. Without it,[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]] cannot use the customwidget.

In most cases, exporting the plugin in this way is sufficient to ensure that[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]] and other applicationscan access the widget when using <tt>uic</tt> or with Qt's dynamic form loadingfacilities. If you want to use the custom widget directly by linking yourapplication against the plugin, you must export the custom widget classexplicitly in the following way:
<source lang="cpp-qt">
#include <QDesignerExportWidget>

class QDESIGNER_WIDGET_EXPORT MyWidget : public QWidget
{
    Q_OBJECT
   
public:
    MyWidget(QWidget *parent = 0);
}
</source> 
With a self-contained custom widget implementation and anassociated interface in place, we need to add some information to thecorresponding <tt>.pro</tt> file:
<source lang="cpp-qt">
TEMPLATE      = lib
CONFIG       += designer plugin debug_and_release
HEADERS       = mywidget.h \
                mywidgetplugin.h 
SOURCES       = mywidget.cpp \
                mywidgetplugin.cpp 
</source> 
The <tt>TEMPLATE</tt> and <tt>CONFIG</tt> lines tell <tt>qmake</tt> to create alibrary that is suitable for use as a[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]] plugin, relying oncomponents supplied with [[Qt:Документация_4.3.2/designer-manual  | Qt Designer]].This means that the plugin will link against the <tt>designer</tt> library(e.g., <tt>libQtDesigner.so</tt> on Unix).

The header and source files for the custom widget aredeclared in the usual way, and in addition we provide theimplementation of the plugin interface.
<source lang="cpp-qt">
target.path   = $$[QT_INSTALL_PLUGINS]/designer
INSTALLS     += target
</source> 
The <tt>target.path</tt> and <tt>INSTALL</tt> lines ensure that the pluginis installed alongside the other[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]] widget plugins.

Provided that everything compiles and links,[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]] will add the customwidget to its widget box. Note that if a plugin is built in a mode that isincompatible with [[Qt:Документация_4.3.2/designer-manual  | Qt Designer]], itwon't be loaded. The <tt>debug_and_release</tt> value is added to the<tt>CONFIG</tt> definition to ensure that our plugin will be loaded no matterhow [[Qt:Документация_4.3.2/designer-manual  | Qt Designer]] was built.

For more information about plugins, see the[[Qt:Документация_4.3.2/plugins-howto  | How to Create Qt Plugins]] page in Qt'sreference documentation.

<div id="theextensionsclasses"></div>
==The Extensions Classes ==
When implementing a custom multi-page container widget, you can make[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]] recognize it as suchby providing it with an appropriate interface in addition to the plugininterface. Derive the interface from the[[Qt:Документация_4.3.2/qdesignercontainerextension  | QDesignerContainerExtension]]class provided by the QtDesigner module.

There are four available extension classes in the module: 
*[[Qt:Документация_4.3.2/qdesignertaskmenuextension  | QDesignerTaskMenuExtension]] 
*[[Qt:Документация_4.3.2/qdesignercontainerextension  | QDesignerContainerExtension]] 
*[[Qt:Документация_4.3.2/qdesignerpropertysheetextension  | QDesignerPropertySheetExtension]] 
*[[Qt:Документация_4.3.2/qdesignermembersheetextension  | QDesignerMemberSheetExtension]]
These extensions can be used in a variety of situations:[[Qt:Документация_4.3.2/qdesignercontainerextension  | QDesignerContainerExtension]]provides an interface that you can implement to allow custom multi-pagecontainer widgets to be manipulated within[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]], while the[[Qt:Документация_4.3.2/qdesignertaskmenuextension  | QDesignerTaskMenuExtension]]class allows you to add custom menu entries to[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s task menu.

[[Qt:Документация_4.3.2/qdesignerpropertysheetextension  | QDesignerPropertySheetExtension]]and [[Qt:Документация_4.3.2/qdesignermembersheetextension  | QDesignerMemberSheetExtension]]let you manipulate the appearance of a widget's properties and member functionsin [[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s differentcomponents and editing modes. All widgets in[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]] have a default membersheet which is used by the signals and slots editing mode, and a defaultproperty sheet that is used to populate[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s property editor.By reimplementing a member or property sheet extension, you can (and will)override the defaults. In other situations, you might want to use theseinterfaces to check if a particular member or property is supported by a givenwidget.

<div id="creatinganextension"></div>
== Creating an Extension ==
To create an extension, you must first subclass the relevant extensionclass and reimplement its pure virtual functions. For example, acontainer extension's definition might look like this:
<source lang="cpp-qt">
class MyContainerExtension : public QObject,
        public QDesignerContainerExtension
{
    Q_OBJECT
    Q_INTERFACES(QDesignerContainerExtension)

public:
    MyContainerExtension(MyContainerWidget *widget,
                         QObject *parent);

    void addWidget(QWidget *widget);
    int count() const;
    int currentIndex() const;
    void insertWidget(int index, QWidget *widget);
    void remove(int index);
    void setCurrentIndex(int index);
    QWidget *widget(int index) const;

private:
    MyContainerWidget *containerWidget;
};
</source> 
Be aware that although it is called[[Qt:Документация_4.3.2/qdesignercontainerextension  | QDesignerContainerExtension]]class, the class really encapsulates ''multi-page'' widgets, such as[[Qt:Документация_4.3.2/qtabwidget  | QTabWidget]] and[[Qt:Документация_4.3.2/qstackedwidget  | QStackedWidget]]. This means that yourwidget must have a suitable page-based API. For example:
<source lang="cpp-qt">
int MyContainerExtension::currentIndex() const
{
	return myWidget->currentIndex();
}
</source> 
To fully enable [[Qt:Документация_4.3.2/designer-manual  | Qt Designer]] tomanage and manipulate your custom multi-page widget, you must reimplement allthe functions of the[[Qt:Документация_4.3.2/qdesignercontainerextension  | QDesignerContainerExtension]]class.

<div id="initializingtheextension"></div>
== Initializing the Extension ==
The [[Qt:Документация_4.3.2/designer-manual  | Qt Designer]] extensions are notcreated until they are required, and their creation is controlled by[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s extension manager.For that reason, when implementing an extension, you must also create anextension factory &ndash; a class that is able to make instances of your derivedextension class &ndash; then register it with the extension manager.

An extension factory can be implemented to create one or more types ofextension. Derive your custom extension factory from[[Qt:Документация_4.3.2/qextensionfactory  | QExtensionFactory]] and reimplementits <tt>createExtension()</tt> function in the following way:
<source lang="cpp-qt">
QObject *MyExtFactory::createExtension(QObject *object,
        const QString &amp;iid, QObject *parent) const
{
    MyWidget *widget = qobject_cast<MyWidget*>(object);
    if (!widget)
        return 0;

    if (iid == Q_TYPEID(QDesignerContainerExtension))
        return new MyContainerExtension(widget, parent);
    else if (iid == Q_TYPEID(QDesignerTaskMenuExtension))
        return new MyTaskMenuExtension(widget, parent);

    return 0;
}
</source> 
When an extension is required,[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s extension managerwill look through all its registered factories, calling the<tt>createExtension()</tt> function for each one until it finds one that isable to create the requested extension. For this reason, in the<tt>createExtension()</tt> function, you must check that the[[Qt:Документация_4.3.2/qobject  | QObject]] for which the extension is requiredand the requested extension type correspond to a widget type and extensiontype that your factory supports. Remember that your custom widget must containthe [http://www.crossplatform.ru/documentation/qtdoc4.3/qobject.php#Q_OBJECT Q_OBJECT] macro for this to workcorrectly.

If an extension factory does not support the requested widget, itsimply returns a null pointer, allowing[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s extension managerto continue its search for a suitable factory.

Although the extensions are used in different situations, you canuse the same implementation pattern when creating any extension bysimply replacing the respective extension base class throughout theprocess.

{| align="center"

|- 
|[[Image:qq16-creatingextension.png|center]]
|}
To register your factory, you must access[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s current[[Qt:Документация_4.3.2/qdesignerformeditorinterface  | QDesignerFormEditorInterface]]object, which holds information about all of[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s components. We willtake a closer look at the[[Qt:Документация_4.3.2/qdesignerformeditorinterface  | QDesignerFormEditorInterface]]class shortly, but note that the[http://www.crossplatform.ru/documentation/qtdoc4.3/qdesignercustomwidgetinterface.php#initialize QDesignerCustomWidgetInterface::initialize()]function is supplied with a pointer to the current[[Qt:Документация_4.3.2/qdesignerformeditorinterface  | QDesignerFormEditorInterface]]object.

The plugin's <tt>initialize()</tt> function is the best place to register anextension factory for the custom widget. The interface to the extensionmanager is obtained by using the[http://www.crossplatform.ru/documentation/qtdoc4.3/qdesignerformeditorinterface.php#extensionManager QDesignerFormEditorInterface::extensionManager()]function.

The <tt>initialize()</tt> function will look like this:
<source lang="cpp-qt">
void MyPlugin::initialize(
        QDesignerFormEditorInterface *editor)
{
    if (initialized)
        return;
    QExtensionManager *mgr = editor->extensionManager();
    if (!mgr)
        return;
    mgr->registerExtensions(new MyExtensionFactory(mgr),
                   Q_TYPEID(QDesignerTaskMenuExtension));
    mgr->registerExtensions(new MyExtensionFactory(mgr),
                   Q_TYPEID(QDesignerContainerExtension));
    initialized = true;
}
</source> 
Note that an extension factory must be registered once for each of theextension types that it supports.

<div id="accessingqtdesignerscomponents"></div>
== Accessing Qt Designer's Components ==
The QtDesigner module contains several classes whose purposeis to provide access to[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s components, managers,and workspace. Be aware that these classes are not intended to be instantiateddirectly.

The [[Qt:Документация_4.3.2/qdesignerformeditorinterface  | QDesignerFormEditorInterface]]class provides access to the logic that integrates all of[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s components, managers,and workspace into a coherent application. You can use[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s current[[Qt:Документация_4.3.2/qdesignerformeditorinterface  | QDesignerFormEditorInterface]]object to retrieve interfaces to the various components.

The [[Qt:Документация_4.3.2/qdesigneractioneditorinterface  | QDesignerActionEditorInterface]]and [[Qt:Документация_4.3.2/qdesignerobjectinspectorinterface  | QDesignerObjectInspectorInterface]]classes allow you to change the behavior of[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s action editor andobject inspector. The [[Qt:Документация_4.3.2/qdesignerpropertyeditorinterface  | QDesignerPropertyEditorInterface]]class lets you query and manipulate the current state of the property editor,while the[[Qt:Документация_4.3.2/qdesignerwidgetboxinterface  | QDesignerWidgetBoxInterface]] class enables you to control the contents of the widget box.

In addition, you can use[[Qt:Документация_4.3.2/qdesignerformeditorinterface  | QDesignerFormEditorInterface]]to retrieve interfaces to[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s extension manager([[Qt:Документация 4.3.2//qextensionmanager.php | QExtensionManager]]) and form windowmanager([[Qt:Документация_4.3.2/qdesignerformwindowmanagerinterface  | QDesignerFormWindowManagerInterface]]).The extension manager controls the construction of extensions as they arerequired, while the form window manager controls the form windows in[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s workspace.

Once you have an interface to[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s form window manager([[Qt:Документация_4.3.2/qdesignerformwindowmanagerinterface  | QDesignerFormWindowManagerInterface]]),you can use it to gain access to all the form windows currently residing in[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s workspace: The[[Qt:Документация_4.3.2/qdesignerformwindowinterface  | QDesignerFormWindowInterface]]class allows you to query and manipulate a form window, and it provides aninterface to the form window's cursor. The[[Qt:Документация_4.3.2/qdesignerformwindowcursorinterface  | QDesignerFormWindowCursorInterface]]class is a convenience class allowing you to query and modify a given formwindow's widget selection and, in addition, modify the properties of the form'swidgets.

<div id="summary"></div>
== Summary ==
In this article, we have given an overview of[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s components andextensions framework. Qt 4.1 is supplied with an updated[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]] manual,containing more detailed information about the available components.The [[Qt:Документация_4.3.2/qtdesigner  | QtDesigner]] module is now fullydocumented, and the release contains several new examples. We hope that youwill take the opportunity to build on[[Qt:Документация_4.3.2/designer-manual  | Qt Designer]]'s new foundations.