Container Extension Example

MultiPageWidgetPlugin Class Implementation

The MultiPageWidgetPlugin class implementation is in most parts equivalent to the Custom Widget Plugin example's plugin class:

 MultiPageWidgetPlugin::MultiPageWidgetPlugin(QObject *parent)
     :QObject(parent)
 {
     initialized = false;
 }

 QString MultiPageWidgetPlugin::name() const
 {
     return QLatin1String("MultiPageWidget");
 }

 QString MultiPageWidgetPlugin::group() const
 {
     return QLatin1String("Display Widgets [Examples]");
 }

 QString MultiPageWidgetPlugin::toolTip() const
 {
     return QString();
 }

 QString MultiPageWidgetPlugin::whatsThis() const
 {
     return QString();
 }

 QString MultiPageWidgetPlugin::includeFile() const
 {
     return QLatin1String("multipagewidget.h");
 }

 QIcon MultiPageWidgetPlugin::icon() const
 {
     return QIcon();
 }

 bool MultiPageWidgetPlugin::isInitialized() const
 {
     return initialized;
 }

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.

 bool MultiPageWidgetPlugin::isContainer() const
 {
     return true;
 }

Another function that differ is the function creating our custom widget:

 QWidget *MultiPageWidgetPlugin::createWidget(QWidget *parent)
 {
     MultiPageWidget *widget = new MultiPageWidget(parent);
     connect(widget, SIGNAL(currentIndexChanged(int)),
             this, SLOT(currentIndexChanged(int)));
     connect(widget, SIGNAL(pageTitleChanged(const QString &)),
             this, SLOT(pageTitleChanged(const QString &)));
     return widget;
 }

In addition to create and return the widget, we connect our custom container widget's currentIndexChanged() signal to the plugin's currentIndexChanged() slot to ensure that Qt Designer's property editor is updated whenever the user views another page. We also connect the widget's pageTitleChanged() signal to the plugin's pageTitleChanged() slot.

The currentIndexChanged() slot is called whenever our custom widget's currentIndexChanged() signal is emitted, i.e. whenever the user views another page:

 void MultiPageWidgetPlugin::currentIndexChanged(int index)
 {
     Q_UNUSED(index);
     MultiPageWidget *widget = qobject_cast<MultiPageWidget*>(sender());

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.

     if (widget) {
         QDesignerFormWindowInterface *form = QDesignerFormWindowInterface::findFormWindow(widget);
         if (form)
             form->emitSelectionChanged();
     }
 }

Once we have the widget we can update the property editor. Qt Designer uses the QDesignerPropertySheetExtension class to feed its property editor, and whenever a widget is selected in its workspace, Qt Designer will query for the widget's property sheet extension and update the property editor.

So what we want to achieve is to notify Qt Designer that our widget's internal selection has changed: First we use the static QDesignerFormWindowInterface::findFormWindow() function to retrieve the QDesignerFormWindowInterface object containing the widget. The QDesignerFormWindowInterface class allows you to query and manipulate form windows appearing in Qt Designer's workspace. Then, all we have to do is to emit its emitSelectionChanged() signal, forcing an update of the property editor.

When changing a page title a generic refresh of the property editor is not enough because it is actually the page's property extension that needs to be updated. For that reason we need to access the QDesignerPropertySheetExtension object for the page which title we want to change. The QDesignerPropertySheetExtension class also allows you to manipulate a widget's properties, but to get hold of the extension we must first retrieve access to Qt Designer's extension manager:

 void MultiPageWidgetPlugin::pageTitleChanged(const QString &title)
 {
     Q_UNUSED(title);
     MultiPageWidget *widget = qobject_cast<MultiPageWidget*>(sender());
     if (widget) {
         QWidget *page = widget->widget(widget->currentIndex());
         QDesignerFormWindowInterface *form;
         form = QDesignerFormWindowInterface::findFormWindow(widget);

Again we first retrieve the widget emitting the signal, using the QObject::sender() and qobject_cast() functions. Then we retrieve the current page from the widget that emitted the signal, and we use the static QDesignerFormWindowInterface::findFormWindow() function to retrieve the form containing our widget.

             QDesignerFormEditorInterface *editor = form->core();
             QExtensionManager *manager = editor->extensionManager();

Now that we have the form window, the QDesignerFormWindowInterface class provides the core() function which returns the current QDesignerFormEditorInterface object. The QDesignerFormEditorInterface class allows you to access Qt Designer's various components. In particular, the QDesignerFormEditorInterface::extensionManager() function returns a reference to the current extension manager.

             QDesignerPropertySheetExtension *sheet;
             sheet = qt_extension<QDesignerPropertySheetExtension*>(manager, page);
             const int propertyIndex = sheet->indexOf(QLatin1String("windowTitle"));
             sheet->setChanged(propertyIndex, true);
         }
     }
 }

Once we have the extension manager we can update the extension sheet: First we retrieve the property extension for the page which title we want to change, using the qt_extension() function. Then we retrieve the index for the page title using the QDesignerPropertySheetExtension::indexOf() function. As previously mentioned, we have chosen to use the QWidget::windowTitle property to store the page title (for more information see the MultiPageWidget class implementation). Finally, we implicitly force an update of the page's property sheet by calling the the QDesignerPropertySheetExtension::setChanged() function.

 void MultiPageWidgetPlugin::initialize(QDesignerFormEditorInterface *formEditor)
 {
     if (initialized)
         return;

Note also the initialize() function: The initialize() function takes a QDesignerFormEditorInterface object as argument.

     QExtensionManager *manager = formEditor->extensionManager();

When creating extensions associated with custom widget plugins, we need to access Qt Designer's current extension manager which we retrieve from the QDesignerFormEditorInterface parameter.

In addition to allowing you to manipulate a widget's properties, the QExtensionManager class provides extension management facilities for Qt Designer. Using Qt Designer's current extension manager you can retrieve the extension for a given object. You can also register and unregister an extension for a given object. Remember that an extension is an object which modifies the behavior of Qt Designer.

When registrering an extension, it is actually the associated extension factory that is registered. In Qt Designer, extension factories are used to look up and create named extensions as they are required. So, in this example, the container extension itself is not created until Qt Designer must know whether the associated widget is a container, or not.

     QExtensionFactory *factory = new MultiPageWidgetExtensionFactory(manager);

     Q_ASSERT(manager != 0);
     manager->registerExtensions(factory, Q_TYPEID(QDesignerContainerExtension));

     initialized = true;
 }

We create a MultiPageWidgetExtensionFactory object that we register using Qt Designer's current extension manager retrieved from the QDesignerFormEditorInterface parameter. The first argument is the newly created factory and the second argument is an extension identifier which is a string. The Q_TYPEID() macro simply convert the string into a QLatin1String.

The MultiPageWidgetExtensionFactory class is a subclass of QExtensionFactory. When Qt Designer must know whether a widget is a container, or not, Qt Designer's extension manager will run through all its registered factories invoking the first one which is able to create a container extension for that widget. This factory will in turn create a MultiPageWidgetExtension object.

 QString MultiPageWidgetPlugin::domXml() const
 {
     return QLatin1String("\
 <ui>\
     <widget class=\"MultiPageWidget\" name=\"multipagewidget\">\
         <widget class=\"QWidget\" name=\"page\" />\
     </widget>\
     <customwidgets>\
         <customwidget>\
             <class>MultiPageWidget</class>\
             <extends>QWidget</extends>\
             <addpagemethod>addPage</addpagemethod>\
         </customwidget>\
     </customwidgets>\
 </ui>");
 }

Finally, take a look at the domXml() function. This function includes default settings for the widget in the standard XML format used by Qt Designer. In this case, we specify the container's first page; any inital pages of a multi-page widget must be specified within this function.

 Q_EXPORT_PLUGIN2(containerextension, MultiPageWidgetPlugin)

Remember to use the Q_EXPORT_PLUGIN2() macro to export the MultiPageWidgetPlugin class for use with Qt's plugin handling classes: This macro ensures that Qt Designer can access and construct the custom widget. Without this macro, there is no way for Qt Designer to use the widget.

 class MultiPageWidgetExtensionFactory: public QExtensionFactory
 {
     Q_OBJECT

 public:
     MultiPageWidgetExtensionFactory(QExtensionManager *parent = 0);

 protected:
     QObject *createExtension(QObject *object, const QString &iid, QObject *parent) const;
 };

 MultiPageWidgetExtensionFactory::MultiPageWidgetExtensionFactory(QExtensionManager *parent)
     : QExtensionFactory(parent)
 {}

 QObject *MultiPageWidgetExtensionFactory::createExtension(QObject *object,
                                                           const QString &iid,
                                                           QObject *parent) const
 {
     MultiPageWidget *widget = qobject_cast<MultiPageWidget*>(object);

     if (widget && (iid == Q_TYPEID(QDesignerContainerExtension))) {
         return new MultiPageWidgetContainerExtension(widget, parent);
     } else {
         return 0;
     }
 }

 class MultiPageWidgetContainerExtension: public QObject,
                                          public QDesignerContainerExtension
 {
     Q_OBJECT
     Q_INTERFACES(QDesignerContainerExtension)

 public:
     MultiPageWidgetContainerExtension(MultiPageWidget *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:
     MultiPageWidget *myWidget;
 };

 MultiPageWidgetContainerExtension::MultiPageWidgetContainerExtension(MultiPageWidget *widget,
                                                                      QObject *parent)
     :QObject(parent)
 {
     myWidget = widget;
 }

 void MultiPageWidgetContainerExtension::addWidget(QWidget *widget)
 {
     myWidget->addPage(widget);
 }

 int MultiPageWidgetContainerExtension::count() const
 {
     return myWidget->count();
 }

 int MultiPageWidgetContainerExtension::currentIndex() const
 {
     return myWidget->currentIndex();
 }

 void MultiPageWidgetContainerExtension::insertWidget(int index, QWidget *widget)
 {
     myWidget->insertPage(index, widget);
 }

 void MultiPageWidgetContainerExtension::remove(int index)
 {
     myWidget->removePage(index);
 }

 void MultiPageWidgetContainerExtension::setCurrentIndex(int index)
 {
     myWidget->setCurrentIndex(index);
 }

 QWidget* MultiPageWidgetContainerExtension::widget(int index) const
 {
     return myWidget->widget(index);
 }

 class MultiPageWidget : public QWidget
 {
     Q_OBJECT
     Q_PROPERTY(int currentIndex READ currentIndex WRITE setCurrentIndex)
     Q_PROPERTY(QString pageTitle READ pageTitle WRITE setPageTitle STORED false)

 public:
     MultiPageWidget(QWidget *parent = 0);

     QSize sizeHint() const;

     int count() const;
     int currentIndex() const;
     QWidget *widget(int index);
     QString pageTitle() const;

 public slots:
     void addPage(QWidget *page);
     void insertPage(int index, QWidget *page);
     void removePage(int index);
     void setPageTitle(QString const &newTitle);
     void setCurrentIndex(int index);

 signals:
     void currentIndexChanged(int index);
     void pageTitleChanged(const QString &title);

 private:
     QStackedWidget *stackWidget;
     QComboBox *comboBox;
     QVBoxLayout *layout;
 };