1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the Qt Designer of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:GPL-EXCEPT$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU
19** General Public License version 3 as published by the Free Software
20** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT
21** included in the packaging of this file. Please review the following
22** information to ensure the GNU General Public License requirements will
23** be met: https://www.gnu.org/licenses/gpl-3.0.html.
24**
25** $QT_END_LICENSE$
26**
27****************************************************************************/
28
29#include <QtDesigner/extension.h>
30
31QT_BEGIN_NAMESPACE
32
33/*!
34 \class QAbstractExtensionFactory
35
36 \brief The QAbstractExtensionFactory class provides an interface
37 for extension factories in Qt Designer.
38
39 \inmodule QtDesigner
40
41 QAbstractExtensionFactory is not intended to be instantiated
42 directly; use the QExtensionFactory instead.
43
44 In \QD, extension factories are used to look up and create named
45 extensions as they are required. For that reason, when
46 implementing a custom extension, you must also create a
47 QExtensionFactory, i.e a class that is able to make an instance of
48 your extension, and register it using \QD's \l
49 {QExtensionManager}{extension manager}.
50
51 When an extension is required, \QD's \l
52 {QExtensionManager}{extension manager} will run through all its
53 registered factories calling QExtensionFactory::createExtension()
54 for each until the first one that is able to create the requested
55 extension for the selected object, is found. This factory will
56 then make an instance of the extension.
57
58 \sa QExtensionFactory, QExtensionManager
59*/
60
61/*!
62 \fn QAbstractExtensionFactory::~QAbstractExtensionFactory()
63
64 Destroys the extension factory.
65*/
66
67/*!
68 \fn QObject *QAbstractExtensionFactory::extension(QObject *object, const QString &iid) const
69
70 Returns the extension specified by \a iid for the given \a object.
71*/
72
73
74/*!
75 \class QAbstractExtensionManager
76
77 \brief The QAbstractExtensionManager class provides an interface
78 for extension managers in Qt Designer.
79
80 \inmodule QtDesigner
81
82 QAbstractExtensionManager is not intended to be instantiated
83 directly; use the QExtensionManager instead.
84
85 In \QD, extension are not created until they are required. For
86 that reason, when implementing a custom extension, you must also
87 create a QExtensionFactory, i.e a class that is able to make an
88 instance of your extension, and register it using \QD's \l
89 {QExtensionManager}{extension manager}.
90
91 When an extension is required, \QD's \l
92 {QExtensionManager}{extension manager} will run through all its
93 registered factories calling QExtensionFactory::createExtension()
94 for each until the first one that is able to create the requested
95 extension for the selected object, is found. This factory will
96 then make an instance of the extension.
97
98 \sa QExtensionManager, QExtensionFactory
99*/
100
101/*!
102 \fn QAbstractExtensionManager::~QAbstractExtensionManager()
103
104 Destroys the extension manager.
105*/
106
107/*!
108 \fn void QAbstractExtensionManager::registerExtensions(QAbstractExtensionFactory *factory, const QString &iid)
109
110 Register the given extension \a factory with the extension
111 specified by \a iid.
112*/
113
114/*!
115 \fn void QAbstractExtensionManager::unregisterExtensions(QAbstractExtensionFactory *factory, const QString &iid)
116
117 Unregister the given \a factory with the extension specified by \a
118 iid.
119*/
120
121/*!
122 \fn QObject *QAbstractExtensionManager::extension(QObject *object, const QString &iid) const
123
124 Returns the extension, specified by \a iid, for the given \a
125 object.
126*/
127
128/*!
129 \fn template <class T> T qt_extension(QAbstractExtensionManager* manager, QObject *object)
130
131 \relates QExtensionManager
132
133 Returns the extension of the given \a object cast to type T if the
134 object is of type T (or of a subclass); otherwise returns 0. The
135 extension is retrieved using the given extension \a manager.
136
137 \snippet lib/tools_designer_src_lib_extension_extension.cpp 0
138
139 When implementing a custom widget plugin, a pointer to \QD's
140 current QDesignerFormEditorInterface object (\c formEditor) is
141 provided by the QDesignerCustomWidgetInterface::initialize()
142 function's parameter.
143
144 If the widget in the example above doesn't have a defined
145 QDesignerPropertySheetExtension, \c propertySheet will be a null
146 pointer.
147
148*/
149
150/*!
151 \macro Q_DECLARE_EXTENSION_INTERFACE(ExtensionName, Identifier)
152
153 \relates QExtensionManager
154
155 Associates the given \a Identifier (a string literal) to the
156 extension class called \a ExtensionName. The \a Identifier must be
157 unique. For example:
158
159 \snippet lib/tools_designer_src_lib_extension_extension.cpp 1
160
161 Using the company and product names is a good way to ensure
162 uniqueness of the identifier.
163
164 When implementing a custom extension class, you must use
165 Q_DECLARE_EXTENSION_INTERFACE() to enable usage of the
166 qt_extension() function. The macro is normally located right after the
167 class definition for \a ExtensionName, in the associated header
168 file.
169
170 \sa {Q_DECLARE_INTERFACE}{Q_DECLARE_INTERFACE()}
171*/
172
173QT_END_NAMESPACE
174

source code of qttools/src/designer/src/lib/extension/extension.cpp