diff options
| -rw-r--r-- | doc/src/declarative/extending.qdoc | 62 | ||||
| -rw-r--r-- | doc/src/declarative/qmlforcpp.qdoc | 713 | ||||
| -rw-r--r-- | doc/src/declarative/qtdeclarative.qdoc | 1 |
3 files changed, 59 insertions, 717 deletions
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index bc18108..db35961 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -511,6 +511,18 @@ to be used in bindings should have a NOTIFY signal instead. \l {Extending QML - Binding Example} shows the BirthdayParty example updated to include NOTIFY signals for use in binding. +\section1 Binding and Script Properties + +While generally no changes are needed to a C++ class to use property +binding, sometimes more advanced interaction between the binding engine and +an object is desirable. To facilitate this, there is a special exception +in the bind engine for allowing an object to access the binding directly. + +If a binding is assigned to a property with a type of QmlBinding +pointer (ie. \c {QmlBinding *}), each time the binding value changes, +a QmlBinding instance is assigned to that property. The QmlBinding instance +allows the object to read the binding and to evaluate the binding's current value. + \section1 Extension Objects \snippet examples/declarative/extending/extended/example.qml 0 @@ -522,15 +534,59 @@ When integrating existing classes and technology into QML, their APIs will often need to be tweaked to fit better into the declarative environment. Although the best results are usually obtained by modifying the original classes directly, if this is either not possible or is complicated by some other -concerns extension objects allow limited extension possibilities without +concerns, extension objects allow limited extension possibilities without direct modifications. -Extension objects can only add properties. +Extension objects are used to add additional properties to an existing type. +Extension objects can only add properties, not signals or methods. An extended +type definition allows the programmer to supply an additional type - known as the +extension type - when registering the target class whose properties are +transparently merged with the original target class when used from within QML. + +An extension class is a regular QObject, with a constructor that takes a QObject +pointer. When needed (extension classes are delay created until the first extended +property is accessed) the extension class is created and the target object is +passed in as the parent. When an extended property on the original is accessed, +the appropriate property on the extension object is used instead. + +When an extended type is installed, one of the +\code + #define QML_DEFINE_EXTENDED_TYPE(URI, VMAJ, VFROM, VTO, QmlName,T, ExtendedT) + #define QML_DEFINE_EXTENDED_NOCREATE_TYPE(T, ExtendedT) +\endcode +macros should be used instead of the regular \c QML_DEFINE_TYPE or +\c QML_DEFINE_NOCREATE_TYPE. The arguments are identical to the corresponding +non-extension object macro, except for the ExtendedT parameter which is the type +of the extension object. \section1 Optimization -*/ +Often to develop high performance elements it is helpful to know more about the +status of the QML engine. For example, it might be beneficial to delay +initializing some costly data structures until after all the properties have been +set. +The QML engine defines an interface class called QmlParserStatus, which contains a +number of virtual methods that are invoked at various stages during component +instantiation. To receive these notifications, an element implementation inherits +QmlParserStatus and notifies the Qt meta system using the Q_INTERFACES() macro. + +For example, + +\code +class Example : public QObject, public QmlParserStatus +{ + Q_OBJECT + Q_INTERFACES(QmlParserStatus) +public: + virtual void componentComplete() + { + qDebug() << "Woohoo! Now to do my costly initialization"; + } +}; +\endcode + +*/ /*! \page qml-extending-types.html diff --git a/doc/src/declarative/qmlforcpp.qdoc b/doc/src/declarative/qmlforcpp.qdoc deleted file mode 100644 index 5378571..0000000 --- a/doc/src/declarative/qmlforcpp.qdoc +++ /dev/null @@ -1,713 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Qt Software Information (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at qt-sales@nokia.com. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qmlforcpp.html - \target qmlforcpp - \title QML for C++ Programmers - - This page describes the QML format and how to use and extend it from C++. - - The QML syntax declaratively describes how to construct an in memory - object tree. QML is usually used to describe a visual scene graph - but it is not conceptually limited to this: the QML format is an abstract - description of \bold any object tree. - - QML also includes property bindings. Bindings are ECMAScript expressions - of a properties value. Whenever the value of the expression changes - - either for the first time at startup or subsequently thereafter - the - property is automatically updated with the new value. - - \tableofcontents - - \section1 Loading and using QML Files - - QmlComponent is used to load a QML file and to create object instances. - - In QML a component is the unit of instantiation, and the most basic unit - of scope. A component is like a template for how to construct an object - tree. One component can create multiple instances of this tree, but the - template remains constant. - - The following code uses the C++ interface to create 100 red rectangles - based on a simple declarative component description. - - \code - QmlEngine engine; - QmlComponent redRectangle(&engine, "Rectangle { color: \"red\"; width: 100; height: 100 }"); - for (int ii = 0; ii < 100; ++ii) { - QObject *rectangle = redRectangle.create(); - // ... do something with the rectangle ... - } - \endcode - - Each independent file describes a QML component, but it is also possible to - create sub-components within a QML file as will be shown later. - - \section1 QML Format 101 - - This is some sample QML code. - - \code - Image { - id: myRect - x: 10 - y: 10 - width: 100 - height: 100 - source: "background.png" - - Text { - height: 50 - width: 100 - color: "white" - font.fontSize: 16 - text: "Hello world!" - } - } - \endcode - - The QML snippet shown above instantiates one \c Image instance and one - \c Text instance and sets properties on both. \bold Everything in QML - ultimately comes down to either instantiating an object instance, or - assigning a property a value. QML relies heavily on Qt's meta object system - and can only instantiate classes that derive from QObject. - - In the above example, each property is placed on its own line. You can - also place multiple properties on one line by separating them with a - semi-colon. The code below is equivalent to the example above. - - \code - Image { - id: myRect - x: 10; y: 10; width: 100; height: 100 - source: "background.png" - Text { height: 50; width: 100; color: "white"; font.fontSize: 16; text: "Hello world!" } - } - \endcode - - QML can set properties that are more complex than just simple types like - integers and strings. Properties can be object pointers or Qt interface - pointers or even lists of object or Qt interface pointers! QML is typesafe, - and will ensure that only the valid types are assigned to properties. - - Assigning an object to a property is as simple as assigning a basic - integer. Attempting to assign an object to a property when type coercian - fails will produce an error. The following shows an example of valid and of - invalid QML and the corresponding C++ classes. - - \table - \row \o - \code - class Image : public QObject - { - ... - Q_PROPERTY(ImageFilter *filter READ filter WRITE setFilter) - }; - - class ImageFilter : public QObject - { - ... - }; - \endcode - \o \code - // OK - Image { - filter: ImageFilter {} - } - - // NOT OK: Image cannot be cast into ImageFilter - Image { - filter: Image {} - } - \endcode - \endtable - - Classes can also define an optional default property. The default property - is used for assignment if no explicit property has been specified. - Any object property can be the default, even complex properties like lists - of objects. The default property of the \c Rect class is the \c children - property, a list of \c Item's. In the following example, as both \c Image - and \c Text inherit from \c Item the \c Image and \c Text instances are - added to the parent's \c children property. - - \code - Rectangle { - Image {} - Text {} - } - \endcode - - Properties that return read-only object pointers can be used recursively. - This can be used, for example, to group properties together. The - \c Text element has a \c font property that returns an object with a number - of sub-properties such as \c family, \c bold, \c italic and \c size. - QML makes it easy to interact with these grouped properties, as the - following shows - everything you would expect to work, just does. - - \table - \row \o - \code - class Text : public ... - { - ... - Q_PROPERTY(Font *font READ font); - }; - class Font : public QObject - { - ... - Q_PROPERTY(QString family READ family WRITE setFamily); - Q_PROPERTY(bool bold READ bold WRITE setBold); - Q_PROPERTY(bool italic READ italic WRITE setItalic); - Q_PROPERTY(int size READ size WRITE setSize); - }; - \endcode - \o - \code - Text { - font.family: "helvetica" - font.pointSize: 12 - font { - bold: true - italic: true - } - } - \endcode - \endtable - - \section1 Defining QML Types - - The QML engine has no intrinsic knowledge of any class types. Instead - the programmer must define the C++ types, their corresponding QML - name, library namespace, and version availability. - - \code - #define QML_DECLARE_TYPE(T) - #define QML_DEFINE_TYPE(URI,VMAJ,VFROM,VTO,QmlName,T) - \endcode - - Adding these macros to your library or executable automatically makes the - C++ type \a T available from the declarative markup language under the - name \a QmlName. Of course there's nothing stopping you using the same - name for both the C++ and the QML name! - Any type can be added to the QML engine using these macros. The only - requirements are that \a T inherits QObject, is not abstract, - and that it has a default constructor. - - \section1 Property Binding - - Assigning constant values and trees to properties will only get you so - far. Property binding allows a property's value to be dependant on the - value of other properties and data. Whenever these dependencies change, - the property's value is automatically updated. - - Property bindings are ECMAScript expressions and can be applied to any - object property. C++ classes don't have to do anything special to get - binding support other than define appropriate properties. When a non-literal - property assignment appears in a QML file, it is automatically treated as a - property binding. - - Here's a simple example that stacks a red, blue and green rectangle. - Bindings are used to ensure that the height of each is kept equal to it's - parent's. Were the root rectangle's height property to change, the child - rectangles height would be updated automatically. - - \code - Rectangle { - color: "red" - width: 100 - Rectangle { - color: "blue" - width: 50 - height: parent.height - Rectangle { - color: "green" - width: 25 - height: parent.height - } - } - } - \endcode - - Binding expressions execute in a context. A context behaves as a scope and - defines how the expression resolves property and variable names. Although - the two expressions in the last example are the same, the value of \c parent - resolves differently because each executes in a different context. Although - QML generally takes care of everything for the programmer, a thorough - understanding of bind contexts is important in some of the more complex QML - structures. - - Every expression is executed in a bind context, encapsulated by the - QmlContext C++ class. As covered in the class documentation, a - bind context contains a map of names to values, and a list of default - objects. When resolving a name, the name to value map is searched first. - If the name cannot be found, the default object's are iterated in turn and - the context attempts to resolve the name as a property of one of the default - objects. - - There are generally two contexts involved in the execution of a binding. - The first is the "object context" - a bind context associated with the - closest instantiated object and containing just one default object, and - that's instantiated object itself. The effect of the object - context is pretty simple - names in the binding expression resolve to - properties on the object first. It is important to note - particularly in - the case of grouped properties - the object context is that of the - instantiated object, the consequences of which are shown below. - - \code - // OK // NOT OK - Text { Text { - font { font { - bold: font.italic bold: italic - } } - } } - \endcode - - The second context is the "component context". Each QML component (and - consequently each QML file) is created in its own unique binding context. - Like the object context, the component context contains just one default - object - but in this case it is the component's root object. An example - will illustrate best - the resultant text will read "background.png". - - \code - Image { - source: "background.png" - Text { - text: source - } - } - \endcode - - If the name is not found in either of these contexts, the context heirarchy - is searched parent-by-parent until the name is either found, or the - heirarchy is exhausted. - - The first property binding example shown involved fixing the height of three - rectangles. It did this by fixing the height of each rectangle to its - parent, rather than fixing them all to a single common point. Here's the - example rewritten to do just that. - - \code - Rectangle { - color: "red" - width: 100 - Rectangle { - color: "blue" - width: 50 - height: parent.height - Rectangle { - color: "green" - width: 25 - height: parent.parent.height - } - } - } - \endcode - - Clearly this sort of fragile relationship is undesirable and unmanageable - - moving the green rectangle to be a sibling of the blue or introducing a - further rectangle between the two would break the example. - - To address this problem, QML includes a way to directly reference any object - within a component (or parent component for that matter), called "ids". - Developers assign an object an id, and can then reference it directly by - name. Developers assign an object an id by setting the special \c id - property. Every object automatically has this magical property (if the - object also has an actual property called \c id, that gets set too). As - an id allows an object to be referenced directly, it must be unique within - a component. By convention, id's should start with an uppercase letter. - - \code - Rectangle { - id: root - color: "red" - width: greenRect.width + 75 - height: root.height - Rectangle { - color: "blue" - width: greenRect.width + 25 - Rectangle { - id: greenRect - color: "green" - width: 25 - height: root.height - } - } - } - \endcode - - To relate id's back to QmlContext, id's exist as properties on the - component context. - - Bind expressions can reference any object property. The QML bind engine - relies on the presence of the NOTIFY signal in the Q_PROPERTY declaration - on a class to alert it that a property's value has changed. If this is - omitted, the bind expression can still access the property's value, but - the expression will not be updated if the value changes. The following is - an example of a QML friendly property declaration. - - \code - class Example : public QObject - { - Q_OBJECT - Q_PROPERTY(int sample READ sample WRITE setSample NOTIFY sampleChanged) - public: - int sample() const; - void setSample(int); - signals: - void sampleChanged(int); - }; - \endcode - - While generally no changes are needed to a C++ class to use property - binding, sometimes more advanced interaction between the binding engine and - an object is desirable. To facilitate this, there is a special exception - in the bind engine for allowing an object to access the binding directly. - - If a binding is assigned to a property with a type of QmlBindableValue - pointer (ie. QmlBindableValue *), each time the binding value changes, - a QmlBindableValue instance is assigned to that property. The - QmlBindableValue instance allows the object to read the binding and to - evaluate the binding's current value. - - \section1 Signal Properties - - In addition to reading and writing regular properties, QML allows you to - easily associate ECMAScript with signals. Consider the following example, - in which Button is a made-up type with a clicked() signal. - - \code - Button { - text: "Hello world!" - onClicked: print(text) - } - \endcode - - Clicking on the button causes "Hello world!" to be printed to the console - (or lost forever if you're running Windows). - - Like properties, signals automatically become available in QML without - any additional work. As illustrated signals are mapped into QML as special - "signal properties", using the name "on<Signal Name>" where the first - character of the signal's name is uppercased. If more than one signal of - the same name is exist on a class, only the first is available (see the - \l Connection element for more general signal connections). - - An important observation to make here is the lack of braces. While both - property bindings and signal properties involve executing ECMAScript code, - property bindings dynamically update the property value (hence the braces), - whereas with signal properties the constant script "value" is actually - assigned to the signal property. Trying to bind a value to a signal - property will not work! - - Signal parameters are also available to the executing script, as shown - below, as long as you remember to name the parameters of your signal - in C++ (see QMetaMethod::parameterNames()). - - \table - \row \o - \code - Example { - onDoSomething: for(var ii = 0; ii < count; ++ii) - print(message) - } - \endcode - \o - \code - class Example : public QObject - { - Q_OBJECT - signals: - void doSomething(int count, const QString &message); - }; - \endcode - \endtable - - Just like property bindings, signal scripts are executed in a context. The - signal script context is identical in scope to the "object context" under - property binding, with the exception that it has the signal parameters - bound in. - - In addition to scripts, it is possible to assign objects to signal properties. - This automatically connects the signal to the object's default method. A - default method is defined just like a default property, though the special - "DefaultMethod" class info. - - \code - Q_CLASSINFO("DefaultMethod", "myMethod(int)"); - \endcode - - This is useful in achieving several use cases, like that below which moves - the button when it is clicked. - - \code - Button { - id: myButton - onClicked: NumberAnimation { - target: myButton - property: "x" - to: 100 - } - } - \endcode - - If the class itself actually defines a property called "on<Name>", this will - be assigned the string value and the signal handling behaviour will be - disabled. - - \section1 Attached Properties - - Attached properties allow unrelated types to annotate another type with some - additional properties. Some APIs or operations are inherintly imperative, - and attached properties help out when translating these APIs into the - declarative QML language. - - Qt's QGridLayout is one such example. - - \code - QGridLayout { - QLabel { - QGridLayout.row: 0 - QGridLayout.column: 0 - text: "Name:" - } - QLineEdit { - QGridLayout.row: 0 - QGridLayout.column: 1 - } - - QLabel { - QGridLayout.row: 1 - QGridLayout.column: 0 - text: "Occupation:" - } - QLineEdit { - QGridLayout.row: 1 - QGridLayout.column: 1 - } - } - \endcode - - Attached properties are identified by the use of a type name, in the - case shown \c QGridLayout, as a grouped property specifier. To prevent - ambiguity with actual class instantiations, attached properties must - always be specified to include a period but can otherwise be used just like - regular properties. - - C++ types provide attached properties by declaring the public function \c qmlAttachedProperties like this example. - - \table - \row \o - \code - static QObject *Type::qmlAttachedProperties(QObject *); - \endcode - \o - \code - class Example : public QObject - { - Q_OBJECT - public: - static QObject *qmlAttachedProperties(QObject *); - }; - \endcode - \endtable - - When an attached property is accessed, the QML engine will call this method - to create an attachment object, passing in the object instance that the - attached property applies to. The attachment object should define all - the attached properties, and is generally parented to the provided object - instance to avoid memory leaks. The QML engine does not saves this object, - so it is not necessary for the attached property function to ensure that - multiple calls for the same instance object return the same attached object. - - While conceptually simple, implementing an attachment object is not quite - so easy. The \c qmlAttachedProperties function is static - attachment - objects are not associated with any particular instance. How the values - of the attached properties apply to the behaviour they are controlling is - entirely implementation dependent. An additional consequence of this is - that \bold any object can attach \bold any attached property. The following is - perfectly valid, although the attached property has no actual effect: - - \code - FancyGridLayout { - Item { - Button { - QGridLayout.row: 1 - } - } - } - \endcode - - The property has no effect because the (made-up) FancyGridLayout type defines the meaning - of the \c row attached property only to apply to its direct children. It - is possible that other types may have attached properties that affect - objects that aren't their direct children. - - Attached properties are an advanced feature that should be used with - caution. - - \note We may implement a convenience wrapper that makes using attached - properties easier for the common "attach to children" case. - - \section1 Property Value Sources - - Intrinsically, the QML engine can assign a property either a static value, - such as a number or an object tree, or a property binding. It is possible for - advanced users to extend the engine to assign other "types" of values to - properties. These "types" are known as property value sources. - - Consider the following example. - - \code - Rectangle { - x: NumberAnimation { running: true; repeat; true; from: 0; to: 100; } - } - \endcode - - Here the \c x property of the rectangle will be animated from 0 to 100. - To support this, the NumberAnimation class inherits the - QmlPropertyValueSource class. If a type inherits this class and is assigned - to a property for which type assignment would otherwise fail (ie. the - property itself doesn't have a type of QmlPropertyValueSource *), the QML - engine will automatically set the property as the target of the value - source. - - \section1 Parser Status - - Generally using QML is a breeze - you implement your classes in C++, add - the appropriate properties, signals and slots and off you go. The QML - engine takes care of instantiating your classes and setting the properties - and everything works fine. - - However, sometimes it is helpful to know a little more about the status of - the QML parser. For example, it might be beneficial from a performance - standpoint to delay initializing some data structures until all the - properties have been set. - - To assist with this, the QML engine defines an interface class called - QmlParserStatus. The interface defines a number of virtual methods that are - invoked at various stages of the component instantiation. To receive - these notifications, all a class has to do is to inherit the interface, and - notify the Qt meta system using the Q_INTERFACES() macro. For example, - - \code - class Example : public QObject, public QmlParserStatus - { - Q_OBJECT - Q_INTERFACES(QmlParserStatus) - public: - virtual void componentComplete() - { - qDebug() << "Woohoo! Now to do my costly initialization"; - } - }; - \endcode - - \section1 Extended Type Definitions - - QML requires that types have the appropriate properties and signals to - work well within the declarative environment. In the case of existing - types, it is sometimes necessary to add signals, properties or slots to a - target class to make it more QML friendly but the original type cannot be - modified. For these cases, the QML engine supports extended type - definitions. - - An extended type definition allows the programmer to supply an additional - type - known as the extension type - when registering the target class - whose properties, signals and slots are transparently merged with the - original target class when used from within QML. - - An extension class is a regular QObject, with a constructor that takes a - QObject pointer. When needed (extension classes are delay created - until the first extension attribute is accessed) the extension - class is created and the target object is passed in as the parent. When - an extension attribute on the original is accessed, the appropriate signal, - property or slots on the extension object is used instead. - - When an extended type is installed, the - \code - #define QML_DEFINE_EXTENDED_TYPE(T,QmlName,ExtendedTypeName) - \endcode - macro should be used instead of the regular \c QML_DEFINE_TYPE. - - This example shows the addition of a read-only \c textLength property to - QLabel being implemented as an extension. - - \table - \row - \o - \code - class QLabelExtension : public QObject - { - Q_OBJECT - Q_PROPERTY(int textLength READ textLength) - public: - QWidgetExtension(QObject *parent) : QObject(parent) {} - int textLength() const { - return static_cast<QLabel *>(parent())->text().count(); - } - }; - QML_DEFINE_EXTENDED_TYPE(QLabel,QLabel,QLabelExtension); - \endcode - \o - \code - QLabel { - id: label1 - text: "Hello World!" - } - QLabel { - text: "label1 text length: " + label1.textLength - } - \endcode - \endtable - - Attributes defined through extensions are inherited, just like attributes - defined on a normal class. Any types that inherit from \c QLabel, will - also have the \c textLength property. Derived types can include additional - extensions which are merged together, but only a single extension can be - specified for each single C++ class. - - Extended type definitions can even be used to add an attached properties - function to a type - just declare the \c qmlAttachedProperties function on - the extension object. - -*/ - diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc index 1a13049..aeaa76e 100644 --- a/doc/src/declarative/qtdeclarative.qdoc +++ b/doc/src/declarative/qtdeclarative.qdoc @@ -67,7 +67,6 @@ \o \l {tutorials-declarative-contacts.html}{Tutorial: 'Introduction to QML'} \o \l {advtutorial.html}{Advanced Tutorial: 'Same Game'} \o \l {qmlexamples}{Examples} - \o \l {qmlforcpp}{QML For C++ Programmers} \endlist Core QML Features: |