calling functions in a third-party C++ library)
\li To access functionality in the QtQml or QtQuick modules (for example, to dynamically generate
images using QQuickImageProvider)
-\li To write your own QML elements (whether for your applications, or for distribution to others)
+\li To write your own QML object types (whether for your applications, or for distribution to others)
\endlist
-
There are a number of ways to extend your QML application through C++. For example, you could:
\list
\li Load a QML component and manipulate it (or its children) from C++
\li Embed a C++ object and its properties directly into a QML component (for example, to make a
particular C++ object callable from QML, or to replace a dummy list model with a real data set)
-\li Define new QML elements (through QObject-based C++ classes) and create them directly from your
+\li Define new QML object types (through QObject-based C++ classes) and create them directly from your
QML code
\endlist
-
\section1 Exposing C++ Types To QML
QML types may be implemented in C++ and then exposed to the QML type system via
\title QML Documents
\brief Description of QML documents
+A QML document is a string which conforms to QML document syntax. A document
+defines a QML object type. A document is generally loaded from a \c ".qml"
+file stored either locally or remotely, but can be constructed manually in
+code. An instance of the object type defined by a document may be created
+using a \l Component in QML code, or a \l QQmlComponent in C++.
+Alternatively, if the object type is explicitly exposed to the QML type system
+with a particular type name, the type may be used directly in object
+declarations in other documents.
+
+The ability to define re-usable QML object types in documents is an important
+enabler to allow clients to write modular, highly readable and maintainable
+code.
+
\section1 Structure Of A QML Document
-A QML document consists of two parts: its imports, and its object
-hierarchy definition. See the \l {qtqml-documents-structure.html}{Structure of a QML Document}
-for more information.
+A QML document consists of two sections: the imports section, and the object
+declaration section. The imports section in a document contains import
+statements that define which QML object types and JavaScript resources the
+document is able to use. The object declaration section defines the object
+tree to be created when instantiating the object type defined by the document.
+
+An example of a simple document is as follows:
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+ width: 300
+ height: 200
+ color: "blue"
+}
+\endqml
+
+See the \l {qtqml-documents-structure.html}{Structure of a QML Document}
+for more information on the topic.
+
+\section2 Syntax of the QML Language
+The object declaration section of the document must specify a valid object
+hierarchy with appropriate \l {qtqml-syntax-basics.html}{QML syntax}. An
+object declaration may include the specification of custom
+\l{qtqml-syntax-objectattributes.html}{object attributes}. Object method
+attributes may be specified as JavaScript functions, and object property
+attributes may be assigned \l{qtqml-syntax-propertybinding.html}
+{property binding expressions}.
-\section1 Documents as QML object type definitions
+Please see the documentation about the \l{qtqml-syntax-basics.html}
+{syntax of QML} for more information about valid syntax, and see the
+documentation about \l{qtqml-javascript-topic.html}
+{integrating QML and JavaScript} for in-depth information on that topic.
-Any QML document can also define a QML object type.
+\section1 Defining Object Types through QML Documents
+As described briefly in the previous section, a document implicitly defines
+a QML object type. One of the core principles of QML is the ability to define
+and then re-use object types. This improves the maintainability of QML code,
+increases the readability of object hierarchy declarations, and promotes
+separation between UI definition and logic implementation.
-\section2 Defining a component with a .qml file
+In the following example, the client developer defines a \c Button type with
+a document in a file:
+\snippet qml/qml-extending-types/components/Button.qml 0
-\section2 Attributes exposed by components
+The \c Button type can then be used in an application:
+\table
+\row
+\li \snippet qml/qml-extending-types/components/application.qml 0
+\li \image qml-extending-types.png
+\endtable
+Please see the documentation about \l{qtqml-documents-definetypes.html}
+{defining object types in documents} for in-depth information on the
+topic.
-\section1 Network Transparency
+\section1 Resource Loading and Network Transparency
-It is important to note that QML is network-transparent.
-Applications can import documents from remote paths just as
-simply as documents from local paths.
+It is important to note that QML is network-transparent. Applications can
+import documents from remote paths just as simply as documents from local
+paths. In fact, any \c url property may be assigned a remote or local URL,
+and the QML engine will handle any network communication involved.
Please see the \l{qtqml-documents-networktransparency.html}
{Network Transparency} documentation for more information about network
\section1 Scope and Naming Resolution
+Expressions in documents usually involve objects or properties of objects,
+and since multiple objects may be defined and since different objects may have
+properties with the same name, some predefined symbol resolution semantics must
+be defined by QML. Please see the page on \l{qtqml-documents-scope.html}
+{scope and symbol resolution} for in-depth information about the topic.
*/
A module may contain QML, JavaScript and/or C++ files. To access the types and functionality within
a module, the module must be imported with an \l{Import Statements}{import} statement.
-
\section1 Located Modules
A located module is one that is imported by a quoted URL string that refers to the
See \l{qtqml-modules-qmldir.html}{Adding Module Metadata with a qmldir File} for more information.
-
\section1 Providing Types And Functionality In A C++ Plugin
An application which has a lot of logic implemented in C++, or which defines
language, and it also provides some elementary QML types which provide the
basis for further extensions to the QML language.
-
-
The Qt QML module also provides the \c QtObject and \c Component types which
may be used in QML documents, by default. These types are non-visual and
provide building-blocks for extensions to QML.
-
-
\section1 The QtQml Import
The types provided by the Qt QML module are only available in a QML document
if that document imports the QtQml namespace (or if the document imports the
-QtQuick namespace, as noted below).
+\c QtQuick namespace, as noted below).
The current version of the import provided by the Qt QML module is version 2.0,
and thus it may be imported via the following statement:
-\tt{import QtQml 2.0}
+\qml
+import QtQml 2.0
+\endqml
-Most clients will never need to use the QtQml import, as all of the types and
-functionality provided by the QtQml namespace are also provided by the QtQuick
-namespace which may be imported as follows:
+Most clients will never need to use the \c QtQml import, as all of the types
+and functionality provided by the \c QtQml namespace are also provided by the
+\c QtQuick namespace which may be imported as follows:
-\tt{import QtQuick 2.0}
+\qml
+import QtQuick 2.0
+\endqml
-See the \l{Qt Quick} module documentation for more information about the
-QtQuick namespace and what it provides to QML application developers.
+See the \l{QtQuick}{Qt Quick} module documentation for more information about the
+\c QtQuick namespace and what it provides to QML application developers.
The documentation for the types below applies equally to the types of the same
-name provided by the Qt Quick module, as they are in fact identical.
+name provided by the \l{QtQuick}{Qt Quick} module, as they are in fact identical.
\section1 QtObject
\c id and it has a default property which is the object type to instantiate,
but no other properties may be added to it.
-For example, the following QtObject has two different Component properties,
-and it uses those components to dynamically construct objects at run-time:
+For example, the following QtObject has two different \l Component
+properties, and it uses those components to dynamically construct objects at
+run-time:
\code
import QtQuick 2.0
\li \l{qtqml-typesystem-topic.html}{The QML Type System}
\list
- \li \l{qtqml-typesystem-topic.html}{Basic Types}
+ \li \l{qtqml-typesystem-basictypes.html}{Basic Types}
\li \l{qtqml-typesystem-topic.html#javascript-types}{JavaScript Types}
- \li \l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Types}
+ \li \l{qtqml-typesystem-objecttypes.html}{QML Object Types}
\list
\li \l{qtqml-documents-definetypes.html}{Defining Object Types from QML}
\li \l{qtqml-cppintegration-registercpptypes.html}{Defining Object Types from C++}
**
****************************************************************************/
/*!
-\page qtqml-basictypes.html
+\page qtqml-typesystem-basictypes.html
\title QML Basic Types
\brief Description of basic types provided by the Qt QML module
A QML object type is a type from which a QML object can be instantiated.
-In syntactic terms, a QML object type is one which can be used to declare an object by specifying the \e{type name} followed by a set of curly braces that encompasses the attributes of that object. This differs from \e {basic types}, which cannot be used in the same way. For example, \l Rectangle is a QML object type: it can be used to create \c Rectangle type objects. This cannot be done with primitive types such as \c int and \c bool, which are used to hold simple data types rather than objects.
-
-Custom QML object types can be defined by creating a .qml file that defines the type, as discussed in \l {qtqml-documents-definetypes.html}{Documents as QML object type definitions}, or by defining a QML type from C++ and registering the type with the QML engine, as discussed in \l{qtqml-registercpptypes.html}
-{Registering C++ Types With The QML Type System}.
+In syntactic terms, a QML object type is one which can be used to declare an
+object by specifying the \e{type name} followed by a set of curly braces that
+encompasses the attributes of that object. This differs from \e {basic types},
+which cannot be used in the same way. For example, \l Rectangle is a QML object
+type: it can be used to create \c Rectangle type objects. This cannot be done
+with primitive types such as \c int and \c bool, which are used to hold simple
+data types rather than objects.
+
+Custom QML object types can be defined by creating a .qml file that defines the
+type, as discussed in \l {qtqml-documents-definetypes.html}
+{Documents as QML object type definitions}, or by defining a QML type from C++
+and registering the type with the QML engine, as discussed in
+\l{qtqml-registercpptypes.html}{Registering C++ Types With The QML Type System}.
\section1 Creating Object Types from QML
\brief Description of the QML type system
The types which may be used in the definition of an object hierarchy in a QML
-document can come from various sources.
+document can come from various sources. They may be:
\list
-\li They may be provided natively by the QML language
-\li They may be registered by C++ plugins for QML
-\li They may be provided as QML documents by a plugin developer
+\li provided natively by the QML language
+\li registered via C++ by QML modules
+\li provided as QML documents by QML modules
\endlist
Furthermore, application developers can provide their own types, either by
\section1 Basic Types
-The Qt QML module provides support for various primitive types including
+The QML language has built-in support for various primitive types including
integers, double-precision floating point numbers, strings, and boolean values.
Objects may have properties of these types, and values of these types may be
passed as arguments to methods of objects.
-See the \l{qtqml-basictypes.html}{Basic Types} documentation for more
-information about basic types, or the \l{qtqml-documents-properties.html}
+See the \l{qtqml-typesystem-basictypes.html}{Basic Types} documentation for
+more information about basic types, or the \l{qtqml-documents-properties.html}
{QML Documents - Object Properties} documentation for more information about
other available property types.
\section1 JavaScript types
-JavaScript objects and arrays are supported by the QML engine. Any standard JavaScript type can be created and stored using the generic \l var type.
+JavaScript objects and arrays are supported by the QML engine. Any standard
+JavaScript type can be created and stored using the generic \l var type.
For example, the standard \c Date and \c Array types are available, as below:
\section1 QML Object Types
-A QML object type is a type from which a QML object can be instantiated.
-
-
+A QML object type is a type from which a QML object can be instantiated. QML
+object types are derived from \l QtObject, and are provided by QML modules.
+Applications can import these modules to use the object types they provide.
+The \c QtQuick module provides the most common object types needed to create
+user interfaces in QML.
+Finally, every QML document implicitly defines a QML object type, which can be
+re-used in other QML documents. See the documentation about
+\l{qtqml-typesystem-objecttypes.html}{object types in the QML type system} for
+in-depth information about object types.
*/
\l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Type}.
The QML language provides a number of built in
- (\l{qtqml-basictypes.html}{basic types}), and the QtQuick module
- provides various \l{qtquick-qmltypereference.html}{Qt Quick types}
- for building QML applications. Types can also be provided by
- third-party developers through (\l{qtqml-modules-topic.html}{modules})
- or by the application developer in the application itself
- \l{qtqml-documents-definetypes.html}{through QML Documents}.
+ (\l{qtqml-typesystem-basictypes.html}{basic types}), and the
+ QtQuick module provides various \l{qtquick-qmltypereference.html}
+ {Qt Quick types} for building QML applications. Types can also be
+ provided by third-party developers through
+ (\l{qtqml-modules-topic.html}{modules}) or by the application
+ developer in the application itself through
+ \l{qtqml-documents-definetypes.html}{QML Documents}.
See \l{qtqml-typesystem-topic.html}{The QML Type System}
for more details.
projects / platform / upstream / qtdeclarative.git / commitdiff