source: trunk/tools/designer/src/lib/uilib/container.qdoc@ 846

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** 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 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 [email protected].
** $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.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 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()
*/