doc/src/declarative/qmlreusablecomponents.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: http://www.qt-project.org/
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qmlreusablecomponents.html
  30 \inqmlmodule QtQuick 2
  31 \ingroup qml-features
  32 \previouspage {QML Signal and Handler Event System}{Signal and Handler Event System}
  33 \nextpage {QML States}{States}
  34 \contentspage QML Features
  35
  36 \title Importing Reusable Components
  37
  38 A \i component is an instantiable QML definition, typically contained in a
  39 \c .qml file. For instance, a Button \i component may be defined in
  40 \c Button.qml. The QML runtime may instantiate this Button component to create
  41 Button \i objects. Alternatively, a component may be defined inside a
  42 \l Component element.
  43
  44 Moreover, the Button definition may also contain other components. A Button
  45 component could use a Text element for its label and other components to
  46 implement its functions. Compounding components to form new components
  47 (and effectively new interfaces) is the emphasis in QML.
  48
  49 \keyword qml-define-components
  50 \section1 Defining New Components
  51
  52 Any snippet of QML code may become a component, by placing the code in a QML
  53 file (extension is \c .qml). A complete Button component that responds to user
  54 input may be in a Button.qml file.
  55 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml document
  56
  57 Alternatively, a \l Component element may encapsulate a QML object to form a
  58 component.
  59 \snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent begin
  60 \snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component
  61 \snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent end
  62
  63 \keyword qml-loading-components
  64 \section1 Loading a Component
  65
  66 The initialization of inline components is different from loading a component
  67 from a \c .qml file.
  68
  69 \section2 Importing a Component
  70
  71 A component defined in a \c .qml file is directly usable by declaring the name
  72 of the component. For example, a button defined in \c Button.qml is created by
  73 declaring a \c Button. The button is defined in the
  74 \l {qml-define-components}{Defining New Components} section.
  75 \snippet doc/src/snippets/declarative/reusablecomponents/application.qml document
  76
  77 Note that the component name, \c Button, matches the QML filename, \c Button.qml.
  78 Also, the first character is in upper case. Matching the names allow
  79 components in the same directory to be in the direct import path of the
  80 application.
  81
  82 For flexibility, a \c qmldir file is for dictating which additional components,
  83 plugins, or directories should be imported. By using a \c qmldir file,
  84 component names do not need to match the filenames. The \c qmldir file should,
  85 however, be in an imported path.
  86 \snippet doc/src/snippets/declarative/reusablecomponents/qmldir document
  87
  88 \section2 Loading an Inline Component
  89
  90 A consequence of inline components is that initialization may be deferred or
  91 delayed. A component may be created during a MouseArea event or by using a
  92 \l Loader element. The component can create an object, which is addressable in a
  93 similar way as an \l {qml-id-property}{id property}. Thus, the created object may
  94 have its bindings set and read like a normal QML object.
  95 \snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component
  96 \snippet doc/src/snippets/declarative/reusablecomponents/component.qml create inline component
  97
  98 \keyword qml-component-properties
  99 \section1 Component Properties
 100
 101 Initializing a component, either from a .qml file or initializing an inline
 102 component, have several properties to facilitate component execution.
 103 Specifically, there are \l{attached-properties}{attached properties} and
 104 \l{attached-signalhandlers}{attached signal handlers} for setting properties
 105 during the lifetime of a component.
 106
 107 The \c{Component.onCompleted} attached signal handler is called when the
 108 component completes initialization. It is useful for executing any commands
 109 after component initialization. Similarly, the \c{Component.onDestruction}
 110 signal handler executes when the component finishes destruction.
 111
 112 \keyword qml-top-level
 113 \section1 Top-Level Component
 114
 115 Choosing the \i{top-level} or the \i{root} object of components is an important
 116 design aspect because the top-level object dictates which properties are
 117 accessible outside the component. Some elements are not visual elements and
 118 will not have visual properties exposed outside the component. Likewise, some
 119 elements add functionality that are not available to visual elements.
 120
 121 Consider the Button component from the
 122 \l{qml-define-components}{Defining New Components} section; it's top-level
 123 object is a \l Rectangle. When imported, the Button component will possess the
 124 Rectangle's properties, methods, signals, and any custom properties.
 125
 126 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent begin
 127 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses
 128 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml properties
 129 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses
 130 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent end
 131
 132 The Button's \c text alias is accessible from outside the component as well as
 133 the Rectangle's visual properties and signals such as \c x, \c y, \c anchors,
 134 and \c states.
 135
 136 Alternatively, we may choose a \l {Keyboard Focus in QML}{FocusScope} as our
 137 top-level object. The \l FocusScope element manage keyboard focus for its
 138 children which is beneficial for certain types of interfaces. However, since
 139 \c FocusScopes are not visual elements, the visual properties of its child need
 140 to be exposed.
 141
 142 \snippet doc/src/snippets/declarative/reusablecomponents/focusbutton.qml document
 143
 144 \section2 Child Components
 145
 146 Objects or Items declared within a component can be made accessible by binding their id to a
 147 property alias.
 148
 149 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent begin
 150 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml object alias
 151 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml text
 152 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent end
 153
 154 The advantage of using an alias instead a property of type of the object is that the value of
 155 the alias cannot be overridden, and members of the object can be used in property bindings when
 156 declaring an instance of the component.
 157 \snippet doc/src/snippets/declarative/reusablecomponents/application.qml grouped property
 158 If a property of type \c Text was used instead of an alias in this instance there would be no
 159 guarantee that \c label would be initialized before the binding was attempted which would cause
 160 the binding to fail.
 161 */