QWidgetContainerPlugin(3qt)

NAME
QWidgetContainerPlugin - Abstract base for complex custom container QWidget plugins

SYNOPSIS
#include <qwidgetplugin.h>

Inherits QWidgetPlugin.

  Public Members
QWidgetContainerPlugin ()
~QWidgetContainerPlugin ()
virtual QWidget * containerOfWidget ( const QString & key, QWidget * container ) const
virtual bool isPassiveInteractor ( const QString & key, QWidget * container ) const
virtual bool supportsPages ( const QString & key ) const
virtual QWidget * addPage ( const QString & key, QWidget * container, const QString & name, int index ) const
virtual void insertPage ( const QString & key, QWidget * container, const QString & name, int index, QWidget * page ) const
virtual void removePage ( const QString & key, QWidget * container, int index ) const
virtual void movePage ( const QString & key, QWidget * container, int fromIndex, int toIndex ) const
virtual int count ( const QString & key, QWidget * container ) const
virtual int currentIndex ( const QString & key, QWidget * container ) const
virtual QString pageLabel ( const QString & key, QWidget * container, int index ) const
virtual QWidget * page ( const QString & key, QWidget * container, int index ) const
virtual void renamePage ( const QString & key, QWidget * container, int index, const QString & newName ) const
virtual QWidgetList pages ( const QString & key, QWidget * container ) const
virtual QString createCode ( const QString & key, const QString & container, const QString & page, const QString & pageName ) const

DESCRIPTION
The QWidgetContainerPlugin class provides an abstract base for complex custom container QWidget plugins.

The widget container plugin is a subclass of QWidgetPlugin and extends the interface with functions necessary for supporting complex container widgets via plugins. These container widgets are widgets that have one or multiple sub widgets which act as the widget's containers. If the widget has multiple container subwidgets, they are referred to as "pages", and only one can be active at a time. Examples of complex container widgets include: QTabWidget, QWidgetStack and QToolBox.

Writing a complex container widget plugin is achieved by subclassing this base class. First by reimplementing QWidgetPlugin's pure virtual functions keys(), create(), group(), iconSet(), includeFile(), toolTip(), whatsThis() and isContainer(), and exporting the class with the Q_EXPORT_PLUGIN macro. In addition containerOfWidget(), isPassiveInteractor() and supportsPages() must be reimplemented. If the widget supportsPages(), count(), currentIndex(), pageLabel(), page(), pages() and createCode() must be implemented. If the widget supportsPages() and you want to allow the containers pages to be modified, you must also reimplement addPage(), insertPage(), removePage(), movePage() and renamePage().

See also QWidgetPlugin and Plugins.

MEMBER FUNCTION DOCUMENTATION

QWidgetContainerPlugin::QWidgetContainerPlugin ()
Constructs a complex container widget plugin. This is invoked automatically by the Q_EXPORT_PLUGIN macro.

QWidgetContainerPlugin::~QWidgetContainerPlugin ()
Destroys the complex container widget plugin.

You never have to call this explicitly. Qt destroys a plugin automatically when it is no longer used.

QWidget * QWidgetContainerPlugin::addPage ( const QString & key, QWidget * container, const QString & name, int index ) const [virtual]
Operates on the plugin's key class.

This function is called when a new page with the given name should be added to the container custom widget at position index.

The default implementation does nothing.

QWidget * QWidgetContainerPlugin::containerOfWidget ( const QString & key, QWidget * container ) const [virtual]
Operates on the plugin's key class.

Returns the current container's custom widget. If the custom widget is a tab widget, this function takes the container as input and returns the widget's current page.

The default implementation returns container.

int QWidgetContainerPlugin::count ( const QString & key, QWidget * container ) const [virtual]
Operates on the plugin's key class.

Returns the container custom widget's number of pages. If the custom widget is a tab widget, this function returns the number of tabs.

The default implementation returns 0.

QString QWidgetContainerPlugin::createCode ( const QString & key, const QString & container, const QString & page, const QString & pageName ) const [virtual]
Operates on the plugin's key class.

This function is called from Qt Designer's User Interface Compiler uic, when generating C++ code for inserting a page in the container custom widget. The name of the page widget which should be inserted at the end of the container is page, and the label of the page should be pageName.

If the custom widget was a QTabWidget, the implementation of this function should return:

    return widget + "->addTab( " + page + ", \"" + pageName + "\" )";

Warning: If the code returned by this function contains invalid C++ syntax, the generated uic code will not compile.

int QWidgetContainerPlugin::currentIndex ( const QString & key, QWidget * container ) const [virtual]
Operates on the plugin's key class.

Returns the container custom widget's current page index. If the custom widget is a tab widget, this function returns the current tab's index.

The default implementation returns -1.

void QWidgetContainerPlugin::insertPage ( const QString & key, QWidget * container, const QString & name, int index, QWidget * page ) const [virtual]
Operates on the plugin's key class.

This function is called when a new page, page, with the given name should be added to the container custom widget at position index.

The default implementation does nothing.

bool QWidgetContainerPlugin::isPassiveInteractor ( const QString & key, QWidget * container ) const [virtual]
Operates on the plugin's key class.

Returns TRUE if the container custom widget is a passive interactor for class key; otherwise returns FALSE. The container is a child widget of the actual custom widget.

Usually, when a custom widget is used in Qt Designer's design mode, no widget receives any mouse or key events, since Qt Designer filters and processes them itself. If one or more widgets of a custom widget still need to receive such events, for example, because the widget needs to change pages, this function must return TRUE for the widget. In such cases Qt Designer will not filter out key and mouse events destined for the widget.

If the custom widget is a tab widget, the tab bar is the passive interactor, since that's what the user will use to change pages.

The default implementation returns FALSE.

void QWidgetContainerPlugin::movePage ( const QString & key, QWidget * container, int fromIndex, int toIndex ) const [virtual]
Operates on the plugin's key class.

This function is called when the page at position fromIndex should be moved to position toIndex in the container custom widget.

The default implementation does nothing.

QWidget * QWidgetContainerPlugin::page ( const QString & key, QWidget * container, int index ) const [virtual]
Operates on the plugin's key class.

Returns the container custom widget's page at position index. If the custom widget is a tab widget, this function returns the tab at index position index.

The default implementation returns 0.

QString QWidgetContainerPlugin::pageLabel ( const QString & key, QWidget * container, int index ) const [virtual]
Operates on the plugin's key class.

Returns the container custom widget's label at position index. If the custom widget is a tab widget, this function returns the current tab's label.

The default implementation returns a null string.

QWidgetList QWidgetContainerPlugin::pages ( const QString & key, QWidget * container ) const [virtual]
Operates on the plugin's key class.

This function should return a list of the container custom widget's pages.

void QWidgetContainerPlugin::removePage ( const QString & key, QWidget * container, int index ) const [virtual]
Operates on the plugin's key class.

This function is called when the page at position index should be removed from the container custom widget.

The default implementation does nothing.

void QWidgetContainerPlugin::renamePage ( const QString & key, QWidget * container, int index, const QString & newName ) const [virtual]
Operates on the plugin's key class.

This function is called when the page at position index should be renamed (have its label changed) to newName in the container custom widget.

The default implementation does nothing.

bool QWidgetContainerPlugin::supportsPages ( const QString & key ) const [virtual]
Operates on the plugin's key class.

Returns TRUE if the widget supports pages; otherwise returns FALSE. If the custom widget is a tab widget this function should return TRUE.

The default implementation returns FALSE.

SEE ALSO
http://doc.trolltech.com/qwidgetcontainerplugin.html http://www.trolltech.com/faq/tech.html

COPYRIGHT
Copyright 1992-2001 Trolltech AS, http://www.trolltech.com. See the license file included in the distribution for a complete license statement.

AUTHOR
Generated automatically from the source code.

BUGS
If you find a bug in Qt, please report it as described in http://doc.trolltech.com/bughowto.html. Good bug reports help us to help you. Thank you.

The definitive Qt documentation is provided in HTML format; it is located at $QTDIR/doc/html and can be read using Qt Assistant or with a web browser. This man page is provided as a convenience for those users who prefer man pages, although this format is not officially supported by Trolltech.

If you find errors in this manual page, please report them to qt-bugs@trolltech.com. Please include the name of the manual page (qwidgetcontainerplugin.3qt) and the Qt version (3.2.0b1).