doc/src/declarative/qdeclarativedocument.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Free Documentation License
  17 ** Alternatively, this file may be used under the terms of the GNU Free
  18 ** Documentation License version 1.3 as published by the Free Software
  19 ** Foundation and appearing in the file included in the packaging of this
  20 ** file.
  21 **
  22 ** If you have questions regarding the use of this file, please contact
  23 ** Nokia at qt-info@nokia.com.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qdeclarativedocuments.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/declarative/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}.  That is,
  46 QML is a \e versioned language.
  47
  48 Syntactically a QML document is self contained; QML does \e not have a preprocessor that
  49 modifies the document prior to presentation to the QML runtime. \c import statements
  50 do not "include" code in the document, but instead instruct the QML runtime on how to
  51 resolve type references found in the document.  Any type reference present in a QML
  52 document - such as \c Rectangle and \c ListView - including those made within an
  53 \l {Inline JavaScript}{JavaScript block} or \l {Property Binding}s, are \e resolved based exclusively on the
  54 import statements.  QML does not import any modules by default, so at least one \c import
  55 statement must be present or no elements will be available!
  56
  57 Each \c id value in a QML document must be unique within that document. They
  58 do not need to be unique across different documents as id values are
  59 resolved according to the document scope.
  60
  61
  62 \section1 Documents as Component Definitions
  63
  64 A QML document defines a single, top-level \l {QDeclarativeComponent}{QML component}.  A QML component
  65 is a template that is interpreted by the QML runtime to create an object with some predefined
  66 behaviour.  As it is a template, a single QML component can be "run" multiple times to
  67 produce several objects, each of which are said to be \e instances of the component.
  68
  69 Once created, instances are not dependent on the component that created them, so they can
  70 operate on independent data.  Here is an example of a simple "Button" component (defined
  71 in a \c Button.qml file) that is instantiated four times by \c application.qml.
  72 Each instance is created with a different value for its \c text property:
  73
  74 \table
  75 \row
  76 \o Button.qml
  77 \o application.qml
  78
  79 \row
  80 \o \snippet doc/src/snippets/declarative/qml-documents/qmldocuments.qml document
  81 \o
  82 \qml
  83 import QtQuick 1.0
  84
  85 Column {
  86     spacing: 10
  87
  88     Button { text: "Apple" }
  89     Button { text: "Orange" }
  90     Button { text: "Pear" }
  91     Button { text: "Grape" }
  92 }
  93 \endqml
  94
  95 \image anatomy-component.png
  96
  97 \endtable
  98
  99 Any snippet of QML code can become a component, just by placing it in the file "<Name>.qml"
 100 where <Name> is the new element name, and begins with an \bold uppercase letter.  Note that
 101 the case of all characters in the <Name> are significant on some filesystems, notably
 102 UNIX filesystems.  It is recommended that the case of the filename matches the case of
 103 the component name in QML exactly, regardless of the platform the QML will be deployed to.
 104
 105 These QML component files automatically become available as new QML element types
 106 to other QML components and applications in the same directory.
 107
 108
 109
 110 \section1 Inline Components
 111
 112 In addition to the top-level component that all QML documents define, and any reusable
 113 components placed in separate files, documents may also
 114 include \e inline components.  Inline components are declared using the
 115 \l Component element, as can be seen in the first example above.  Inline components share
 116 all the characteristics of regular top-level components and use the same \c import list as their
 117 containing QML document.  Components are one of the most basic building blocks in QML, and are
 118 frequently used as "factories" by other elements.  For example, the \l ListView element uses the
 119 \c delegate component as the template for instantiating list items - each list item is just a
 120 new instance of the component with the item specific data set appropriately.
 121
 122 Like other \l {QML Elements}, the \l Component element is an object and must be assigned to a
 123 property.   \l Component objects may also have an object id.  In the first example on this page,
 124 the inline component is added to the \l Rectangle's \c resources list, and then
 125 \l {Property Binding} is used to assign the \l Component to the \l ListView's \c delegate
 126 property.  While using property binding allows the \l Component object to be shared (for example,
 127 if the QML document contained multiple \l ListView's with the same delegate), in this case the
 128 \l Component could have been assigned directly to the \l ListView's \c delegate.  The QML
 129 language even contains a syntactic optimization when assigning directly to a component property
 130 for this case where it will automatically insert the \l Component tag.
 131
 132 These final two examples are behaviorally identical to the original document.
 133
 134 \table
 135 \row
 136 \o
 137 \snippet doc/src/snippets/declarative/qml-documents/inline-component.qml document
 138 \o
 139 \snippet doc/src/snippets/declarative/qml-documents/inline-text-component.qml document
 140 \endtable
 141
 142 \sa QDeclarativeComponent
 143 */