src/qml/doc/src/documents/topic.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27 /*!
  28 \page qtqml-documents-topic.html
  29 \title QML Documents
  30 \brief Description of QML documents
  31
  32 A QML document is a string which conforms to QML document syntax.  A document
  33 defines a QML object type.  A document is generally loaded from a \c ".qml"
  34 file stored either locally or remotely, but can be constructed manually in
  35 code.  An instance of the object type defined by a document may be created
  36 using a \l Component in QML code, or a \l QQmlComponent in C++.
  37 Alternatively, if the object type is explicitly exposed to the QML type system
  38 with a particular type name, the type may be used directly in object
  39 declarations in other documents.
  40
  41 The ability to define re-usable QML object types in documents is an important
  42 enabler to allow clients to write modular, highly readable and maintainable
  43 code.
  44
  45 \section1 Structure of a QML Document
  46
  47 A QML document consists of two sections: the imports section, and the object
  48 declaration section.  The imports section in a document contains import
  49 statements that define which QML object types and JavaScript resources the
  50 document is able to use.  The object declaration section defines the object
  51 tree to be created when instantiating the object type defined by the document.
  52
  53 An example of a simple document is as follows:
  54
  55 \qml
  56 import QtQuick 2.0
  57
  58 Rectangle {
  59     width: 300
  60     height: 200
  61     color: "blue"
  62 }
  63 \endqml
  64
  65 See the \l {qtqml-documents-structure.html}{Structure of a QML Document}
  66 for more information on the topic.
  67
  68 \section2 Syntax of the QML Language
  69
  70 The object declaration section of the document must specify a valid object
  71 hierarchy with appropriate \l {qtqml-syntax-basics.html}{QML syntax}.  An
  72 object declaration may include the specification of custom
  73 \l{qtqml-syntax-objectattributes.html}{object attributes}.  Object method
  74 attributes may be specified as JavaScript functions, and object property
  75 attributes may be assigned \l{qtqml-syntax-propertybinding.html}
  76 {property binding expressions}.
  77
  78 Please see the documentation about the \l{qtqml-syntax-basics.html}
  79 {syntax of QML} for more information about valid syntax, and see the
  80 documentation about \l{qtqml-javascript-topic.html}
  81 {integrating QML and JavaScript} for in-depth information on that topic.
  82
  83 \section1 Defining Object Types through QML Documents
  84
  85 As described briefly in the previous section, a document implicitly defines
  86 a QML object type.  One of the core principles of QML is the ability to define
  87 and then re-use object types.  This improves the maintainability of QML code,
  88 increases the readability of object hierarchy declarations, and promotes
  89 separation between UI definition and logic implementation.
  90
  91 In the following example, the client developer defines a \c Button type with
  92 a document in a file:
  93
  94 \snippet qml/qml-extending-types/components/Button.qml 0
  95
  96 The \c Button type can then be used in an application:
  97
  98 \table
  99 \row
 100 \li \snippet qml/qml-extending-types/components/application.qml 0
 101 \li \image qml-extending-types.png
 102 \endtable
 103
 104 Please see the documentation about \l{qtqml-documents-definetypes.html}
 105 {defining object types in documents} for in-depth information on the
 106 topic.
 107
 108 \section1 Resource Loading and Network Transparency
 109
 110 It is important to note that QML is network-transparent.  Applications can
 111 import documents from remote paths just as simply as documents from local
 112 paths.  In fact, any \c url property may be assigned a remote or local URL,
 113 and the QML engine will handle any network communication involved.
 114
 115 Please see the \l{qtqml-documents-networktransparency.html}
 116 {Network Transparency} documentation for more information about network
 117 transparency in imports.
 118
 119 \section1 Scope and Naming Resolution
 120
 121 Expressions in documents usually involve objects or properties of objects,
 122 and since multiple objects may be defined and since different objects may have
 123 properties with the same name, some predefined symbol resolution semantics must
 124 be defined by QML.  Please see the page on \l{qtqml-documents-scope.html}
 125 {scope and symbol resolution} for in-depth information about the topic.
 126
 127 */