\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.
*/
projects / profile / ivi / qtdeclarative.git / blobdiff