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 | |
31 | QT_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 | |
173 | QT_END_NAMESPACE |
174 | |