diff options
Diffstat (limited to 'src/qml/doc/src/qmllanguageref')
6 files changed, 221 insertions, 96 deletions
diff --git a/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc index 2de4eb0c18..a4119ff793 100644 --- a/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc @@ -29,25 +29,37 @@ \title Defining Object Types through QML Documents \brief Description of how a QML document is a reusable type definition -One of the core features of QML is that it enables QML object types to be easily defined in a lightweight manner through QML documents to suit the needs of individual QML applications. The standard \l {Qt Quick} module provides various types like \l Rectangle, \l Text and \l Image for building a QML application; beyond these, you can easily define your own QML types to be reused within your application. This ability to create your own types forms the building blocks of any QML application. +One of the core features of QML is that it enables QML object types to be +easily defined in a lightweight manner through QML documents to suit the needs +of individual QML applications. The standard \l {Qt Quick} module provides +various types like \l Rectangle, \l Text and \l Image for building a QML +application; beyond these, you can easily define your own QML types to be +reused within your application. This ability to create your own types forms the +building blocks of any QML application. \section1 Defining an Object Type with a QML File \section2 Naming Custom QML Object Types -To create an object type, a QML document should be placed into a text file named as \e <TypeName>.qml where \e <TypeName> is the desired name of the type. The type name has the following requirements: +To create an object type, a QML document should be placed into a text file +named as \e <TypeName>.qml where \e <TypeName> is the desired name of the type. +The type name has the following requirements: \list \li It must be comprised of alphanumeric characters or underscores. \li It must begin with an uppercase letter. \endlist -This document is then automatically recognized by the engine as a definition of a QML type. Additionally, a type defined in this manner is automatically made available to other QML files within the same directory as the engine searches within the immediate directory when resolving QML type names. +This document is then automatically recognized by the engine as a definition of +a QML type. Additionally, a type defined in this manner is automatically made +available to other QML files within the same directory as the engine searches +within the immediate directory when resolving QML type names. \section2 Custom QML Type Definition -For example, below is a document that declares a \l Rectangle with a child \l MouseArea. The document has been saved to file named \c SquareButton.qml: +For example, below is a document that declares a \l Rectangle with a child \l +MouseArea. The document has been saved to file named \c SquareButton.qml: \qml // SquareButton.qml @@ -65,7 +77,10 @@ Rectangle { } \endqml -Since the file is named \c SquareButton.qml, \b {this can now be used as a type named \c SquareButton by any other QML file within the same directory}. For example, if there was a \c myapplication.qml file in the same directory, it could refer to the \c SquareButton type: +Since the file is named \c SquareButton.qml, \b {this can now be used as a type +named \c SquareButton by any other QML file within the same directory}. For +example, if there was a \c myapplication.qml file in the same directory, it +could refer to the \c SquareButton type: \qml // myapplication.qml @@ -76,23 +91,80 @@ SquareButton {} \image documents-definetypes-simple.png -This creates a 100 x 100 red \l Rectangle with an inner \l MouseArea, as defined in \c SquareButton.qml. When this \c myapplication.qml document is loaded by the engine, it loads the SquareButton.qml document as a component and instantiates it to create a \c SquareButton object. +This creates a 100 x 100 red \l Rectangle with an inner \l MouseArea, as +defined in \c SquareButton.qml. When this \c myapplication.qml document is +loaded by the engine, it loads the SquareButton.qml document as a component and +instantiates it to create a \c SquareButton object. + +The \c SquareButton type encapsulates the tree of QML objects declared in \c +SquareButton.qml. When the QML engine instantiates a \c SquareButton object +from this type, it is instantiating an object from the \l Rectangle tree +declared in \c SquareButton.qml. + +\note the letter case of the file name is significant on some (notably UNIX) +filesystems. It is recommended the file name case matches the case of the +desired QML type name exactly - for example, \c Box.qml and not \c BoX.qml - +regardless of the platform to which the QML type will be deployed. + +\section2 Inline Components + +Sometimes, it can be inconvenient to create a new file for a type, for +instance when reusing a small delegate in multiple views. If you don't actually +need to expose the type, but only need to create an instance, +\l{QtQml::Component}{Component} is an option. +But if you want to declare properties with the component types, or if you +want to use it in multiple files, \c Component is not an option. In that case, +you can use \e {inline components}. Inline components declare a new component +inside of a file. The syntax for that is +\code +component <component name> : BaseType { + // declare properties and bindings here +} +\endcode + +Inside the file which declares the inline component, the type can be referenced +simply by its name. + +\snippet qml/qml-documents/Images.qml document + +In other files, it has to be prefixed with the name of its containing component. + +\snippet qml/qml-documents/LabeledImageBox.qml document + +\note Inline components don't share their scope with the component they are +declared in. In the following example, when \c A.MyInlineComponent in file +B.qml gets created, a ReferenceError will occur, as \c root does not exist as +an id in B.qml. +It is therefore advisable not to reference objects in an inline component +which are not part of it. -The \c SquareButton type encapsulates the tree of QML objects declared in \c SquareButton.qml. When the QML engine instantiates a \c SquareButton object from this type, it is instantiating an object from the \l Rectangle tree declared in \c SquareButton.qml. +\snippet qml/qml-documents/A.qml document +\snippet qml/qml-documents/B.qml document -\note the letter case of the file name is significant on some (notably UNIX) filesystems. It is recommended the file name case matches the case of the desired QML type name exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the QML type will be deployed. +\note Inline components cannot be nested. \section2 Importing Types Defined Outside the Current Directory If \c SquareButton.qml was not in the same directory as \c myapplication.qml, -the \c SquareButton type would need to be specifically made available through an \e import statement in \c myapplication.qml. It could be imported from a relative path on the file system, or as an installed module; see \l {QML Modules}{module} for more details. +the \c SquareButton type would need to be specifically made available through +an \e import statement in \c myapplication.qml. It could be imported from a +relative path on the file system, or as an installed module; see \l {QML +Modules}{module} for more details. \section1 Accessible Attributes of Custom Types -The \b {root object} definition in a .qml file \b {defines the attributes that are available for a QML type}. All properties, signals and methods that belong to this root object - whether they are custom declared, or come from the QML type of the root object - are externally accessible and can be read and modified for objects of this type. +The \b {root object} definition in a .qml file \b {defines the attributes that +are available for a QML type}. All properties, signals and methods that belong +to this root object - whether they are custom declared, or come from the QML +type of the root object - are externally accessible and can be read and +modified for objects of this type. -For example, the root object type in the \c SquareButton.qml file above is \l Rectangle. This means any properties defined by the \l Rectangle type can be modified for a \c SquareButton object. The code below defines three \c SquareButton objects with customized values for some of the properties of the root \l Rectangle object of the \c SquareButton type: +For example, the root object type in the \c SquareButton.qml file above is \l +Rectangle. This means any properties defined by the \l Rectangle type can be +modified for a \c SquareButton object. The code below defines three \c +SquareButton objects with customized values for some of the properties of the +root \l Rectangle object of the \c SquareButton type: \qml // application.qml @@ -107,7 +179,12 @@ Column { \image documents-definetypes-attributes.png -The attributes that are accessible to objects of the custom QML type include any \l{Defining Property Attributes}{custom properties}, \l{Defining Method Attributes}{methods} and \l{Defining Signal Attributes}{signals} that have additionally been defined for an object. For example, suppose the \l Rectangle in \c SquareButton.qml had been defined as follows, with additional properties, methods and signals: +The attributes that are accessible to objects of the custom QML type include +any \l{Defining Property Attributes}{custom properties}, \l{Defining Method +Attributes}{methods} and \l{Defining Signal Attributes}{signals} that have +additionally been defined for an object. For example, suppose the \l Rectangle +in \c SquareButton.qml had been defined as follows, with additional properties, +methods and signals: \qml // SquareButton.qml @@ -136,7 +213,9 @@ Rectangle { } \endqml -Any \c SquareButton object could make use of the \c pressed property, \c buttonClicked signal and \c randomizeColor() method that have been added to the root \l Rectangle: +Any \c SquareButton object could make use of the \c pressed property, \c +buttonClicked signal and \c randomizeColor() method that have been added to the +root \l Rectangle: \qml // application.qml @@ -154,7 +233,14 @@ SquareButton { } \endqml -Note that any of the \c id values defined in \c SquareButton.qml are not accessible to \c SquareButton objects, as id values are only accessible from within the component scope in which a component is declared. The \c SquareButton object definition above cannot refer to \c mouseArea in order to refer to the \l MouseArea child, and if it had an \c id of \c root rather than \c squareButton, this would not conflict with the \c id of the same value for the root object defined in \c SquareButton.qml as the two would be declared within separate scopes. +Note that any of the \c id values defined in \c SquareButton.qml are not +accessible to \c SquareButton objects, as id values are only accessible from +within the component scope in which a component is declared. The \c +SquareButton object definition above cannot refer to \c mouseArea in order to +refer to the \l MouseArea child, and if it had an \c id of \c root rather than +\c squareButton, this would not conflict with the \c id of the same value for +the root object defined in \c SquareButton.qml as the two would be declared +within separate scopes. */ diff --git a/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc index 0faad43f4f..99c7fa5621 100644 --- a/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc @@ -422,7 +422,7 @@ import QtQuick.tooling 1.1 // Component objects. Module { // A Component object directly corresponds to a type exported - // in a plugin with a call to qmlRegisterType. + // using the QML_ELEMENT or QML_NAMED_ELEMENT macros. Component { // The name is a unique identifier used to refer to this type. @@ -440,25 +440,34 @@ Module { attachedType: "QQuickAnimationAttached" // The list of exports determines how a type can be imported. - // Each string has the format "URI/Name version" and matches the - // arguments to qmlRegisterType. Usually types are only exported - // once, if at all. - // If the "URI/" part of the string is missing that means the - // type should be put into the package defined by the URI the - // module was imported with. - // For example if this module was imported with 'import Foo 4.8' - // the Animation object would be found in the package Foo and - // QtQuick. + // Each string has the format "URI/Name version". The URI is + // the import name given via the build system, for example as + // QML_IMPORT_NAME in qmake. The name is either the C++ class + // name or, in case of QML_NAMED_ELEMENT(), an explicitly given + // name. The version is constructed from the major version + // given via the build system, as QML_IMPORT_MAJOR_VERSION in + // qmake, and any revisions given in the class or its base + // classes by Q_REVISION(), the REVISION argument to Q_PROPERTY, + // or QML_ADDED_IN_MINOR_VERSION(). Usually types are only + // exported once, if at all. The following tells us that there + // are two variants of Animation, and that 'import QtQuick 2.0' + // will expose a different revision than imports of later + // versions. exports: [ - "Animation 4.7", - "QtQuick/Animation 1.0" + "QtQuick/Animation 2.0", + "QtQuick/Animation 2.1" ] // The meta object revisions for the exports specified in 'exports'. - // Describes with revisioned properties will be visible in an export. - // The list must have exactly the same length as the 'exports' list. - // For example the 'animations' propery described below will only be - // available through the QtQuick/Animation 1.0 export. + // Each meta object revision may add additional properties or methods, + // relative to the previous one. Those will only be visible when the + // module is imported with at least the corresponding version as + // specified in the 'exports' list. + // The exportMetaObjectRevisions list must have exactly the same + // length as the 'exports' list. For example, the 'animations' property + // described below will only be available through the QtQuick/Animation + // 2.1 export. Usually the revisions will match the versions in the + // 'exports' list. exportMetaObjectRevisions: [0, 1] Property { @@ -479,17 +488,14 @@ Module { Enum { name: "Loops" - values: { - "Infinite": -2, - "OnceOnly": 1 - } + values: [ "Infinite", "OnceOnly" ] } // Signal and Method work the same way. The inner Parameter // declarations also support the isReadonly, isPointer and isList // attributes which mean the same as for Property Method { name: "restart" } - Signal { name: "started"; revision: 2 } + Signal { name: "started"; revision: 1 } Signal { name: "runningChanged" Parameter { type: "bool" } diff --git a/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc index 01e81e7c19..496245820a 100644 --- a/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc +++ b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc @@ -1,19 +1,22 @@ -QQmlExtensionPlugin is a plugin interface that makes it possible to +\l QQmlEngineExtensionPlugin is a plugin interface that makes it possible to create QML extensions that can be loaded dynamically into QML applications. These extensions allow custom QML types to be made available to the QML engine. To write a QML extension plugin: \list 1 -\li Subclass QQmlExtensionPlugin +\li Subclass \l QQmlEngineExtensionPlugin and use the Q_PLUGIN_METADATA() macro + to register the plugin with the Qt meta object system. +\li Use the \l QML_ELEMENT and \l QML_NAMED_ELEMENT() macros to declare + QML types. +\li Write a project file for the plugin. Add: \list - \li Use the Q_PLUGIN_METADATA() macro to register the plugin with - the Qt meta object system - \li Override the \l{QQmlExtensionPlugin::}{registerTypes()} method - and call qmlRegisterType() to register the types to be exported - by the plugin + \li \c {CONFIG += qmltypes} to instruct the build system to generate + QML types. + \li \c {QML_IMPORT_NAME = <my.import.name>} to specify the import name. + \li \c {QML_IMPORT_MAJOR_VERSION = <version>} to specify the import + major version. \endlist -\li Write a project file for the plugin \li Create a \l{Module Definition qmldir Files}{qmldir file} to describe the plugin \endlist @@ -27,26 +30,18 @@ issues in the library user's code. Suppose there is a new \c TimeModel C++ class that should be made available as a new QML type. It provides the current time through \c hour and \c minute -properties. +properties. It declares a QML type called \c Time via \l QML_NAMED_ELEMENT(). -\snippet qmlextensionplugins/plugin.cpp 0 +\snippet qmlextensionplugins/timemodel.h 0 \dots To make this type available, we create a plugin class named \c QExampleQmlPlugin -which is a subclass of \l QQmlExtensionPlugin. It overrides the -\l{QQmlExtensionPlugin::}{registerTypes()} method in order to register the \c TimeModel -type using qmlRegisterType(). It also uses the Q_PLUGIN_METADATA() macro in the class -definition to register the plugin with the Qt meta object system using a unique -identifier for the plugin. +which is a subclass of \l QQmlEngineExtensionPlugin. It uses the +Q_PLUGIN_METADATA() macro in the class definition to register the plugin with the +Qt meta object system using a unique identifier for the plugin. \snippet qmlextensionplugins/plugin.cpp plugin -This registers the \c TimeModel class with version \c{1.0} of this plugin library, as -a QML type called \c Time. The Q_ASSERT() macro can ensure the type namespace is -imported correctly by any QML components that use this plugin. The -\l{Defining QML Types from C++} article has more information about registering C++ -types into the runtime. - \section1 Project settings for the plugin Additionally, the project file (\c .pro) defines the project as a plugin library, @@ -55,14 +50,22 @@ the plugin target name and various other details: \code TEMPLATE = lib -CONFIG += qt plugin +CONFIG += qt plugin qmltypes QT += qml -DESTDIR = imports/TimeExample -TARGET = qmlqtimeexampleplugin +QML_IMPORT_NAME = TimeExample +QML_IMPORT_MAJOR_VERSION = 1 + +DESTDIR = imports/$$QML_IMPORT_NAME +TARGET = qmlqtimeexampleplugin + SOURCES += qexampleqmlplugin.cpp \endcode +This registers the \c TimeModel class with the import \c{TimeExample 1.0}, as +a QML type called \c Time. The \l{Defining QML Types from C++} article has more +information about registering C++ types for usage in QML. + \section1 Plugin definition in the qmldir Finally, a \l{Module Definition qmldir Files}{qmldir file} is required diff --git a/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc b/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc index 57e0ba1a14..fdba452271 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc @@ -127,15 +127,15 @@ Rectangle { In this case, the engine will emit an error and refuse to load the file. -\section4 Non-module Namespace Imports +\section4 C++ Module Imports -Types can also be registered into namespaces directly via the various -registration functions in C++ (such as qmlRegisterType()). The types which -have been registered into a namespace in this way may be imported by importing -the namespace, as if the namespace was a module identifier. +Usually, C++ types are declared using the QML_ELEMENT and QML_NAMED_ELEMENT() +macros and registered via the build system using QML_IMPORT_NAME and +QML_IMPORT_MAJOR_VERSION. The import name and version given this way form a +module that can be imported to access the types. This is most common in client applications which define their own QML object -types in C++ and register them with the QML type system manually. +types in C++. \section4 Importing into a Qualified Local Namespace @@ -299,6 +299,13 @@ Additional import paths can be added through QQmlEngine::addImportPath() or the \l{Prototyping with qmlscene}{qmlscene} tool, you can also use the \c -I option to add an import path. +You can specify multiple import paths in the \c QML2_IMPORT_PATH environment +variable by joining them using the path separator. On Windows the path separator +is a semicolon (;), on other platforms it is a colon (:). This means that you +cannot specify resource paths or URLs in QML2_IMPORT_PATH, as they contain +colons themselves. However, you can add resource paths and URLs by calling +QQmlEngine::addImportPath() programatically. + \section1 Debugging diff --git a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc index 401e099ebf..ecfef2e04f 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc @@ -112,7 +112,7 @@ Alternatively, a custom property of an object type may be defined in an object declaration in a QML document with the following syntax: \code - [default] property <propertyType> <propertyName> + [default] [required] [readonly] property <propertyType> <propertyName> \endcode In this way an object declaration may \l {Defining Object Types from QML} @@ -121,10 +121,13 @@ state more easily. Property names must begin with a lower case letter and can only contain letters, numbers and underscores. \l {JavaScript Reserved Words} -{JavaScript reserved words} are not valid property names. The \c default -keyword is optional, and modifies the semantics of the property being declared. -See the upcoming section on \l {Default Properties}{default properties} for -more information about the \c default property modifier. +{JavaScript reserved words} are not valid property names. The \c default, +\c required, and \c readonly keywords are optional, and modify the semantics +of the property being declared. +See the upcoming sections on \l {Default Properties}{default properties}, +\l {Required Properties}{required properties} and, +\l {Read-Only Properties}{read-only properties} for more information +about their respective meaning. Declaring a custom property implicitly creates a value-change \l{Signal attributes}{signal} for that property, as well as an associated @@ -647,6 +650,45 @@ the \l{TabWidget Example}, which uses a default property to automatically reassign children of the TabWidget as children of an inner ListView. See also \l {Extending QML}. +\section3 Required Properties + +An object declaration may define a property as required, using the \c required +keyword. The syntax is +\code + required property <propertyType> <propertyName> +\endcode + +As the name suggests, required properties must be set when an instance of the object +is created. Violation of this rule will result in QML applications not starting if it can be +detected statically. In case of dynamically instantiated QML components (for instance via +\l {QtQml::Qt::createComponent()}{Qt.createComponent()}), violating this rule results in a +warning and a null return value. + +It's possible to make an existing property required with +\code + required <propertyName> +\endcode +The following example shows how to create a custom Rectangle component, in which the color +property always needs to be specified. +\qml +// ColorRectangle.qml +Rectangle { + required color +} +\endqml + +\note You can't assign an initial value to a required property from QML, as that would go +directly against the intended usage of required properties. + +Required properties play a special role in model-view-delegate code: +If the delegate of a view has required properties whose names match with +the role names of the view's model, then those properties will be initialized +with the model's corresponding values. +For more information, visit the \l{Models and Views in Qt Quick} page. + +\sa {QQmlComponent::createWithInitialProperties}, {QQmlApplicationEngine::setInitialProperties} +and {QQuickView::setInitialProperties} for ways to initialize required properties from C++. + \section3 Read-Only Properties An object declaration may define a read-only property using the \c readonly diff --git a/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc index 5144fe219e..53984a440d 100644 --- a/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc @@ -582,34 +582,15 @@ property is only invoked when the property is reassigned to a different object v QML objects (and certainly not JavaScript object either) and the key-value pairs in \c attributes are \e not QML properties. Rather, the \c items property holds an array of values, and \c attributes holds a set of key-value - pairs. Since they are stored as a set of values, instead of as an object, - their contents \e cannot be modified individually: - - \qml - Item { - property variant items: [1, 2, 3, "four", "five"] - property variant attributes: { 'color': 'red', 'width': 100 } - - Component.onCompleted: { - items[0] = 10 - console.log(items[0]) // This will still be '1'! - attributes.color = 'blue' - console.log(attributes.color) // This will still be 'red'! - } - } - \endqml - - Since it is not possible to individually add or remove items from a list or - object stored in a \c variant, the only way to modify its contents is to - reassign a new value. However, this is not efficient, as it causes the value - to be serialized and deserialized. + pairs. Additionally, since \c items and \c attributes are not QML objects, changing - their individual values do not trigger property change notifications. If - the above example had \c onNumberChanged or \c onAnimalChanged signal - handlers, they would not have been called. If, however, the \c items or - \c attributes properties themselves were reassigned to different values, then - such handlers would be called. + the values they contain does not trigger property change notifications. If + the above example had \c onItemsChanged or \c onAttributesChanged signal + handlers, they would not be called when assigning individual entries in + either property. If, however, the \c items or \c attributes properties + themselves were reassigned to different values, then such handlers would be + called. JavaScript programmers should also note that when a JavaScript object is copied to an array or map property, the \e contents of the object (that is, |