Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
propertysheet.qdoc
Go to the documentation of this file.
1
// Copyright (C) 2016 The Qt Company Ltd.
2
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4
/*!
5
\class QDesignerPropertySheetExtension
6
7
\brief The QDesignerPropertySheetExtension class allows you to
8
manipulate a widget's properties which is displayed in Qt
9
Designer's property editor.
10
11
\sa QDesignerDynamicPropertySheetExtension
12
13
\inmodule QtDesigner
14
15
QDesignerPropertySheetExtension provides a collection of functions that
16
are typically used to query a widget's properties, and to
17
manipulate the properties' appearance in the property editor. For
18
example:
19
20
\snippet plugins/doc_src_qtdesigner.cpp 15
21
22
Note that if you change the value of a property using the
23
QDesignerPropertySheetExtension::setProperty() function, the undo
24
stack is not updated. To ensure that a property's value can be
25
reverted using the undo stack, you must use the
26
QDesignerFormWindowCursorInterface::setProperty() function, or its
27
buddy \l
28
{QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()},
29
instead.
30
31
When implementing a custom widget plugin, a pointer to \QD's
32
current QDesignerFormEditorInterface object (\c formEditor in the
33
example above) is provided by the
34
QDesignerCustomWidgetInterface::initialize() function's parameter.
35
36
The property sheet, or any other extension, can be retrieved by
37
querying \QD's extension manager using the qt_extension()
38
function. When you want to release the extension, you only need to
39
delete the pointer.
40
41
All widgets have a default property sheet which populates \QD's
42
property editor with the widget's properties (i.e the ones defined
43
with the Q_PROPERTY() macro). But QDesignerPropertySheetExtension
44
also provides an interface for creating custom property sheet
45
extensions.
46
47
Keep the following limitations in mind:
48
49
\list
50
\li \QD uses the QDesignerPropertySheetExtension to feed its
51
property editor. Whenever a widget is selected in its workspace,
52
\QD will query for the widget's property sheet extension. If the
53
selected widget has an implemented property sheet extension, this
54
extension will override the default property sheet.
55
56
\li The data types used by the property sheet for some properties
57
are opaque custom QVariant types containing additional information
58
instead of plain Qt data types. For example, this is the case for
59
enumerations, flags, icons, pixmaps and strings.
60
61
\li \QD's property editor has no implementation for handling
62
Q_PROPERTY types for custom types that have been declared
63
with Q_DECLARE_METATYPE().
64
\endlist
65
66
To create a property sheet extension, your extension class must
67
inherit from both QObject and
68
QDesignerPropertySheetExtension. Then, since we are implementing
69
an interface, we must ensure that it's made known to the meta
70
object system using the Q_INTERFACES() macro:
71
72
\snippet plugins/doc_src_qtdesigner.cpp 16
73
74
This enables \QD to use qobject_cast() to query for supported
75
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 property 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 property 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 property
87
sheet extension for the selected widget, is found. This factory
88
will then make an instance of the extension. If no such factory
89
can be found, \QD will use the default property sheet.
90
91
There are four available types of extensions in \QD:
92
QDesignerContainerExtension, QDesignerMemberSheetExtension,
93
QDesignerPropertySheetExtension and QDesignerTaskMenuExtension. Qt
94
Designer's behavior is the same whether the requested extension is
95
associated with a multi page container, a member sheet, a property
96
sheet or a task menu.
97
98
The QExtensionFactory class provides a standard extension factory,
99
and can also be used as an interface for custom extension
100
factories. You can either create a new QExtensionFactory and
101
reimplement the QExtensionFactory::createExtension() function. For
102
example:
103
104
\snippet plugins/doc_src_qtdesigner.cpp 17
105
106
Or you can use an existing factory, expanding the
107
QExtensionFactory::createExtension() function to make the factory
108
able to create a property sheet extension as well. For
109
example:
110
111
\snippet plugins/doc_src_qtdesigner.cpp 18
112
113
For a complete example using an extension class, see the \l
114
{taskmenuextension}{Task Menu Extension example}. The
115
example shows how to create a custom widget plugin for Qt
116
Designer, and how to use the QDesignerTaskMenuExtension class
117
to add custom items to \QD's task menu.
118
119
\sa QExtensionFactory, QExtensionManager, {Creating Custom Widget
120
Extensions}
121
*/
122
123
/*!
124
\fn QDesignerPropertySheetExtension::~QDesignerPropertySheetExtension()
125
126
Destroys the property sheet extension.
127
*/
128
129
/*!
130
\fn int QDesignerPropertySheetExtension::count() const
131
132
Returns the selected widget's number of properties.
133
*/
134
135
/*!
136
\fn int QDesignerPropertySheetExtension::indexOf(const QString &name) const
137
138
Returns the index for a given property \a name.
139
140
\sa propertyName()
141
*/
142
143
/*!
144
\fn QString QDesignerPropertySheetExtension::propertyName(int index) const
145
146
Returns the name of the property at the given \a index.
147
148
\sa indexOf()
149
*/
150
151
/*!
152
\fn QString QDesignerPropertySheetExtension::propertyGroup(int index) const
153
154
Returns the property group for the property at the given \a index.
155
156
\QD's property editor supports property groups, i.e. sections of
157
related properties. A property can be related to a group using the
158
setPropertyGroup() function. The default group of any property is
159
the name of the class that defines it. For example, the
160
QObject::objectName property appears within the QObject property
161
group.
162
163
\sa indexOf(), setPropertyGroup()
164
*/
165
166
/*!
167
\fn void QDesignerPropertySheetExtension::setPropertyGroup(int index, const QString &group)
168
169
Sets the property group for the property at the given \a index to
170
\a group.
171
172
Relating a property to a group makes it appear within that group's
173
section in the property editor. The default property group of any
174
property is the name of the class that defines it. For example,
175
the QObject::objectName property appears within the QObject
176
property group.
177
178
\sa indexOf(), property(), propertyGroup()
179
*/
180
181
/*!
182
\fn bool QDesignerPropertySheetExtension::hasReset(int index) const
183
184
Returns true if the property at the given \a index has a reset
185
button in \QD's property editor, otherwise false.
186
187
\sa indexOf(), reset()
188
*/
189
190
/*!
191
\fn bool QDesignerPropertySheetExtension::reset(int index)
192
193
Resets the value of the property at the given \a index, to the
194
default value. Returns true if a default value could be found, otherwise false.
195
196
\sa indexOf(), hasReset(), isChanged()
197
*/
198
199
/*!
200
\fn bool QDesignerPropertySheetExtension::isVisible(int index) const
201
202
Returns true if the property at the given \a index is visible in
203
\QD's property editor, otherwise false.
204
205
\sa indexOf(), setVisible()
206
*/
207
208
/*!
209
\fn void QDesignerPropertySheetExtension::setVisible(int index, bool visible)
210
211
If \a visible is true, the property at the given \a index is
212
visible in \QD's property editor; otherwise the property is
213
hidden.
214
215
\sa indexOf(), isVisible()
216
*/
217
218
/*!
219
\fn bool QDesignerPropertySheetExtension::isAttribute(int index) const
220
221
Returns true if the property at the given \a index is an attribute,
222
which will be \e excluded from the UI file, otherwise false.
223
224
\sa indexOf(), setAttribute()
225
*/
226
227
/*!
228
\fn void QDesignerPropertySheetExtension::setAttribute(int index, bool attribute)
229
230
If \a attribute is true, the property at the given \a index is
231
made an attribute which will be \e excluded from the UI file;
232
otherwise it will be included.
233
234
\sa indexOf(), isAttribute()
235
*/
236
237
/*!
238
\fn QVariant QDesignerPropertySheetExtension::property(int index) const
239
240
Returns the value of the property at the given \a index.
241
242
\sa indexOf(), setProperty(), propertyGroup()
243
*/
244
245
/*!
246
\fn void QDesignerPropertySheetExtension::setProperty(int index, const QVariant &value)
247
248
Sets the \a value of the property at the given \a index.
249
250
\warning If you change the value of a property using this
251
function, the undo stack is not updated. To ensure that a
252
property's value can be reverted using the undo stack, you must
253
use the QDesignerFormWindowCursorInterface::setProperty()
254
function, or its buddy \l
255
{QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()},
256
instead.
257
258
\sa indexOf(), property(), propertyGroup()
259
*/
260
261
/*!
262
\fn bool QDesignerPropertySheetExtension::isChanged(int index) const
263
264
Returns true if the value of the property at the given \a index
265
differs from the property's default value, otherwise false.
266
267
\sa indexOf(), setChanged(), reset()
268
*/
269
270
/*!
271
\fn void QDesignerPropertySheetExtension::setChanged(int index, bool changed)
272
273
Sets whether the property at the given \a index is different from
274
its default value, or not, depending on the \a changed parameter.
275
276
\sa indexOf(), isChanged()
277
*/
278
279
/*!
280
\fn bool QDesignerPropertySheetExtension::isEnabled(int index) const
281
282
Returns true if the property at the given \a index is enabled in
283
\QD's property editor, otherwise false.
284
285
\since 5.0
286
287
\sa indexOf()
288
*/
qttools
src
designer
src
lib
sdk
propertysheet.qdoc
Generated on Sat Sep 21 2024 01:06:10 for Qt by
1.12.0