1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \class QDesignerContainerExtension

    44     \brief The QDesignerContainerExtension class allows you to add pages to

    45     a custom multi-page container in Qt Designer's workspace.

    46     \inmodule QtDesigner

    47 

    48     QDesignerContainerExtension provide an interface for creating

    49     custom container extensions. A container extension consists of a

    50     collection of functions that \QD needs to manage a multi-page

    51     container plugin, and a list of the container's pages.

    52 

    53     \image containerextension-example.png

    54 

    55     \warning This is \e not an extension for container plugins in

    56     general, only custom \e multi-page containers.

    57 

    58     To create a container extension, your extension class must inherit

    59     from both QObject and QDesignerContainerExtension. For example:

    60 

    61     \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 6

    62 

    63     Since we are implementing an interface, we must ensure that it's

    64     made known to the meta object system using the Q_INTERFACES()

    65     macro. This enables \QD to use the qobject_cast() function to

    66     query for supported interfaces using nothing but a QObject

    67     pointer.

    68 

    69     You must reimplement several functions to enable \QD to manage a

    70     custom multi-page container widget: \QD uses count() to keep track

    71     of the number pages in your container, widget() to return the page

    72     at a given index in the list of the container's pages, and

    73     currentIndex() to return the list index of the selected page. \QD

    74     uses the addWidget() function to add a given page to the

    75     container, expecting it to be appended to the list of pages, while

    76     it expects the insertWidget() function to add a given page to the

    77     container by inserting it at a given index.

    78 

    79     In \QD the extensions are not created until they are

    80     required. For that reason you must also create a

    81     QExtensionFactory, i.e a class that is able to make an instance of

    82     your extension, and register it using \QD's \l

    83     {QExtensionManager}{extension manager}.

    84 

    85     When a container extension is required, \QD's \l

    86     {QExtensionManager}{extension manager} will run through all its

    87     registered factories calling QExtensionFactory::createExtension()

    88     for each until the first one that is able to create a container

    89     extension, is found. This factory will then create the extension

    90     for the plugin.

    91 

    92     There are four available types of extensions in \QD:

    93     QDesignerContainerExtension , QDesignerMemberSheetExtension,

    94     QDesignerPropertySheetExtension and QDesignerTaskMenuExtension.

    95     \QD's behavior is the same whether the requested extension is

    96     associated with a multi page container, a member sheet, a property

    97     sheet or a task menu.

    98 

    99     The QExtensionFactory class provides a standard extension factory,

   100     and can also be used as an interface for custom extension

   101     factories. You can either create a new QExtensionFactory and

   102     reimplement the QExtensionFactory::createExtension() function. For

   103     example:

   104 

   105     \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 7

   106 

   107     Or you can use an existing factory, expanding the

   108     QExtensionFactory::createExtension() function to make the factory

   109     able to create a container extension as well. For example:

   110 

   111     \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 8

   112 

   113     For a complete example using the QDesignerContainerExtension

   114     class, see the \l {designer/containerextension}{Container

   115     Extension example}. The example shows how to create a custom

   116     multi-page plugin for \QD.

   117 

   118     \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget

   119     Extensions}

   120 */

   121 

   122 /*!

   123     \fn QDesignerContainerExtension::~QDesignerContainerExtension()

   124 

   125     Destroys the extension.

   126 */

   127 

   128 /*!

   129     \fn int QDesignerContainerExtension::count() const

   130 

   131     Returns the number of pages in the container.

   132 */

   133 

   134 /*!

   135     \fn QWidget *QDesignerContainerExtension::widget(int index) const

   136 

   137     Returns the page at the given \a index in the extension's list of

   138     pages.

   139 

   140     \sa addWidget(), insertWidget()

   141 */

   142 

   143 /*!

   144     \fn int QDesignerContainerExtension::currentIndex() const

   145 

   146     Returns the index of the currently selected page in the

   147     container.

   148 

   149     \sa setCurrentIndex()

   150 */

   151 

   152 /*!

   153     \fn void QDesignerContainerExtension::setCurrentIndex(int index)

   154 

   155     Sets the currently selected page in the container to be the

   156     page at the given \a index in the extension's list of pages.

   157 

   158     \sa currentIndex()

   159 */

   160 

   161 /*!

   162     \fn void QDesignerContainerExtension::addWidget(QWidget *page)

   163 

   164     Adds the given \a page to the container by appending it to the

   165     extension's list of pages.

   166 

   167     \sa insertWidget(), remove(), widget()

   168 */

   169 

   170 /*!

   171     \fn void QDesignerContainerExtension::insertWidget(int index, QWidget *page)

   172 

   173     Adds the given \a page to the container by inserting it at the

   174     given \a index in the extension's list of pages.

   175 

   176     \sa addWidget(), remove(), widget()

   177 */

   178 

   179 /*!

   180     \fn void QDesignerContainerExtension::remove(int index)

   181 

   182     Removes the page at the given \a index from the extension's list

   183     of pages.

   184 

   185     \sa addWidget(), insertWidget()

   186 */