diff options
Diffstat (limited to 'doc/src/declarative/extending.qdoc')
| -rw-r--r-- | doc/src/declarative/extending.qdoc | 252 |
1 files changed, 126 insertions, 126 deletions
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index 2d0dc34..649eab1 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -43,8 +43,8 @@ \page qml-extending.html \title Extending QML -The QML syntax declaratively describes how to construct an in memory object -tree. In Qt, QML is mainly used to describe a visual scene graph, but it is +The QML syntax declaratively describes how to construct an in memory object +tree. In Qt, QML is mainly used to describe a visual scene graph, but it is not conceptually limited to this: the QML format is an abstract description of any object tree. All the QML element types included in Qt are implemented using the C++ extension mechanisms describe on this page. Programmers can use these @@ -57,14 +57,14 @@ QML for their own independent use. \snippet examples/declarative/extending/adding/example.qml 0 -The QML snippet shown above instantiates one \c Person instance and sets +The QML snippet shown above instantiates one \c Person instance and sets the name and shoeSize properties on it. Everything in QML ultimately comes down -to either instantiating an object instance, or assigning a property a value. +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. -The QML engine has no intrinsic knowledge of any class types. Instead the -programmer must define the C++ types, and their corresponding QML name. +The QML engine has no intrinsic knowledge of any class types. Instead the +programmer must define the C++ types, and their corresponding QML name. Custom C++ types are made available to QML using these two macros: @@ -79,11 +79,11 @@ under the name \a QmlName in library URI version VMAJ.VFROM to VMAJ.VTO. \a T and \a QmlName may be the same. Generally the QML_DECLARE_TYPE() macro should be included immediately following -the type declaration (usually in its header file), and the QML_DEFINE_TYPE() +the type declaration (usually in its header file), and the QML_DEFINE_TYPE() macro in the implementation file. QML_DEFINE_TYPE() must not be present in a header file. -Type \a T must be a concrete type that inherits QObject and has a default +Type \a T must be a concrete type that inherits QObject and has a default constructor. \endquotation @@ -106,7 +106,7 @@ of these types: \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 +generate an error. For example, assuming the name property of the \c Person element had a type of QString, this would cause an error: \code @@ -127,13 +127,13 @@ The QML snippet shown above assigns a \c Person object to the \c BirthdayParty's celebrant property, and assigns three \c Person objects to the guests property. QML can set properties of types that are more complex than basic intrinsics like -integers and strings. Properties can also be object pointers, Qt interface -pointers, lists of object points, and lists of Qt interface pointers. As QML -is typesafe it ensures that only valid types are assigned to these properties, +integers and strings. Properties can also be object pointers, Qt interface +pointers, lists of object points, and lists of Qt interface pointers. As QML +is typesafe it ensures that only valid types are assigned to these properties, just like it does for primitive types. Properties that are pointers to objects or Qt interfaces are declared with the -Q_PROPERTY() macro, just like other properties. The celebrant property +Q_PROPERTY() macro, just like other properties. The celebrant property declaration looks like this: \snippet examples/declarative/extending/properties/birthdayparty.h 1 @@ -143,7 +143,7 @@ property can be assigned. QML also supports assigning Qt interfaces. To assign to a property whose type is a Qt interface pointer, the interface must also be registered with QML. As -they cannot be instantiated directly, registering a Qt interface is different +they cannot be instantiated directly, registering a Qt interface is different from registering a new QML type. The following macros are used instead: \quotation @@ -154,8 +154,8 @@ from registering a new QML type. The following macros are used instead: Register the C++ interface \a T with the QML system. -Generally the QML_DECLARE_INTERFACE() macro should be included immediately -following the interface declaration (usually in its header file), and the +Generally the QML_DECLARE_INTERFACE() macro should be included immediately +following the interface declaration (usually in its header file), and the QML_DEFINE_INTERFACE() macro in an implementation file. QML_DEFINE_INTERFACE() must not be present in a header file. @@ -163,7 +163,7 @@ Following registration, QML can coerce objects that implement this interface for assignment to appropriately typed properties. \endquotation -The guests property is a list of \c Person objects. Properties that are lists +The guests property is a list of \c Person objects. Properties that are lists of objects or Qt interfaces are also declared with the Q_PROPERTY() macro, just like other properties. List properties must have the type \c {QmlList<T *>*}. As with object properties, the type \a T must be registered with QML. @@ -172,7 +172,7 @@ The guest property declaration looks like this: \snippet examples/declarative/extending/properties/birthdayparty.h 2 -\l {Extending QML - Object and List Property Types Example} shows the complete +\l {Extending QML - Object and List Property Types Example} shows the complete code used to create the \c BirthdayParty type. \section1 Inheritance and Coercion @@ -182,17 +182,17 @@ code used to create the \c BirthdayParty type. The QML snippet shown above assigns a \c Boy object to the \c BirthdayParty's celebrant property, and assigns three other objects to the guests property. -QML supports C++ inheritance heirarchies and can freely coerce between known, +QML supports C++ inheritance heirarchies and can freely coerce between known, valid object types. This enables the creation of common base classes that allow the assignment of specialized classes to object or list properties. In the snippet shown, both the celebrant and the guests properties retain the Person -type used in the previous section, but the assignment is valid as both the Boy +type used in the previous section, but the assignment is valid as both the Boy and Girl objects inherit from Person. To assign to a property, the property's type must have been registered with QML. Both the QML_DEFINE_TYPE() and QML_DEFINE_INTERFACE() macros already shown can be used to register a type with QML. Additionally, if a type that acts purely -as a base class that cannot be instantiated from QML needs to be +as a base class that cannot be instantiated from QML needs to be registered these macros can be used: \quotation @@ -201,14 +201,14 @@ registered these macros can be used: #define QML_DEFINE_NOCREATE_TYPE(T) \endcode -Register the C++ type \a T with the QML system. QML_DEFINE_NOCREATE_TYPE() +Register the C++ type \a T with the QML system. QML_DEFINE_NOCREATE_TYPE() differs from QML_DEFINE_TYPE() in that it does not define a mapping between the C++ class and a QML element name, so the type is not instantiable from QML, but it is available for type coercion. Generally the QML_DECLARE_TYPE() macro should be included immediately following -the type declaration (usually in its header file), and the -QML_DEFINE_NOCREATE_TYPE() macro in the implementation file. +the type declaration (usually in its header file), and the +QML_DEFINE_NOCREATE_TYPE() macro in the implementation file. QML_DEFINE_NOCREATE_TYPE() must not be present in a header file. Type \a T must inherit QObject, but there are no restrictions on whether it is @@ -216,25 +216,25 @@ concrete or the signature of its constructor. \endquotation QML will automatically coerce C++ types when assigning to either an object -property, or to a list property. Only if coercion fails does an assignment +property, or to a list property. Only if coercion fails does an assignment error occur. -\l {Extending QML - Inheritance and Coercion Example} shows the complete +\l {Extending QML - Inheritance and Coercion Example} shows the complete code used to create the \c Boy and \c Girl types. \section1 Default Property \snippet examples/declarative/extending/default/example.qml 0 -The QML snippet shown above assigns a collection of objects to the +The QML snippet shown above assigns a collection of objects to the \c BirthdayParty's default property. The default property is a syntactic convenience that allows a type designer to -specify a single property as the type's default. The default property is +specify a single property as the type's default. The default property is assigned to whenever no explicit property is specified. As a convenience, it is behaviorally identical to assigning the default property explicitly by name. -From C++, type designers mark the default property using a Q_CLASSINFO() +From C++, type designers mark the default property using a Q_CLASSINFO() annotation: \quotation @@ -245,7 +245,7 @@ Q_CLASSINFO("DefaultProperty", "property") Mark \a property as the class's default property. \a property must be either an object property, or a list property. -A default property is optional. A derived class inherits its base class's +A default property is optional. A derived class inherits its base class's default property, but may override it in its own declaration. \a property can refer to a property declared in the class itself, or a property inherited from a base class. @@ -261,9 +261,9 @@ specify a default property. The QML snippet shown above assigns a number properties to the \c Boy object, including four properties using the grouped property syntax. -Grouped properties collect similar properties together into a single named +Grouped properties collect similar properties together into a single named block. Grouped properties can be used to present a nicer API to developers, and -may also simplify the implementation of common property collections across +may also simplify the implementation of common property collections across different types through implementation reuse. A grouped property block is implemented as a read-only object property. The @@ -271,35 +271,35 @@ shoe property shown is declared like this: \snippet examples/declarative/extending/grouped/person.h 1 -The ShoeDescription type declares the properties available to the grouped +The ShoeDescription type declares the properties available to the grouped property block - in this case the size, color, brand and price properties. -Grouped property blocks may declared and accessed be recusively. +Grouped property blocks may declared and accessed be recusively. -\l {Extending QML - Grouped Properties Example} shows the complete code used to +\l {Extending QML - Grouped Properties Example} shows the complete code used to implement the \c shoe property grouping. \section1 Attached Properties \snippet examples/declarative/extending/attached/example.qml 1 -The QML snippet shown above assigns the rsvp property using the attached +The QML snippet shown above assigns the rsvp property using the attached property syntax. Attached properties allow unrelated types to annotate other types with some -additional properties, generally for their own use. Attached properties are -identified through the use of the attacher type name, in the case shown -\c BirthdayParty, as a suffix to the property name. +additional properties, generally for their own use. Attached properties are +identified through the use of the attacher type name, in the case shown +\c BirthdayParty, as a suffix to the property name. In the example shown, \c BirthdayParty is called the attaching type, and the -Box instance the attachee object instance. +Box instance the attachee object instance. For the attaching type, an attached property block is implemented as a new QObject derived type, called the attachment object. The properties on the -attachment object are those that become available for use as the attached +attachment object are those that become available for use as the attached property block. -Any QML type can become an attaching type by declaring the +Any QML type can become an attaching type by declaring the \c qmlAttachedProperties() public function: \quotation @@ -310,21 +310,21 @@ Return an attachment object, of type \a AttachedPropertiesType, for the attachee \a object instance. It is customary, though not strictly required, for the attachment object to be parented to \a object to prevent memory leaks. -\a AttachedPropertiesType must be a QObject derived type. The properties on +\a AttachedPropertiesType must be a QObject derived type. The properties on this type will be accessible through the attached properties syntax. This method will be called at most once for each attachee object instance. The -QML engine will cache the returned instance pointer for subsequent attached +QML engine will cache the returned instance pointer for subsequent attached property accesses. Consequently the attachment object may not be deleted until \a object is destroyed. \endquotation -Conceptually, attached properties are a \e type exporting a set of additional +Conceptually, attached properties are a \e type exporting a set of additional properties that can be set on \e any other object instance. Attached properties cannot be limited to only attaching to a sub-set of object instances, although their effect may be so limited. -For example, a common usage scenario is for a type to enhance the properties +For example, a common usage scenario is for a type to enhance the properties available to its children in order to gather instance specific data. Here we add a rsvp field to all the guests coming to a birthday party: \code @@ -332,7 +332,7 @@ BirthdayParty { Boy { BirthdayParty.rsvp: "2009-06-01" } } \endcode -However, as a type cannot limit the instances to which the attachment object +However, as a type cannot limit the instances to which the attachment object must attach, the following is also allowed, even though adding a birthday party rsvp in this context will have no effect. \code @@ -349,10 +349,10 @@ an instance can be accessed using the following method: template<typename T> QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true); \endcode -Returns the attachment object attached to \a attachee by the attaching type +Returns the attachment object attached to \a attachee by the attaching type \a T. If type \a T is not a valid attaching type, this method always returns 0. -If \a create is true, a valid attachment object will always be returned, +If \a create is true, a valid attachment object will always be returned, creating it if it does not already exist. If \a create is false, the attachment object will only be returned if it has previously been created. \endquotation @@ -368,8 +368,8 @@ implement the rsvp attached property. The QML snippet shown above associates the evaluation of a ECMAScript expression with the emission of a Qt signal. -All Qt signals on a registered class become available as special "signal -properties" within QML to which the user can assign a single ECMAScript +All Qt signals on a registered class become available as special "signal +properties" within QML to which the user can assign a single ECMAScript expression. The signal property's name is a transformed version of the Qt signal name: "on" is prepended, and the first letter of the signal name upper cased. For example, the signal used in the example above has the following @@ -378,14 +378,14 @@ C++ signature: \snippet examples/declarative/extending/signal/birthdayparty.h 0 In classes with multiple signals with the same name, only the final signal -is accessible as a signal property. Although QML provides an element, +is accessible as a signal property. Although QML provides an element, \l Connection, for accessing the other signals it is less elegant. For the best QML API, class developers should avoid overloading signal names. Signal parameters become accessible by name to the assigned script. An unnamed parameter cannot be accessed, so care should be taken to name all the signal parameters in the C++ class declaration. The intrinsic types -listed in \l {Adding Types}, as well registered object types are permitted as +listed in \l {Adding Types}, as well registered object types are permitted as signal parameter types. Using other types is not an error, but the parameter value will not be accessible from script. @@ -400,14 +400,14 @@ implement the onPartyStarted signal property. The QML snippet shown above assigns a property value to the speaker property. A property value source generates a value for a property that changes over time. -Property value sources are most commonly used to do animation. Rather than +Property value sources are most commonly used to do animation. Rather than constructing an animation object and manually setting the animation's "target" property, a property value source can be assigned directly to a property of any type and automatically set up this association. -The example shown here is rather contrived: the speaker property of the +The example shown here is rather contrived: the speaker property of the BirthdayParty object is a string that is printed every time it is assigned and -the HappyBirthday value source generates the lyrics of the song +the HappyBirthday value source generates the lyrics of the song "Happy Birthday". \snippet examples/declarative/extending/valuesource/birthdayparty.h 0 @@ -417,9 +417,9 @@ the case of a property value source, rather than assigning the object instance itself, the QML engine sets up an association between the value source and the property. -Property value sources are special types that derive from the +Property value sources are special types that derive from the QmlPropertyValueSource base class. This base class contains a single method, -QmlPropertyValueSource::setTarget(), that the QML engine invokes when +QmlPropertyValueSource::setTarget(), that the QML engine invokes when associating the property value source with a property. The relevant part of the HappyBirthday type declaration looks like this: @@ -429,10 +429,10 @@ the HappyBirthday type declaration looks like this: In all other respects, property value sources are regular QML types. They must be registered with the QML engine using the same macros as other types, and can -contain properties, signals and methods just like other types. +contain properties, signals and methods just like other types. When a property value source object is assigned to a property, QML first tries -to assign it normally, as though it were a regular QML type. Only if this +to assign it normally, as though it were a regular QML type. Only if this assignment fails does the engine call the setTarget() method. This allows the type to also be used in contexts other than just as a value source. @@ -444,20 +444,20 @@ implement the HappyBirthday property value source. \snippet examples/declarative/extending/binding/example.qml 0 \snippet examples/declarative/extending/binding/example.qml 1 -The QML snippet shown above uses a property binding to ensure the +The QML snippet shown above uses a property binding to ensure the HappyBirthday's name property remains up to date with the celebrant. Property binding is a core feature of QML. In addition to assigning literal -values, property bindings allow the developer to assign an arbitrarily complex +values, property bindings allow the developer to assign an arbitrarily complex ECMAScript expression that may include dependencies on other property values. -Whenever the expression's result changes - through a change in one of its +Whenever the expression's result changes - through a change in one of its constituent values - the expression is automatically reevaluated and the new result assigned to the property. All properties on custom types automatically support property binding. However, -for binding to work correctly, QML must be able to reliably determine when a +for binding to work correctly, QML must be able to reliably determine when a property has changed so that it knows to reevaluate any bindings that depend on -the property's value. QML relies on the presence of a +the property's value. QML relies on the presence of a \c {Qt's Property System}{NOTIFY signal} for this determination. Here is the celebrant property declaration: @@ -468,7 +468,7 @@ The NOTIFY attribute is followed by a signal name. It is the responsibility of the class implementer to ensure that whenever the property's value changes, the NOTIFY signal is emitted. The signature of the NOTIFY signal is not important to QML. -To prevent loops or excessive evaluation, developers should ensure that the +To prevent loops or excessive evaluation, developers should ensure that the signal is only emitted whenever the property's value is actually changed. If a property, or group of properties, is infrequently used it is permitted to use the same NOTIFY signal for several properties. This should be done with care to @@ -476,10 +476,10 @@ ensure that performance doesn't suffer. To keep QML reliable, if a property does not have a NOTIFY signal, it cannot be used in a binding expression. However, the property can still be assigned -a binding as QML does not need to monitor the property for change in that +a binding as QML does not need to monitor the property for change in that scenario. -Consider a custom type, \c TestElement, that has two properties, "a" and "b". +Consider a custom type, \c TestElement, that has two properties, "a" and "b". Property "a" does not have a NOTIFY signal, and property "b" does have a NOTIFY signal. @@ -495,7 +495,7 @@ TestElement { \endcode The presence of a NOTIFY signal does incur a small overhead. There are cases -where a property's value is set at object construction time, and does not +where a property's value is set at object construction time, and does not subsequently change. The most common case of this is when a type uses \l {Grouped Properties}, and the grouped property object is allocated once, and only freed when the object is deleted. In these cases, the CONSTANT attribute @@ -520,9 +520,9 @@ modifying its source code. 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 +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 direct modifications. Extension objects can only add properties. @@ -536,29 +536,29 @@ Extension objects can only add properties. \page qml-extending-types.html \title Extending types from QML -Many of the elements available for use in QML are implemented in -\l {QML for C++ Programmers}{C++}. These types are know as "core types". QML -allows programmers to build new, fully functional elements without using C++. -Existing core types can be extended, and new types defined entirely in the QML +Many of the elements available for use in QML are implemented in +\l {QML for C++ Programmers}{C++}. These types are know as "core types". QML +allows programmers to build new, fully functional elements without using C++. +Existing core types can be extended, and new types defined entirely in the QML language. \tableofcontents \section1 Adding new properties -New properties can be added to an existing type. These new properties are +New properties can be added to an existing type. These new properties are available for use within QML, and also appear as regular Qt properties on the C++ object, accessible through the regular property access mechanisms. -Like all properties in QML, custom properties are typed. The type is used to +Like all properties in QML, custom properties are typed. The type is used to define the property's behavior, and also determines the C++ type of the created -Qt property. The following table shows the list of types available when +Qt property. The following table shows the list of types available when declaring a new property, and the corresponding C++ type. \table -\header \o QML Type Name \o C++ Type Name -\row \o int \o int -\row \o bool \o bool +\header \o QML Type Name \o C++ Type Name +\row \o int \o int +\row \o bool \o bool \row \o double \o double \row \o real \o double \row \o string \o QString @@ -589,7 +589,7 @@ in the same type block is an error. However, a new property may reuse the name of an existing property on the type. This should be done with caution, as the existing property will be hidden, and become inaccessible. -The <type> must be one of the QML type names shown in the above table. +The <type> must be one of the QML type names shown in the above table. Additionally, an optional default value of the property can be provided. The default value is a convenient shortcut, but is behaviorally identical to doing it in two steps, like this: @@ -627,10 +627,10 @@ controls the color of the inner rectangle. \section2 Property aliases Property aliases are a more advanced form of property declaration. Unlike a -property definition, that allocates a new, unique storage space for the -property, a property alias connects the newly declared property (called the -aliasing property) to an existing property (the aliased property). Read -operations on the aliasing property act as read operations on the aliased +property definition, that allocates a new, unique storage space for the +property, a property alias connects the newly declared property (called the +aliasing property) to an existing property (the aliased property). Read +operations on the aliasing property act as read operations on the aliased property, and write operations on the aliasing property as write operations on the aliased property. @@ -641,7 +641,7 @@ A property alias declaration looks a lot like a property definition: As the aliasing property has the same type as the aliased property, an explicit type is omitted, and the special "alias" keyword is used. Instead of a default -value, a property alias includes a compulsary alias reference. The alias +value, a property alias includes a compulsary alias reference. The alias reference is used to locate the aliased property. While similar to a property binding, the alias reference syntax is highly restricted. @@ -656,11 +656,11 @@ alias reference syntax may become more flexibly in future releases. Here is the property definition example rewritten to use property aliases. \code Rectangle { - property alias innerColor: InnerRect.color + property alias innerColor: innerRect.color color: "red"; width: 100; height: 100 Rectangle { - id: InnerRect + id: innerRect anchors.centerIn: parent width: parent.width - 10 height: parent.height - 10 @@ -678,24 +678,24 @@ use the aliased property directly. For example, this will not work: \code // Does NOT work - property alias innerColor: InnerRect.color + property alias innerColor: innerRect.color innerColor: "black" \endcode -This behavior is required to allow type developers to redefine the behavior +This behavior is required to allow type developers to redefine the behavior of existing property names while continuing to use the existing behavior within -the type they are building, something that is not possible with property +the type they are building, something that is not possible with property definitions. In the example used so far, this could allows the developer to fix -the external rectangle's color as "red" and redefine the "color" property to +the external rectangle's color as "red" and redefine the "color" property to refer to the inner rectangle, like this: \code Rectangle { - property alias color: InnerRect.color + property alias color: innerRect.color color: "red"; width: 100; height: 100 Rectangle { - id: InnerRect + id: innerRect anchors.centerIn: parent width: parent.width - 10 height: parent.height - 10 @@ -705,18 +705,18 @@ Rectangle { \endcode Users of this type would not be able to affect the color of the red rectangle, -but would find using the "color" property, rather than the strange new +but would find using the "color" property, rather than the strange new "innerColor" property, much more familiar. -A second, much less significant, consequence of the delayed activation of +A second, much less significant, consequence of the delayed activation of aliases is that an alias reference cannot refer to another aliasing property declared within the same component. This will not work: \code // Does NOT work - id: Root - property alias innerColor: InnerRect.color - property alias innerColor2: Root.innerColor + id: root + property alias innerColor: innerRect.color + property alias innerColor2: root.innerColor \endcode From outside the component, aliasing properties appear as regular Qt properties @@ -724,7 +724,7 @@ and consequently can be used in alias references. \section1 Adding new signals -New signals can be added to an existing type. These new signals are available +New signals can be added to an existing type. These new signals are available for use within QML, and also appear as regular Qt signals on the C++ object that can be used in Qt signal/slot connections. @@ -734,9 +734,9 @@ signal <name>[([<type> <parameter name>[, ...]])] \endcode This declaration may appear anywhere within a type body, but it is customary to -include it at the top. Attempting to declare two signals or methods with the -same name in the same type block is an error. However, a new signal may reuse -the name of an existing signal on the type. This should be done with caution, +include it at the top. Attempting to declare two signals or methods with the +same name in the same type block is an error. However, a new signal may reuse +the name of an existing signal on the type. This should be done with caution, as the existing signal may be hidden and become inaccessible. The options for parameter types are the same as for property types (see @@ -754,7 +754,7 @@ Here are three examples of signal declarations: \section1 Adding new methods -New methods can be added to an existing type. These new methods are available +New methods can be added to an existing type. These new methods are available for use within QML, and also appear as regular Qt slots on the C++ object that can be used in Qt signal/slot connections. @@ -763,9 +763,9 @@ function <name>([<parameter name>[, ...]]) { <body> } \endcode This declaration may appear anywhere within a type body, but it is customary to -include it at the top. Attempting to declare two methods or signals with the +include it at the top. Attempting to declare two methods or signals with the same name in the same type block is an error. However, a new method may reuse -the name of an existing method on the type. This should be done with caution, +the name of an existing method on the type. This should be done with caution, as the existing method may be hidden and become inaccessible. Methods parameters are not typed. In C++ these parameters are of type QVariant. @@ -783,24 +783,24 @@ Item { \section1 Defining new Components -A component is a reusable type with a well-defined interface built entirely in +A component is a reusable type with a well-defined interface built entirely in QML. Components appear as regular QML elements, and can be used interchangably with core types. Components allow developers to create new types to be reused -in other projects without the use of C++. Components can also help to reduce -duplication inside one project by limiting the need for large numbers of +in other projects without the use of C++. Components can also help to reduce +duplication inside one project by limiting the need for large numbers of copy-and-pasted blocks. -Any snippet of QML code can become a component, just by placing it in the file +Any snippet of QML code can become a component, just by placing it in the file "<Name>.qml" where <Name> is the new element name, and begins with an uppercase letter. These QML files automatically become available as new QML element types to other QML components and applications in the same directory. -For example, here we show how a component named "Box" is defined and used +For example, here we show how a component named "Box" is defined and used multiple times by an application. \table \row -\o application.qml +\o application.qml \code Rectangle { width: 100; height: 400; @@ -812,19 +812,19 @@ Rectangle { \o Box.qml \code Rectangle { - width: 100; height: 100; + width: 100; height: 100; color: "blue" } \endcode \endtable -Components may be collected into \l {Modules} that gives the +Components may be collected into \l {Modules} that gives the developer more freedom than just putting files in the same directory. \section2 Building reusable components -A component type built to be reused by others must have a well defined -interface. In QML, an interface consists of a defined collection of +A component type built to be reused by others must have a well defined +interface. In QML, an interface consists of a defined collection of properties, signals and methods. Users of a component have access to all the properties, signals and methods defined on the root element of the component. @@ -846,7 +846,7 @@ available externally. Here we add a "text" property: \table \row -\o application.qml +\o application.qml \code Rectangle { width: 100; height: 400; @@ -858,25 +858,25 @@ Rectangle { \o Box.qml \code Rectangle { - property alias text: MyText.text - width: 100; height: 100; + property alias text: myText.text + width: 100; height: 100; color: "blue" Text { - id: MyText + id: myText anchors.centerIn: parent - } + } } \endcode \endtable Methods and signals may be added in the same way. -As all external methods, signals and properties are accessible to external -users, developers should ensure that setting these properties does not have +As all external methods, signals and properties are accessible to external +users, developers should ensure that setting these properties does not have any undesirable side-effects. For most resiliance, root level properties should only be used for literal default values. When a root level property must be used inside the component - such as the children property - property aliases can be used to redirect this property to a "safe" location for external users. -Try to think of the root level properties as being "owned" by the components +Try to think of the root level properties as being "owned" by the components user, rather than the component itself. */ |