1/****************************************************************************
2**
3** Copyright (C) 2015 The Qt Company Ltd.
4** Contact: http://www.qt.io/licensing/
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:FDL$
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 http://www.qt.io/terms-conditions. For further
15** information use the contact form at http://www.qt.io/contact-us.
16**
17** GNU Free Documentation License Usage
18** Alternatively, this file may be used under the terms of the GNU Free
19** Documentation License version 1.3 as published by the Free Software
20** Foundation and appearing in the file included in the packaging of
21** this file.  Please review the following information to ensure
22** the GNU Free Documentation License version 1.3 requirements
23** will be met: http://www.gnu.org/copyleft/fdl.html.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29    \class QDesignerMemberSheetExtension
30
31    \brief The QDesignerMemberSheetExtension class allows you to
32    manipulate a widget's member functions which is displayed when
33    configuring connections using Qt Designer's mode for editing
34    signals and slots.
35
36    \inmodule QtDesigner
37
38    QDesignerMemberSheetExtension is a collection of functions that is
39    typically used to query a widget's member functions, and to
40    manipulate the member functions' appearance in \QD's signals and
41    slots editing mode. For example:
42
43    \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 2
44
45    When implementing a custom widget plugin, a pointer to \QD's
46    current QDesignerFormEditorInterface object (\c formEditor in the
47    example above) is provided by the
48    QDesignerCustomWidgetInterface::initialize() function's parameter.
49
50    The member sheet (and any other extension), can be retrieved by
51    querying \QD's extension manager using the qt_extension()
52    function. When you want to release the extension, you only need to
53    delete the pointer.
54
55    All widgets have a default member sheet used in \QD's signals and
56    slots editing mode with the widget's member functions. But
57    QDesignerMemberSheetExtension also provides an interface for
58    creating custom member sheet extensions.
59
60    \warning \QD uses the QDesignerMemberSheetExtension to facilitate
61    the signal and slot editing mode. Whenever a connection between
62    two widgets is requested, \QD will query for the widgets' member
63    sheet extensions. If a widget has an implemented member sheet
64    extension, this extension will override the default member sheet.
65
66    To create a member sheet extension, your extension class must
67    inherit from both QObject and QDesignerMemberSheetExtension. Then,
68    since we are implementing an interface, we must ensure that it's
69    made known to the meta object system using the Q_INTERFACES()
70    macro:
71
72    \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 3
73
74    This enables \QD to use qobject_cast() to query for
75    supported interfaces using nothing but a QObject pointer.
76
77    In \QD the extensions are not created until they are
78    required. For that reason, when implementing a member sheet
79    extension, you must also create a QExtensionFactory, i.e a class
80    that is able to make an instance of your extension, and register
81    it using \QD's \l {QExtensionManager}{extension manager}.
82
83    When a widget's member sheet extension is required, \QD's \l
84    {QExtensionManager}{extension manager} will run through all its
85    registered factories calling QExtensionFactory::createExtension()
86    for each until the first one that is able to create a member sheet
87    extension for that widget, is found. This factory will then make
88    an instance of the extension. If no such factory is found, \QD
89    will use the default member sheet.
90
91    There are four available types of extensions in \QD:
92    QDesignerContainerExtension, QDesignerMemberSheetExtension,
93    QDesignerPropertySheetExtension and
94    QDesignerTaskMenuExtension. \QD's behavior is the same whether the
95    requested extension is associated with a multi page container, a
96    member sheet, a property sheet or a task menu.
97
98    The QExtensionFactory class provides a standard extension
99    factory, and can also be used as an interface for custom
100    extension factories. You can either create a new
101    QExtensionFactory and reimplement the
102    QExtensionFactory::createExtension() function. For example:
103
104    \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 4
105
106    Or you can use an existing factory, expanding the
107    QExtensionFactory::createExtension() function to make the factory
108    able to create a member sheet extension as well. For example:
109
110    \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 5
111
112    For a complete example using an extension class, see \l
113    {designer/taskmenuextension}{Task Menu Extension example}. The
114    example shows how to create a custom widget plugin for Qt
115    Designer, and how to to use the QDesignerTaskMenuExtension class
116    to add custom items to \QD's task menu.
117
118    \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget
119    Extensions}
120*/
121
122/*!
123    \fn QDesignerMemberSheetExtension::~QDesignerMemberSheetExtension()
124
125    Destroys the member sheet extension.
126*/
127
128/*!
129    \fn int QDesignerMemberSheetExtension::count() const
130
131    Returns the extension's number of member functions.
132*/
133
134/*!
135    \fn int QDesignerMemberSheetExtension::indexOf(const QString &name) const
136
137    Returns the index of the member function specified by the given \a
138    name.
139
140    \sa memberName()
141*/
142
143/*!
144    \fn QString QDesignerMemberSheetExtension::memberName(int index) const
145
146    Returns the name of the member function with the given \a index.
147
148    \sa indexOf()
149*/
150
151/*!
152    \fn QString QDesignerMemberSheetExtension::memberGroup(int index) const
153
154    Returns the name of the member group specified for the function
155    with the given \a index.
156
157    \sa indexOf(), setMemberGroup()
158*/
159
160/*!
161    \fn void QDesignerMemberSheetExtension::setMemberGroup(int index, const QString &group)
162
163    Sets the member group of the member function with the given \a
164    index, to \a group.
165
166    \sa indexOf(), memberGroup()
167*/
168
169/*!
170    \fn bool QDesignerMemberSheetExtension::isVisible(int index) const
171
172    Returns true if the member function with the given \a index is
173    visible in \QD's signal and slot editor, otherwise false.
174
175    \sa indexOf(), setVisible()
176*/
177
178/*!
179    \fn void QDesignerMemberSheetExtension::setVisible(int index, bool visible)
180
181    If \a visible is true, the member function with the given \a index
182    is visible in \QD's signals and slots editing mode; otherwise the
183    member function is hidden.
184
185    \sa indexOf(), isVisible()
186*/
187
188/*!
189    \fn virtual bool QDesignerMemberSheetExtension::isSignal(int index) const
190
191    Returns true if the member function with the given \a index is a
192    signal, otherwise false.
193
194    \sa indexOf()
195*/
196
197/*!
198    \fn bool QDesignerMemberSheetExtension::isSlot(int index) const
199
200    Returns true if the member function with the given \a index is a
201    slot, otherwise false.
202
203    \sa indexOf()
204*/
205
206/*!
207    \fn bool QDesignerMemberSheetExtension::inheritedFromWidget(int index) const
208
209    Returns true if the member function with the given \a index is
210    inherited from QWidget, otherwise false.
211
212    \sa indexOf()
213*/
214
215/*!
216    \fn QString QDesignerMemberSheetExtension::declaredInClass(int index) const
217
218    Returns the name of the class in which the member function with
219    the given \a index is declared.
220
221    \sa indexOf()
222*/
223
224/*!
225    \fn QString QDesignerMemberSheetExtension::signature(int index) const
226
227    Returns the signature of the member function with the given \a
228    index.
229
230    \sa indexOf()
231*/
232
233/*!
234    \fn QList<QByteArray> QDesignerMemberSheetExtension::parameterTypes(int index) const
235
236    Returns the parameter types of the member function with the given
237    \a index, as a QByteArray list.
238
239    \sa indexOf(), parameterNames()
240*/
241
242/*!
243    \fn QList<QByteArray> QDesignerMemberSheetExtension::parameterNames(int index) const
244
245    Returns the parameter names of the member function with the given
246    \a index, as a QByteArray list.
247
248    \sa indexOf(), parameterTypes()
249*/
250