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