qt5base-lts/tools/uilib/container.qdoc

173 lines
6.0 KiB
Plaintext
Raw Normal View History

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\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.cpp 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.cpp 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.cpp 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 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()
*/