doc/src/qml/qmlcomponents.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-components.html
  30 \ingroup qml-features
  31 \contentspage QML Reference
  32
  33 \title QML Components
  34 \brief creating and instantiating components
  35
  36 A \i component is an instantiable QML definition, typically contained in a \c
  37 .qml file. For instance, a Button \i component may be defined in \c Button.qml
  38 file. The \l{The QML Engine}{QML engine} may instantiate this Button
  39 component to create Button \i objects. Alternatively, a component may be defined
  40 inside a \l Component element.
  41
  42 Moreover, the Button definition may also contain other components. A Button
  43 component might have a Text element for its label and other components to
  44 implement its functions. Compounding components to form new components
  45 is the emphasis in QML.
  46
  47 \keyword qml-define-components
  48 \section1 Defining New Components
  49
  50 Any snippet of QML code may become a component, by placing the code in a QML
  51 file, whose file extension is \c .qml). A complete Button component that
  52 responds to user input may be in a Button.qml file.
  53 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml document
  54
  55 The component name, \c Button, matches the QML filename, \c Button.qml.
  56 Also, the first character is in upper case. Matching the names allow
  57 components in the same directory to be in the direct import path of the
  58 application. The section on \l{Importing a Component} has information about
  59 naming components with different filenames.
  60
  61 Alternatively, a \l Component element may encapsulate a QML object to form a
  62 component.
  63 \snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent begin
  64 \snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component
  65 \snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent end
  66
  67
  68 Components may incorporate any \l{Qt Quick}{QML feature} such as:
  69 \list
  70 \o \l{Property Binding in QML}{Properties} - for binding to data and functions
  71 \o \l{JavaScript Expressions in QML}{JavaScript functions} - for performing routines and logic
  72 \o \l{QML Signal and Handler Event System}{Signals and handlers} - t notify other
  73 objects about events
  74 \o \l{QML States}{States} and \l{QML Animation and Transitions}{Transitions}
  75 \o many others
  76 \endlist
  77 For information about these features, visit the respective overviews or the
  78 main Qt Quick \l{Qt Quick}{reference} page.
  79
  80 \keyword qml-loading-components
  81 \section1 Loading a Component
  82
  83 The initialization of inline components is different from loading a component
  84 from a \c .qml file.
  85
  86 \section2 Importing a Component
  87
  88 A component defined in a \c .qml file is directly usable by declaring the name
  89 of the component. For example, a button defined in \c Button.qml is created by
  90 declaring a \c Button. The button is defined in the
  91 \l {qml-define-components}{Defining New Components} section.
  92 \snippet doc/src/snippets/declarative/reusablecomponents/application.qml document
  93
  94 Note that the component name, \c Button, matches the QML filename, \c Button.qml.
  95 Also, the first character is in upper case. Matching the names allow
  96 components in the same directory to be in the direct import path of the
  97 application.
  98
  99 For flexibility, a \c qmldir file is for dictating which additional components,
 100 plugins, or directories should be imported. By using a \c qmldir file, component
 101 names do not need to match the filenames. The \c qmldir file should, however, be
 102 in an imported path.
 103 \snippet doc/src/snippets/declarative/reusablecomponents/qmldir document
 104
 105 \section2 Loading an Inline Component
 106
 107 A consequence of inline components is that initialization may be deferred or
 108 delayed. A component may be created during a MouseArea event or by using a
 109 \l Loader element. The component can create an object, which is addressable in a
 110 similar way as an \l {qml-id}{identifier}. Thus, the created object may
 111 have its bindings set and read like a normal QML object.
 112 \snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component
 113 \snippet doc/src/snippets/declarative/reusablecomponents/component.qml create inline component
 114
 115 \keyword qml-component-properties
 116 \section1 Component Properties
 117
 118 Initializing a component, either from a .qml file or initializing an inline
 119 component, have several properties to facilitate component execution.
 120 Specifically, there are \l{attached-properties}{attached properties} and
 121 \l{attached-signalhandlers}{attached signal handlers} for setting properties
 122 during the lifetime of a component.
 123
 124 The \c{Component.onCompleted} attached signal handler is called when the
 125 component completes initialization. It is useful for executing any commands
 126 after component initialization. Similarly, the \c{Component.onDestruction}
 127 signal handler executes when the component finishes destruction.
 128
 129 \keyword qml-top-level
 130 \section1 Top-Level Component
 131
 132 Choosing the \i{top-level} or the \i{root} object of components is an important
 133 design aspect because the top-level object dictates which properties are
 134 accessible outside the component. Some elements are not visual elements and
 135 will not have visual properties exposed outside the component. Likewise, some
 136 elements add functionality that are not available to visual elements.
 137
 138 Consider the Button component from the
 139 \l{qml-define-components}{Defining New Components} section; it's top-level
 140 object is a \l Rectangle. When imported, the Button component will possess the
 141 Rectangle's properties, methods, signals, and any custom properties.
 142
 143 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent begin
 144 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses
 145 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml properties
 146 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses
 147 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent end
 148
 149 The Button's \c text alias is accessible from outside the component as well as
 150 the Rectangle's visual properties and signals such as \c x, \c y, \c anchors,
 151 and \c states.
 152
 153 Alternatively, we may choose a \l {Keyboard Focus in QML}{FocusScope} as our
 154 top-level object. The \l FocusScope element manage keyboard focus for its
 155 children which is beneficial for certain types of interfaces. However, since
 156 \c FocusScopes are not visual elements, the visual properties of its child need
 157 to be exposed.
 158
 159 \snippet doc/src/snippets/declarative/reusablecomponents/focusbutton.qml document
 160
 161 \keyword qml-id
 162 \section2 The Object Identifier
 163
 164 Each QML object may be given a special unique identifier called an \c id.
 165 No other object within the same QML component (see \l{QML Documents}) can have
 166 the same \c id value. QML objects may then access an object using the \c id
 167 property.
 168 \snippet doc/src/snippets/declarative/properties.qml id property
 169 A component may readily access its parent's properties by using the \c parent
 170 property.
 171
 172 Note that an \c id must begin with a lower-case letter or an underscore. The
 173 \c id cannot contain characters other than letters, numbers, underscores, and
 174 \l {JavaScript Reserved Words}{JavaScript reserved words}.
 175
 176 \section2 Child Components
 177
 178 Objects or Items declared within a component can be made accessible by binding their id to a
 179 property alias.
 180
 181 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent begin
 182 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml object alias
 183 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml text
 184 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent end
 185
 186 The advantage of using an alias instead a property of type of the object is that the value of
 187 the alias cannot be overridden, and members of the object can be used in property bindings when
 188 declaring an instance of the component.
 189 \snippet doc/src/snippets/declarative/reusablecomponents/application.qml grouped property
 190 If a property of type \c Text was used instead of an alias in this instance there would be no
 191 guarantee that \c label would be initialized before the binding was attempted which would cause
 192 the binding to fail.
 193 */
 194