/**************************************************************************** ** ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). ** Contact: Qt Software Information (qt-info@nokia.com) ** ** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:LGPL$ ** Commercial Usage ** Licensees holding valid Qt Commercial licenses may use this file in ** accordance with the Qt Commercial License Agreement provided with the ** Software or, alternatively, in accordance with the terms contained in ** a written agreement between you and Nokia. ** ** GNU Lesser General Public License Usage ** Alternatively, this file may be used under the terms of the GNU Lesser ** General Public License version 2.1 as published by the Free Software ** Foundation and appearing in the file LICENSE.LGPL included in the ** packaging of this file. Please review the following information to ** ensure the GNU Lesser General Public License version 2.1 requirements ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. ** ** In addition, as a special exception, Nokia gives you certain ** additional rights. These rights are described in the Nokia Qt LGPL ** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this ** package. ** ** GNU General Public License Usage ** Alternatively, this file may be used under the terms of the GNU ** General Public License version 3.0 as published by the Free Software ** Foundation and appearing in the file LICENSE.GPL included in the ** packaging of this file. Please review the following information to ** ensure the GNU General Public License version 3.0 requirements will be ** met: http://www.gnu.org/copyleft/gpl.html. ** ** If you are unsure which license is appropriate for your use, please ** contact the sales department at qt-sales@nokia.com. ** $QT_END_LICENSE$ ** ****************************************************************************/ /*! \module QtDesigner \title QtDesigner Module \contentspage Qt's Modules \previouspage Qt3Support \nextpage QtUiTools \ingroup modules \brief The QtDesigner module provides classes that allow you to create your own custom widget plugins for Qt Designer, and classes that enable you to access Qt Designer's components. In addition, the QFormBuilder class provides the possibility of constructing user interfaces from \c .ui files at run-time. To include the definitions of the module's classes, use the following directive: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 0 To link against the module, add this line to your \c qmake .pro file: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 1 \note These classes are part of the \l{Open Source Versions of Qt} and \l{Qt Commercial Editions}{Qt Full Framework Edition} for commercial users. \tableofcontents \section1 Creating Custom Widget Plugins When implementing a custom widget plugin for \QD, you must subclass QDesignerCustomWidgetInterface to expose your custom widget to \QD. A single custom widget plugin is built as a separate library. If you want to include several custom widget plugins in the same library, you must in addition subclass QDesignerCustomWidgetCollectionInterface. To provide your custom widget plugin with the expected behavior and functionality within \QD's workspace you can subclass the associated extension classes: The QDesignerContainerExtension class allows you to add pages to a custom multi-page container. The QDesignerTaskMenuExtension class allows you to add custom menu entries to \QD's task menu. The QDesignerMemberSheetExtension class allows you to manipulate a widget's member functions which is displayed when configuring connections using \QD's mode for editing signals and slots. And finally, the QDesignerPropertySheetExtension class allows you to manipulate a widget's properties which is displayed in \QD's property editor. \image qtdesignerextensions.png In \QD the extensions are not created until they are required. For that reason, when implementing extensions, you must also subclass QExtensionFactory, i.e create a class that is able to make instances of your extensions. In addition, you must make \QD's extension manager register your factory; the extension manager controls the construction of extensions as they are required, and you can access it through QDesignerFormEditorInterface and QExtensionManager. For a complete example creating a custom widget plugin with an extension, see the \l {designer/taskmenuextension}{Task Menu Extension} or \l {designer/containerextension}{Container Extension} examples. \section1 Retrieving Access to \QD Components The purpose of the classes mentioned in this section is to provide access to \QD's components, managers and workspace, and they are not intended to be instantiated directly. \QD is composed by several components. It has an action editor, a property editor, widget box and object inspector which you can view in its workspace. \image qtdesignerscreenshot.png \QD also has an object that works behind the scene; it contains the logic that integrates all of \QD's components into a coherent application. You can access this object, using the QDesignerFormEditorInterface, to retrieve interfaces to \QD's components: \list \o QDesignerActionEditorInterface \o QDesignerObjectInspectorInterface \o QDesignerPropertyEditorInterface \o QDesignerWidgetBoxInterface \endlist In addition, you can use QDesignerFormEditorInterface to retrieve interfaces to \QD's extension manager (QExtensionManager) and form window manager (QDesignerFormWindowManagerInterface). The extension manager controls the construction of extensions as they are required, while the form window manager controls the form windows appearing in \QD's workspace. Once you have an interface to \QD's form window manager (QDesignerFormWindowManagerInterface), you also have access to all the form windows currently appearing in \QD's workspace: The QDesignerFormWindowInterface class allows you to query and manipulate the form windows, and it provides an interface to the form windows' cursors. QDesignerFormWindowCursorInterface is a convenience class allowing you to query and modify a given form window's widget selection, and in addition modify the properties of all the form's widgets. \section1 Creating User Interfaces at Run-Time The \c QtDesigner module contains the QFormBuilder class that provides a mechanism for dynamically creating user interfaces at run-time, based on \c .ui files created with \QD. This class is typically used by custom components and applications that embed \QD. Standalone applications that need to dynamically generate user interfaces at run-time use the QUiLoader class, found in the QtUiTools module. For a complete example using QUiLoader, see the \l {designer/calculatorbuilder}{Calculator Builder example}. \sa {Qt Designer Manual}, {QtUiTools Module} */ /*! \class QDesignerMemberSheetExtension \brief The QDesignerMemberSheetExtension class 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. \inmodule QtDesigner QDesignerMemberSheetExtension is a collection of functions that is typically used to query a widget's member functions, and to manipulate the member functions' appearance in \QD's signals and slots editing mode. For example: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 2 When implementing a custom widget plugin, a pointer to \QD's current QDesignerFormEditorInterface object (\c formEditor in the example above) is provided by the QDesignerCustomWidgetInterface::initialize() function's parameter. The member sheet (and any other extension), can be retrieved by querying \QD's extension manager using the qt_extension() function. When you want to release the extension, you only need to delete the pointer. All widgets have a default member sheet used in \QD's signals and slots editing mode with the widget's member functions. But QDesignerMemberSheetExtension also provides an interface for creating custom member sheet extensions. \warning \QD uses the QDesignerMemberSheetExtension to facilitate the signal and slot editing mode. Whenever a connection between two widgets is requested, \QD will query for the widgets' member sheet extensions. If a widget has an implemented member sheet extension, this extension will override the default member sheet. To create a member sheet extension, your extension class must inherit from both QObject and QDesignerMemberSheetExtension. Then, since we are implementing an interface, we must ensure that it's made known to the meta object system using the Q_INTERFACES() macro: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 3 This enables \QD to use qobject_cast() to query for supported interfaces using nothing but a QObject pointer. In \QD the extensions are not created until they are required. For that reason, when implementing a member sheet extension, you must also create a QExtensionFactory, i.e a class that is able to make an instance of your extension, and register it using \QD's \l {QExtensionManager}{extension manager}. When a widget's member sheet extension is required, \QD's \l {QExtensionManager}{extension manager} will run through all its registered factories calling QExtensionFactory::createExtension() for each until the first one that is able to create a member sheet extension for that widget, is found. This factory will then make an instance of the extension. If no such factory is found, \QD will use the default member sheet. There are four available types of extensions in \QD: QDesignerContainerExtension, QDesignerMemberSheetExtension, QDesignerPropertySheetExtension and QDesignerTaskMenuExtension. \QD's behavior is the same whether the requested extension is associated with a multi page container, a member sheet, a property sheet or a task menu. The QExtensionFactory class provides a standard extension factory, and can also be used as an interface for custom extension factories. You can either create a new QExtensionFactory and reimplement the QExtensionFactory::createExtension() function. For example: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 4 Or you can use an existing factory, expanding the QExtensionFactory::createExtension() function to make the factory able to create a member sheet extension as well. For example: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 5 For a complete example using an extension class, see \l {designer/taskmenuextension}{Task Menu Extension example}. The example shows how to create a custom widget plugin for Qt Designer, and how to to use the QDesignerTaskMenuExtension class to add custom items to \QD's task menu. \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget Extensions} */ /*! \fn QDesignerMemberSheetExtension::~QDesignerMemberSheetExtension() Destroys the member sheet extension. */ /*! \fn int QDesignerMemberSheetExtension::count() const Returns the extension's number of member functions. */ /*! \fn int QDesignerMemberSheetExtension::indexOf(const QString &name) const Returns the index of the member function specified by the given \a name. \sa memberName() */ /*! \fn QString QDesignerMemberSheetExtension::memberName(int index) const Returns the name of the member function with the given \a index. \sa indexOf() */ /*! \fn QString QDesignerMemberSheetExtension::memberGroup(int index) const Returns the name of the member group specified for the function with the given \a index. \sa indexOf(), setMemberGroup() */ /*! \fn void QDesignerMemberSheetExtension::setMemberGroup(int index, const QString &group) Sets the member group of the member function with the given \a index, to \a group. \sa indexOf(), memberGroup() */ /*! \fn bool QDesignerMemberSheetExtension::isVisible(int index) const Returns true if the member function with the given \a index is visible in \QD's signal and slot editor, otherwise false. \sa indexOf(), setVisible() */ /*! \fn void QDesignerMemberSheetExtension::setVisible(int index, bool visible) If \a visible is true, the member function with the given \a index is visible in \QD's signals and slots editing mode; otherwise the member function is hidden. \sa indexOf(), isVisible() */ /*! \fn virtual bool QDesignerMemberSheetExtension::isSignal(int index) const Returns true if the member function with the given \a index is a signal, otherwise false. \sa indexOf() */ /*! \fn bool QDesignerMemberSheetExtension::isSlot(int index) const Returns true if the member function with the given \a index is a slot, otherwise false. \sa indexOf() */ /*! \fn bool QDesignerMemberSheetExtension::inheritedFromWidget(int index) const Returns true if the member function with the given \a index is inherited from QWidget, otherwise false. \sa indexOf() */ /*! \fn QString QDesignerMemberSheetExtension::declaredInClass(int index) const Returns the name of the class in which the member function with the given \a index is declared. \sa indexOf() */ /*! \fn QString QDesignerMemberSheetExtension::signature(int index) const Returns the signature of the member function with the given \a index. \sa indexOf() */ /*! \fn QList QDesignerMemberSheetExtension::parameterTypes(int index) const Returns the parameter types of the member function with the given \a index, as a QByteArray list. \sa indexOf(), parameterNames() */ /*! \fn QList QDesignerMemberSheetExtension::parameterNames(int index) const Returns the parameter names of the member function with the given \a index, as a QByteArray list. \sa indexOf(), parameterTypes() */ // Doc: Interface only /*! \class QDesignerLayoutDecorationExtension \brief The QDesignerLayoutDecorationExtension class provides an extension to a layout in \QD. \inmodule QtDesigner \internal */ /*! \enum QDesignerLayoutDecorationExtension::InsertMode This enum describes the modes that are used to insert items into a layout. \value InsertWidgetMode Widgets are inserted into empty cells in a layout. \value InsertRowMode Whole rows are inserted into a vertical or grid layout. \value InsertColumnMode Whole columns are inserted into a horizontal or grid layout. */ /*! \fn virtual QDesignerLayoutDecorationExtension::~QDesignerLayoutDecorationExtension() Destroys the extension. */ /*! \fn virtual QList QDesignerLayoutDecorationExtension::widgets(QLayout *layout) const Returns the widgets that are managed by the given \a layout. \sa insertWidget(), removeWidget() */ /*! \fn QRect QDesignerLayoutDecorationExtension::itemInfo(int index) const Returns the rectangle covered by the item at the given \a index in the layout. */ /*! \fn int QDesignerLayoutDecorationExtension::indexOf(QWidget *widget) const Returns the index of the specified \a widget in the layout. */ /*! \fn int QDesignerLayoutDecorationExtension::indexOf(QLayoutItem *item) const Returns the index of the specified layout \a item. */ /*! \fn QDesignerLayoutDecorationExtension::InsertMode QDesignerLayoutDecorationExtension::currentInsertMode() const Returns the current insertion mode. */ /*! \fn int QDesignerLayoutDecorationExtension::currentIndex() const Returns the current index in the layout. */ /*! \fn QPair QDesignerLayoutDecorationExtension::currentCell() const Returns a pair containing the row and column of the current cell in the layout. */ /*! \fn void QDesignerLayoutDecorationExtension::insertWidget(QWidget *widget, const QPair &cell) Inserts the given \a widget into the specified \a cell in the layout. \sa removeWidget() */ /*! \fn void QDesignerLayoutDecorationExtension::removeWidget(QWidget *widget) Removes the specified \a widget from the layout. \sa insertWidget() */ /*! \fn void QDesignerLayoutDecorationExtension::insertRow(int row) Inserts a new row into the form at the position specified by \a row. */ /*! \fn void QDesignerLayoutDecorationExtension::insertColumn(int column) Inserts a new column into the form at the position specified by \a column. */ /*! \fn void QDesignerLayoutDecorationExtension::simplify() Simplifies the layout by removing unnecessary empty rows and columns, and by changing the number of rows or columns spanned by widgets. */ /*! \fn int QDesignerLayoutDecorationExtension::findItemAt(const QPoint &position) const Returns the index of the item in the layout that covers the given \a position. */ /*! \fn int QDesignerLayoutDecorationExtension::findItemAt(int row, int column) const Returns the item in the layout that occupies the specified \a row and \a column in the layout. Currently, this only applies to grid layouts. */ /*! \fn void QDesignerLayoutDecorationExtension::adjustIndicator(const QPoint &position, int index) Adjusts the indicator for the item specified by \a index so that it lies at the given \a position on the form. */ // Doc: Interface only /*! \class QDesignerContainerExtension \brief The QDesignerContainerExtension class allows you to add pages to a custom multi-page container in Qt Designer's workspace. \inmodule QtDesigner QDesignerContainerExtension provide an interface for creating custom container extensions. A container extension consists of a collection of functions that \QD needs to manage a multi-page container plugin, and a list of the container's pages. \image containerextension-example.png \warning This is \e not an extension for container plugins in general, only custom \e multi-page containers. To create a container extension, your extension class must inherit from both QObject and QDesignerContainerExtension. For example: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 6 Since we are implementing an interface, we must ensure that it's made known to the meta object system using the Q_INTERFACES() macro. This enables \QD to use the qobject_cast() function to query for supported interfaces using nothing but a QObject pointer. You must reimplement several functions to enable \QD to manage a custom multi-page container widget: \QD uses count() to keep track of the number pages in your container, widget() to return the page at a given index in the list of the container's pages, and currentIndex() to return the list index of the selected page. \QD uses the addWidget() function to add a given page to the container, expecting it to be appended to the list of pages, while it expects the insertWidget() function to add a given page to the container by inserting it at a given index. In \QD the extensions are not created until they are required. For that reason you must also create a QExtensionFactory, i.e a class that is able to make an instance of your extension, and register it using \QD's \l {QExtensionManager}{extension manager}. When a container extension is required, \QD's \l {QExtensionManager}{extension manager} will run through all its registered factories calling QExtensionFactory::createExtension() for each until the first one that is able to create a container extension, is found. This factory will then create the extension for the plugin. There are four available types of extensions in \QD: QDesignerContainerExtension , QDesignerMemberSheetExtension, QDesignerPropertySheetExtension and QDesignerTaskMenuExtension. \QD's behavior is the same whether the requested extension is associated with a multi page container, a member sheet, a property sheet or a task menu. The QExtensionFactory class provides a standard extension factory, and can also be used as an interface for custom extension factories. You can either create a new QExtensionFactory and reimplement the QExtensionFactory::createExtension() function. For example: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 7 Or you can use an existing factory, expanding the QExtensionFactory::createExtension() function to make the factory able to create a container extension as well. For example: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 8 For a complete example using the QDesignerContainerExtension class, see the \l {designer/containerextension}{Container Extension example}. The example shows how to create a custom multi-page plugin for \QD. \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget Extensions} */ /*! \fn QDesignerContainerExtension::~QDesignerContainerExtension() Destroys the extension. */ /*! \fn int QDesignerContainerExtension::count() const Returns the number of pages in the container. */ /*! \fn QWidget *QDesignerContainerExtension::widget(int index) const Returns the page at the given \a index in the extension's list of pages. \sa addWidget(), insertWidget() */ /*! \fn int QDesignerContainerExtension::currentIndex() const Returns the index of the currently selected page in the container. \sa setCurrentIndex() */ /*! \fn void QDesignerContainerExtension::setCurrentIndex(int index) Sets the the currently selected page in the container to be the page at the given \a index in the extension's list of pages. \sa currentIndex() */ /*! \fn void QDesignerContainerExtension::addWidget(QWidget *page) Adds the given \a page to the container by appending it to the extension's list of pages. \sa insertWidget(), remove(), widget() */ /*! \fn void QDesignerContainerExtension::insertWidget(int index, QWidget *page) Adds the given \a page to the container by inserting it at the given \a index in the extension's list of pages. \sa addWidget(), remove(), widget() */ /*! \fn void QDesignerContainerExtension::remove(int index) Removes the page at the given \a index from the extension's list of pages. \sa addWidget(), insertWidget() */ // Doc: Interface only /*! \class QDesignerTaskMenuExtension \brief The QDesignerTaskMenuExtension class allows you to add custom menu entries to Qt Designer's task menu. \inmodule QtDesigner QDesignerTaskMenuExtension provides an interface for creating custom task menu extensions. It is typically used to create task menu entries that are specific to a plugin in \QD. \QD uses the QDesignerTaskMenuExtension to feed its task menu. Whenever a task menu is requested, \QD will query for the selected widget's task menu extension. \image taskmenuextension-example-faded.png A task menu extension is a collection of QActions. The actions appear as entries in the task menu when the plugin with the specified extension is selected. The image above shows the custom \gui {Edit State...} action which appears in addition to \QD's default task menu entries: \gui Cut, \gui Copy, \gui Paste etc. To create a custom task menu extension, your extension class must inherit from both QObject and QDesignerTaskMenuExtension. For example: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 9 Since we are implementing an interface, we must ensure that it is made known to the meta-object system using the Q_INTERFACES() macro. This enables \QD to use the qobject_cast() function to query for supported interfaces using nothing but a QObject pointer. You must reimplement the taskActions() function to return a list of actions that will be included in \QD task menu. Optionally, you can reimplement the preferredEditAction() function to set the action that is invoked when selecting your plugin and pressing \key F2. The preferred edit action must be one of the actions returned by taskActions() and, if it's not defined, pressing the \key F2 key will simply be ignored. In \QD, extensions are not created until they are required. A task menu extension, for example, is created when you click the right mouse button over a widget in \QD's workspace. For that reason you must also construct an extension factory, using either QExtensionFactory or a subclass, and register it using \QD's \l {QExtensionManager}{extension manager}. When a task menu extension is required, \QD's \l {QExtensionManager}{extension manager} will run through all its registered factories calling QExtensionFactory::createExtension() for each until it finds one that is able to create a task menu extension for the selected widget. This factory will then make an instance of the extension. There are four available types of extensions in \QD: QDesignerContainerExtension, QDesignerMemberSheetExtension, QDesignerPropertySheetExtension, and QDesignerTaskMenuExtension. \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. The QExtensionFactory class provides a standard extension factory, and can also be used as an interface for custom extension factories. You can either create a new QExtensionFactory and reimplement the QExtensionFactory::createExtension() function. For example: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 10 Or you can use an existing factory, expanding the QExtensionFactory::createExtension() function to make the factory able to create a task menu extension as well. For example: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 11 For a complete example using the QDesignerTaskMenuExtension class, see the \l {designer/taskmenuextension}{Task Menu Extension example}. The example shows how to create a custom widget plugin for \QD, and how to to use the QDesignerTaskMenuExtension class to add custom items to \QD's task menu. \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget Extensions} */ /*! \fn QDesignerTaskMenuExtension::~QDesignerTaskMenuExtension() Destroys the task menu extension. */ /*! \fn QAction *QDesignerTaskMenuExtension::preferredEditAction() const Returns the action that is invoked when selecting a plugin with the specified extension and pressing \key F2. The action must be one of the actions returned by taskActions(). */ /*! \fn QList QDesignerTaskMenuExtension::taskActions() const Returns the task menu extension as a list of actions which will be included in \QD's task menu when a plugin with the specified extension is selected. The function must be reimplemented to add actions to the list. */ // Doc: Interface only /*! \class QDesignerCustomWidgetCollectionInterface \brief The QDesignerCustomWidgetCollectionInterface class allows you to include several custom widgets in one single library. \inmodule QtDesigner When implementing a custom widget plugin, you build it as a separate library. If you want to include several custom widget plugins in the same library, you must in addition subclass QDesignerCustomWidgetCollectionInterface. QDesignerCustomWidgetCollectionInterface contains one single function returning a list of the collection's QDesignerCustomWidgetInterface objects. For example, if you have several custom widgets \c CustomWidgetOne, \c CustomWidgetTwo and \c CustomWidgetThree, the class definition may look like this: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 12 In the class constructor you add the interfaces to your custom widgets to the list which you return in the customWidgets() function: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 13 Note that instead of exporting each custom widget plugin using the Q_EXPORT_PLUGIN2() macro, you export the entire collection. The Q_EXPORT_PLUGIN2() macro ensures that \QD can access and construct the custom widgets. Without this macro, there is no way for \QD to use them. \sa QDesignerCustomWidgetInterface, {Creating Custom Widgets for Qt Designer} */ /*! \fn QDesignerCustomWidgetCollectionInterface::~QDesignerCustomWidgetCollectionInterface() { Destroys the custom widget collection interface. */ /*! \fn QList QDesignerCustomWidgetCollectionInterface::customWidgets() const Returns a list of interfaces to the collection's custom widgets. */ // Doc: Interface only /*! \class QDesignerCustomWidgetInterface \brief The QDesignerCustomWidgetInterface class enables Qt Designer to access and construct custom widgets. \inmodule QtDesigner QDesignerCustomWidgetInterface provides a custom widget with an interface. The class contains a set of functions that must be subclassed to return basic information about the widget, such as its class name and the name of its header file. Other functions must be implemented to initialize the plugin when it is loaded, and to construct instances of the custom widget for \QD to use. When implementing a custom widget you must subclass QDesignerCustomWidgetInterface to expose your widget to \QD. For example, this is the declaration for the plugin used in the \l{Custom Widget Plugin Example}{Custom Widget Plugin example} that enables an analog clock custom widget to be used by \QD: \snippet examples/designer/customwidgetplugin/customwidgetplugin.h 0 Note that the only part of the class definition that is specific to this particular custom widget is the class name. In addition, since we are implementing an interface, we must ensure that it's made known to the meta object system using the Q_INTERFACES() macro. This enables \QD to use the qobject_cast() function to query for supported interfaces using nothing but a QObject pointer. After \QD loads a custom widget plugin, it calls the interface's initialize() function to enable it to set up any resources that it may need. This function is called with a QDesignerFormEditorInterface parameter that provides the plugin with a gateway to all of \QD's API. \QD constructs instances of the custom widget by calling the plugin's createWidget() function with a suitable parent widget. Plugins must construct and return an instance of a custom widget with the specified parent widget. In the implementation of the class you must remember to export your custom widget plugin to \QD using the Q_EXPORT_PLUGIN2() macro. For example, if a library called \c libcustomwidgetplugin.so (on Unix) or \c libcustomwidget.dll (on Windows) contains a widget class called \c MyCustomWidget, we can export it by adding the following line to the file containing the plugin implementation: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 14 This macro ensures that \QD can access and construct the custom widget. Without this macro, there is no way for \QD to use it. When implementing a custom widget plugin, you build it as a separate library. If you want to include several custom widget plugins in the same library, you must in addition subclass QDesignerCustomWidgetCollectionInterface. \warning If your custom widget plugin contains QVariant properties, be aware that only the following \l {QVariant::Type}{types} are supported: \list \o QVariant::ByteArray \o QVariant::Bool \o QVariant::Color \o QVariant::Cursor \o QVariant::Date \o QVariant::DateTime \o QVariant::Double \o QVariant::Int \o QVariant::Point \o QVariant::Rect \o QVariant::Size \o QVariant::SizePolicy \o QVariant::String \o QVariant::Time \o QVariant::UInt \endlist For a complete example using the QDesignerCustomWidgetInterface class, see the \l {designer/customwidgetplugin}{Custom Widget Example}. The example shows how to create a custom widget plugin for \QD. \sa QDesignerCustomWidgetCollectionInterface {Creating Custom Widgets for Qt Designer} */ /*! \fn QDesignerCustomWidgetInterface::~QDesignerCustomWidgetInterface() Destroys the custom widget interface. */ /*! \fn QString QDesignerCustomWidgetInterface::name() const Returns the class name of the custom widget supplied by the interface. The name returned \e must be identical to the class name used for the custom widget. */ /*! \fn QString QDesignerCustomWidgetInterface::group() const Returns the name of the group to which the custom widget belongs. */ /*! \fn QString QDesignerCustomWidgetInterface::toolTip() const Returns a short description of the widget that can be used by \QD in a tool tip. */ /*! \fn QString QDesignerCustomWidgetInterface::whatsThis() const Returns a description of the widget that can be used by \QD in "What's This?" help for the widget. */ /*! \fn QString QDesignerCustomWidgetInterface::includeFile() const Returns the path to the include file that \l uic uses when creating code for the custom widget. */ /*! \fn QIcon QDesignerCustomWidgetInterface::icon() const Returns the icon used to represent the custom widget in \QD's widget box. */ /*! \fn bool QDesignerCustomWidgetInterface::isContainer() const Returns true if the custom widget is intended to be used as a container; otherwise returns false. Most custom widgets are not used to hold other widgets, so their implementations of this function will return false, but custom containers will return true to ensure that they behave correctly in \QD. */ /*! \fn QWidget *QDesignerCustomWidgetInterface::createWidget(QWidget *parent) Returns a new instance of the custom widget, with the given \a parent. */ /*! \fn bool QDesignerCustomWidgetInterface::isInitialized() const Returns true if the widget has been initialized; otherwise returns false. \sa initialize() */ /*! \fn void QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface *formEditor) Initializes the widget for use with the specified \a formEditor interface. \sa isInitialized() */ /*! \fn QString QDesignerCustomWidgetInterface::domXml() const Returns the XML that is used to describe the custom widget's properties to \QD. */ /*! \fn QString QDesignerCustomWidgetInterface::codeTemplate() const This function is reserved for future use by \QD. \omit Returns the code template that \QD includes in forms that contain the custom widget when they are saved. \endomit */ /*! \macro QDESIGNER_WIDGET_EXPORT \relates QDesignerCustomWidgetInterface \since 4.1 This macro is used when defining custom widgets to ensure that they are correctly exported from plugins for use with \QD. On some platforms, the symbols required by \QD to create new widgets are removed from plugins by the build system, making them unusable. Using this macro ensures that the symbols are retained on those platforms, and has no side effects on other platforms. For example, the \l{designer/worldtimeclockplugin}{World Time Clock Plugin} example exports a custom widget class with the following declaration: \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 0 \dots \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 2 \sa {Creating Custom Widgets for Qt Designer} */ // Doc: Abstract class /*! \class QDesignerDnDItemInterface \brief The QDesignerDnDItemInterface class provides an interface that is used to manage items during a drag and drop operation. \inmodule QtDesigner \internal */ /*! \enum QDesignerDnDItemInterface::DropType This enum describes the result of a drag and drop operation. \value MoveDrop The item was moved. \value CopyDrop The item was copied. */ /*! \fn QDesignerDnDItemInterface::QDesignerDnDItemInterface() Constructs a new interface to a drag and drop item. */ /*! \fn QDesignerDnDItemInterface::~QDesignerDnDItemInterface() Destroys the interface to the item. */ /*! \fn DomUI *QDesignerDnDItemInterface::domUi() const Returns a user interface object for the item. */ /*! \fn QWidget *QDesignerDnDItemInterface::widget() const Returns the widget being copied or moved in the drag and drop operation. \sa source() */ /*! \fn QWidget *QDesignerDnDItemInterface::decoration() const Returns the widget used to represent the item. */ /*! \fn QPoint QDesignerDnDItemInterface::hotSpot() const Returns the cursor's hotspot. \sa QDrag::hotSpot() */ /*! \fn DropType QDesignerDnDItemInterface::type() const Returns the type of drag and drop operation in progress. */ /*! \fn QWidget *QDesignerDnDItemInterface::source() const Returns the widget that is the source of the drag and drop operation; i.e. the original container of the widget being dragged. \sa widget() */ // Doc: Abstract class /*! \class QDesignerIconCacheInterface \brief The QDesignerIconCacheInterface class provides an interface to \QD's icon cache. \inmodule QtDesigner \internal */ /*! \fn QDesignerIconCacheInterface::QDesignerIconCacheInterface(QObject *parent) Constructs a new interface with the given \a parent. */ /*! \fn QIcon QDesignerIconCacheInterface::nameToIcon(const QString &filePath, const QString &qrcPath) Returns the icon associated with the name specified by \a filePath in the resource file specified by \a qrcPath. If \a qrcPath refers to a valid resource file, the name used for the file path is a path within those resources; otherwise the file path refers to a local file. \sa {The Qt Resource System}, nameToPixmap() */ /*! \fn QPixmap QDesignerIconCacheInterface::nameToPixmap(const QString &filePath, const QString &qrcPath) Returns the pixmap associated with the name specified by \a filePath in the resource file specified by \a qrcPath. If \a qrcPath refers to a valid resource file, the name used for the file path is a path within those resources; otherwise the file path refers to a local file. \sa {The Qt Resource System}, nameToIcon() */ /*! \fn QString QDesignerIconCacheInterface::iconToFilePath(const QIcon &icon) const Returns the file path associated with the given \a icon. The file path is a path within an application resources. */ /*! \fn QString QDesignerIconCacheInterface::iconToQrcPath(const QIcon &icon) const Returns the path to the resource file that refers to the specified \a icon. The resource path refers to a local file. */ /*! \fn QString QDesignerIconCacheInterface::pixmapToFilePath(const QPixmap &pixmap) const Returns the file path associated with the given \a pixmap. The file path is a path within an application resources. */ /*! \fn QString QDesignerIconCacheInterface::pixmapToQrcPath(const QPixmap &pixmap) const Returns the path to the resource file that refers to the specified \a pixmap. The resource path refers to a local file. */ /*! \fn QList QDesignerIconCacheInterface::pixmapList() const Returns a list of pixmaps for the icons provided by the icon cache. */ /*! \fn QList QDesignerIconCacheInterface::iconList() const Returns a list of icons provided by the icon cache. */ /*! \fn QString QDesignerIconCacheInterface::resolveQrcPath(const QString &filePath, const QString &qrcPath, const QString &workingDirectory) const Returns a path to a resource specified by the \a filePath within the resource file located at \a qrcPath. If \a workingDirectory is a valid path to a directory, the path returned will be relative to that directory; otherwise an absolute path is returned. \omit ### Needs checking \endomit */ // Doc: Interface only /*! \class QDesignerPropertySheetExtension \brief The QDesignerPropertySheetExtension class allows you to manipulate a widget's properties which is displayed in Qt Designer's property editor. \sa QDesignerDynamicPropertySheetExtension \inmodule QtDesigner QDesignerPropertySheetExtension provides a collection of functions that are typically used to query a widget's properties, and to manipulate the properties' appearance in the property editor. For example: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 15 Note that if you change the value of a property using the QDesignerPropertySheetExtension::setProperty() function, the undo stack is not updated. To ensure that a property's value can be reverted using the undo stack, you must use the QDesignerFormWindowCursorInterface::setProperty() function, or its buddy \l {QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()}, instead. When implementing a custom widget plugin, a pointer to \QD's current QDesignerFormEditorInterface object (\c formEditor in the example above) is provided by the QDesignerCustomWidgetInterface::initialize() function's parameter. The property sheet, or any other extension, can be retrieved by querying \QD's extension manager using the qt_extension() function. When you want to release the extension, you only need to delete the pointer. All widgets have a default property sheet which populates \QD's property editor with the widget's properties (i.e the ones defined with the Q_PROPERTY() macro). But QDesignerPropertySheetExtension also provides an interface for creating custom property sheet extensions. \warning \QD uses the QDesignerPropertySheetExtension to feed its property editor. Whenever a widget is selected in its workspace, \QD will query for the widget's property sheet extension. If the selected widget has an implemented property sheet extension, this extension will override the default property sheet. To create a property sheet extension, your extension class must inherit from both QObject and QDesignerPropertySheetExtension. Then, since we are implementing an interface, we must ensure that it's made known to the meta object system using the Q_INTERFACES() macro: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 16 This enables \QD to use qobject_cast() to query for supported interfaces using nothing but a QObject pointer. In \QD the extensions are not created until they are required. For that reason, when implementing a property sheet extension, you must also create a QExtensionFactory, i.e a class that is able to make an instance of your extension, and register it using \QD's \l {QExtensionManager}{extension manager}. When a property sheet extension is required, \QD's \l {QExtensionManager}{extension manager} will run through all its registered factories calling QExtensionFactory::createExtension() for each until the first one that is able to create a property sheet extension for the selected widget, is found. This factory will then make an instance of the extension. If no such factory can be found, \QD will use the default property sheet. There are four available types of extensions in \QD: QDesignerContainerExtension, QDesignerMemberSheetExtension, QDesignerPropertySheetExtension and QDesignerTaskMenuExtension. Qt Designer's behavior is the same whether the requested extension is associated with a multi page container, a member sheet, a property sheet or a task menu. The QExtensionFactory class provides a standard extension factory, and can also be used as an interface for custom extension factories. You can either create a new QExtensionFactory and reimplement the QExtensionFactory::createExtension() function. For example: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 17 Or you can use an existing factory, expanding the QExtensionFactory::createExtension() function to make the factory able to create a property sheet extension extension as well. For example: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 18 For a complete example using an extension class, see the \l {designer/taskmenuextension}{Task Menu Extension example}. The example shows how to create a custom widget plugin for Qt Designer, and how to to use the QDesignerTaskMenuExtension class to add custom items to \QD's task menu. \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget Extensions} */ /*! \fn QDesignerPropertySheetExtension::~QDesignerPropertySheetExtension() Destroys the property sheet extension. */ /*! \fn int QDesignerPropertySheetExtension::count() const Returns the selected widget's number of properties. */ /*! \fn int QDesignerPropertySheetExtension::indexOf(const QString &name) const Returns the index for a given property \a name. \sa propertyName() */ /*! \fn QString QDesignerPropertySheetExtension::propertyName(int index) const Returns the name of the property at the given \a index. \sa indexOf() */ /*! \fn QString QDesignerPropertySheetExtension::propertyGroup(int index) const Returns the property group for the property at the given \a index. \QD's property editor supports property groups, i.e. sections of related properties. A property can be related to a group using the setPropertyGroup() function. The default group of any property is the name of the class that defines it. For example, the QObject::objectName property appears within the QObject property group. \sa indexOf(), setPropertyGroup() */ /*! \fn void QDesignerPropertySheetExtension::setPropertyGroup(int index, const QString &group) Sets the property group for the property at the given \a index to \a group. Relating a property to a group makes it appear within that group's section in the property editor. The default property group of any property is the name of the class that defines it. For example, the QObject::objectName property appears within the QObject property group. \sa indexOf(), property(), propertyGroup() */ /*! \fn bool QDesignerPropertySheetExtension::hasReset(int index) const Returns true if the property at the given \a index has a reset button in \QD's property editor, otherwise false. \sa indexOf(), reset() */ /*! \fn bool QDesignerPropertySheetExtension::reset(int index) Resets the value of the property at the given \a index, to the default value. Returns true if a default value could be found, otherwise false. \sa indexOf(), hasReset(), isChanged() */ /*! \fn bool QDesignerPropertySheetExtension::isVisible(int index) const Returns true if the property at the given \a index is visible in \QD's property editor, otherwise false. \sa indexOf(), setVisible() */ /*! \fn void QDesignerPropertySheetExtension::setVisible(int index, bool visible) If \a visible is true, the property at the given \a index is visible in \QD's property editor; otherwise the property is hidden. \sa indexOf(), isVisible() */ /*! \fn bool QDesignerPropertySheetExtension::isAttribute(int index) const Returns true if the property at the given \a index is an attribute, which will be \e excluded from the .ui file, otherwise false. \sa indexOf(), setAttribute() */ /*! \fn void QDesignerPropertySheetExtension::setAttribute(int index, bool attribute) If \a attribute is true, the property at the given \a index is made an attribute which will be \e excluded from the .ui file; otherwise it will be included. \sa indexOf(), isAttribute() */ /*! \fn QVariant QDesignerPropertySheetExtension::property(int index) const Returns the value of the property at the given \a index. \sa indexOf(), setProperty(), propertyGroup() */ /*! \fn void QDesignerPropertySheetExtension::setProperty(int index, const QVariant &value) Sets the \a value of the property at the given \a index. \warning If you change the value of a property using this function, the undo stack is not updated. To ensure that a property's value can be reverted using the undo stack, you must use the QDesignerFormWindowCursorInterface::setProperty() function, or its buddy \l {QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()}, instead. \sa indexOf(), property(), propertyGroup() */ /*! \fn bool QDesignerPropertySheetExtension::isChanged(int index) const Returns true if the value of the property at the given \a index differs from the property's default value, otherwise false. \sa indexOf(), setChanged(), reset() */ /*! \fn void QDesignerPropertySheetExtension::setChanged(int index, bool changed) Sets whether the property at the given \a index is different from its default value, or not, depending on the \a changed parameter. \sa indexOf(), isChanged() */ // Doc: Interface only /*! \class QDesignerDynamicPropertySheetExtension \brief The QDesignerDynamicPropertySheetExtension class allows you to manipulate a widget's dynamic properties in Qt Designer's property editor. \sa QDesignerPropertySheetExtension, {QObject#Dynamic Properties}{Dynamic Properties} \inmodule QtDesigner \since 4.3 */ /*! \fn QDesignerDynamicPropertySheetExtension::~QDesignerDynamicPropertySheetExtension() Destroys the dynamic property sheet extension. */ /*! \fn bool QDesignerDynamicPropertySheetExtension::dynamicPropertiesAllowed() const Returns true if the widget supports dynamic properties; otherwise returns false. */ /*! \fn int QDesignerDynamicPropertySheetExtension::addDynamicProperty(const QString &propertyName, const QVariant &value) Adds a dynamic property named \a propertyName and sets its value to \a value. Returns the index of the property if it was added successfully; otherwise returns -1 to indicate failure. */ /*! \fn bool QDesignerDynamicPropertySheetExtension::removeDynamicProperty(int index) Removes the dynamic property at the given \a index. Returns true if the operation succeeds; otherwise returns false. */ /*! \fn bool QDesignerDynamicPropertySheetExtension::isDynamicProperty(int index) const Returns true if the property at the given \a index is a dynamic property; otherwise returns false. */ /*! \fn bool QDesignerDynamicPropertySheetExtension::canAddDynamicProperty(const QString &propertyName) const Returns true if \a propertyName is a valid, unique name for a dynamic property; otherwise returns false. */