doc/src/qml/qmldocument.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 /*!
  29 \page qml-documents.html
  30 \title QML Documents
  31 \brief a description of QML documents and the kind of content they contain
  32
  33 A QML document is a block of QML source code.  QML documents generally correspond to files
  34 stored on a disk or at a location on a network, but they can also be constructed directly
  35 from text data.
  36
  37 Here is a simple QML document:
  38
  39 \snippet doc/src/snippets/qml/qml-documents/non-trivial.qml document
  40
  41 QML documents are always encoded in UTF-8 format.
  42
  43 A QML document always begins with one or more import statements.  To prevent elements
  44 introduced in later versions from affecting existing QML programs, the element types
  45 available within a document are controlled by the imported QML \l {Modules} with
  46 a corresponding \i version.
  47
  48 QML does \i not have a preprocessor that modifies the document prior to
  49 presentation to the \l{The QML Engine}{QML engine}, unlike C or C++.
  50 The \c import statements do not copy and prepend the code in the document, but
  51 instead instruct the QML engine on how to resolve type references found
  52 in the document. Any type reference present in a QML document - such as \c
  53 Rectangle and \c ListView - including those made within an \l {Inline
  54 JavaScript}{JavaScript block} or \l {Property Binding in QML}{property
  55 bindings}, are \i resolved based exclusively on the import statements. At least
  56 one \c import statement must be present such as \c{import QtQuick 2.0}.
  57
  58 Each \c id value in a QML document must be unique within that document. They do
  59 not need to be unique across different documents as id values are resolved
  60 according to the document scope.
  61
  62 \section1 Documents as Component Definitions
  63
  64 A QML document defines a single, top-level \l {QML Components}{QML component}. A
  65 QML component is a template that is interpreted by the QML engine to
  66 create an object with some predefined behaviour. As it is a template, a single
  67 QML component can be "run" multiple times to produce several objects, each of
  68 which are said to be \i instances of the component.
  69
  70 Once created, instances are not dependent on the component that created them, so
  71 they can operate on independent data. Here is an example of a simple "Button"
  72 component (defined in a \c Button.qml file) that is instantiated four times by
  73 \c application.qml. Each instance is created with a different value for its \c
  74 text property:
  75
  76 \table
  77 \row
  78 \o Button.qml
  79 \o application.qml
  80
  81 \row
  82 \o \snippet doc/src/snippets/qml/qml-documents/qmldocuments.qml document
  83 \o
  84 \qml
  85 import QtQuick 2.0
  86
  87 Column {
  88     spacing: 10
  89
  90     Button { text: "Apple" }
  91     Button { text: "Orange" }
  92     Button { text: "Pear" }
  93     Button { text: "Grape" }
  94 }
  95 \endqml
  96
  97 \image anatomy-component.png
  98
  99 \endtable
 100
 101 Any snippet of QML code can become a component, just by placing it in the file
 102 "<Name>.qml" where <Name> is the component name, and begins with an \bold
 103 uppercase letter. Note that the case of all characters in the <Name> are
 104 significant on some filesystems, notably UNIX filesystems. It is recommended
 105 that the case of the filename matches the case of the component name in QML
 106 exactly, regardless of the platform the QML will be deployed to. These QML
 107 component files automatically become available as new QML element types to other
 108 QML components and applications in the same directory.
 109
 110 The \l{QML Components} article details the creation of components and how to
 111 load them in other components.
 112
 113 \section1 Inline Components
 114
 115 In addition to the top-level component that all QML documents define, and any
 116 reusable components placed in separate files, documents may also include \i
 117 inline components. Inline components are declared using the \l Component
 118 element, as can be seen in the first example above. Inline components share all
 119 the characteristics of regular top-level components and use the same \c import
 120 list as their containing QML document. Components are one of the most basic
 121 building blocks in QML, and are frequently used as "factories" by other
 122 elements. For example, the \l ListView element uses the \c delegate component as
 123 the template for instantiating list items - each list item is just a new
 124 instance of the component with the item specific data set appropriately.
 125
 126 Like other \l {QML Elements}, the \l Component element is an object and must be
 127 assigned to a property. \l Component objects may also have an object id. In the
 128 first example on this page, the inline component is added to the \l Rectangle's
 129 \c resources list, and then \l {Property Binding} is used to assign the \l
 130 Component to the \l ListView's \c delegate property. The QML language even
 131 contains a syntactic optimization when assigning directly to a component
 132 property for this case where it will automatically insert the \l Component tag.
 133 This means that by enclosing components in a \c Component element, we can
 134 assign an id to the component and use the component elsewhere
 135
 136 These final two examples perform identically to the original document.
 137
 138 \table
 139 \row
 140 \o
 141 \snippet doc/src/snippets/qml/qml-documents/inline-component.qml document
 142 \o
 143 \snippet doc/src/snippets/qml/qml-documents/inline-text-component.qml document
 144 \endtable
 145
 146
 147 For information about components, the \l{QML Components} article details the
 148 creation of components and how to load them in other components.
 149
 150 \sa QQmlComponent
 151 */