diff options
Diffstat (limited to 'doc/src/declarative/extending.qdoc')
| -rw-r--r-- | doc/src/declarative/extending.qdoc | 79 |
1 files changed, 65 insertions, 14 deletions
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index 1ee3574..3b04ddb 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -65,20 +65,22 @@ template<typename T> int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) \endcode -Calling qmlRegisterType() registers the C++ type \a T with the QML system, and makes it available in QML -under the name \a qmlName in library \a uri version \a versionMajor.versionMinor. -The \a qmlName can be the same as the C++ type name. +Calling qmlRegisterType() registers the C++ type \a T with the QML +system, and makes it available in QML under the name \a qmlName in +library \a uri version \a versionMajor.versionMinor. The \a qmlName +can be the same as the C++ type name. Type \a T must be a concrete type that inherits QObject and has a default constructor. + \endquotation -Types can be registered by libraries (such as Qt does), application code, -or by plugins (see QDeclarativeExtensionPlugin). +Types can be registered by libraries, application code, or by plugins +(see QDeclarativeExtensionPlugin). -Once registered, all of the \l {Qt's Property System}{properties} of a supported -type are available for use within QML. QML has intrinsic support for properties -of these types: +Once registered, all \l {Qt's Property System}{properties} of the +supported types are available in QML. QML has intrinsic support for +properties of these types: \list \o bool @@ -94,9 +96,14 @@ of these types: \o QVariant \endlist -QML is typesafe. Attempting to assign an invalid value to a property will -generate an error. For example, assuming the name property of the \c Person -element had a type of QString, this would cause an error: +When a property of a supported type is added to a C++ class, in a QML +element based on the C++ class, a \e{value-changed} signal handler +will be available. See \l{Signal Support} below. + +QML is typesafe. Attempting to assign an invalid value to a property +will generate an error. For example, assuming the \e{name} property +of the \c Person element had a type of QString, this would cause an +error: \code Person { @@ -412,7 +419,28 @@ value will not be accessible from script. implement the onPartyStarted signal property. If you want to use signals from items not created in QML, you can access their -signals with the \l {Connections} element. +signals with the \l {Connections} element. + +Additionally, if a property is added to a C++ class, all QML elements +based on that C++ class will have a \e{value-changed} signal handler +for that property. The name of the signal handler is \e{on<Property +name>Changed}, with the first letter of the property name being upper +cased. + +\note If the NOTIFY signal for the added property is not simply +\c{<property_name>Changed()}, then you will get two equivalent signal +handlers, one because of the signal, one because of the property. For +example, if the property \c{test_property} with NOTIFY signal +\c{testPropChanged()} is added to a C++ class, then QML elements based +on that C++ class will have two signal handlers: +\c{onTest_propertyChanged} because of the property, and +\c{onTestPropChanged} because of the NOTIFY signal. For clarity, we +suggest that for properties exposed to QML in this way, the name of +the NOTIFY signal should be just \c{<property_name>Changed()}, so that +there will be just one signal handler in QML and one naming +convention used. + +See also \l {Extending types from QML}. \section1 Property Value Sources @@ -702,9 +730,30 @@ controls the color of the inner rectangle. \endcode +\section3 Property signal handlers + +Adding a property to an item automatically adds a \e{value-changed} +signal handler to the item. The signal hander is named +\c{on<Property_name>Changed}, with the first letter of the property +name being upper case. + +Signal handlers can have arbitrary JavaScript code assigned. The following +example shows how to output to a text console a new value of property +\c{innerColor} whenever the value of this property changes. + +\code + Rectangle { + id: rect + property color innerColor: "black" + + onInnerColorChanged: { console.log(rect.innerColor); } + } +\endcode + + \section3 Setting default properties -The optional "default" attribute marks a property as the \e {default property} +The optional \c default attribute for a property marks it as the \e {default property} for a type. This allows other items to specify the default property's value as child elements. For example, the \l Item element's default property is its \l{Item::children}{children} property. This allows the children of an \l Item @@ -729,12 +778,14 @@ Item { } \endqml +See the \l{declarative/ui-components/tabwidget}{TabWidget} example for a +demonstration of using default properties. + Specifying a default property overrides any existing default property (for example, any default property inherited from a parent item). Using the default attribute twice in the same type block is an error. - \target qml-property-aliases \section2 Property aliases |