doc/src/declarative/qmlreusablecomponents.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2010 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 qmlreusablecomponents.html
  30 \ingroup qml-features
  31 \previouspage {QML Signal and Handler Event System}{Signal and Handler Event System}
  32 \nextpage {QML States}{States}
  33 \contentspage QML Features
  34
  35 \title Importing Reusable Components
  36
  37 A \e component is an instantiable QML definition, typically contained in a
  38 \c .qml file. For instance, a Button \e component may be defined in
  39 \c Button.qml. The QML runtime may instantiate this Button component to create
  40 Button \e objects. Alternatively, a component may be defined inside a
  41 \l Component element.
  42
  43 Moreover, the Button definition may also contain other components. A Button
  44 component could use a Text element for its label and other components to
  45 implement its functions. Compounding components to form new components
  46 (and effectively new interfaces) is the emphasis in QML.
  47
  48 \keyword qml-define-components
  49 \section1 Defining New Components
  50
  51 Any snippet of QML code may become a component, by placing the code in a QML
  52 file (extension is \c .qml). A complete Button component that responds to user
  53 input may be in a Button.qml file.
  54 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml document
  55
  56 Alternatively, a \l Component element may encapsulate a QML object to form a
  57 component.
  58 \snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent begin
  59 \snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component
  60 \snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent end
  61
  62 \keyword qml-loading-components
  63 \section1 Loading a Component
  64
  65 The initialization of inline components is different from loading a component
  66 from a \c .qml file.
  67
  68 \section2 Importing a Component
  69
  70 A component defined in a \c .qml file is directly usable by declaring the name
  71 of the component. For example, a button defined in \c Button.qml is created by
  72 declaring a \c Button. The button is defined in the
  73 \l {qml-define-components}{Defining New Components} section.
  74 \snippet doc/src/snippets/declarative/reusablecomponents/application.qml document
  75
  76 Note that the component name, \c Button, matches the QML filename, \c Button.qml.
  77 Also, the first character is in upper case. Matching the names allow
  78 components in the same directory to be in the direct import path of the
  79 application.
  80
  81 For flexibility, a \c qmldir file is for dictating which additional components,
  82 plugins, or directories should be imported. By using a \c qmldir file,
  83 component names do not need to match the filenames. The \c qmldir file should,
  84 however, be in an imported path.
  85 \snippet doc/src/snippets/declarative/reusablecomponents/qmldir document
  86
  87 \section2 Loading an Inline Component
  88
  89 A consequence of inline components is that initialization may be deferred or
  90 delayed. A component may be created during a MouseArea event or by using a
  91 \l Loader element. The component can create an object, which is addressable in a
  92 similar way as an \l {qml-id-property}{id property}. Thus, the created object may
  93 have its bindings set and read like a normal QML object.
  94 \snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component
  95 \snippet doc/src/snippets/declarative/reusablecomponents/component.qml create inline component
  96
  97 \keyword qml-component-properties
  98 \section1 Component Properties
  99
 100 Initializing a component, either from a .qml file or initializing an inline
 101 component, have several properties to facilitate component execution.
 102 Specifically, there are \l{attached-properties}{attached properties} and
 103 \l{attached-signalhandlers}{attached signal handlers} for setting properties
 104 during the lifetime of a component.
 105
 106 The \c{Component.onCompleted} attached signal handler is called when the
 107 component completes initialization. It is useful for executing any commands
 108 after component initialization. Similarly, the \c{Component.onDestruction}
 109 signal handler executes when the component finishes destruction.
 110
 111 \keyword qml-top-level
 112 \section1 Top-Level Component
 113
 114 Choosing the \e{top-level} or the \e{root} object of components is an important
 115 design aspect because the top-level object dictates which properties are
 116 accessible outside the component. Some elements are not visual elements and
 117 will not have visual properties exposed outside the component. Likewise, some
 118 elements add functionality that are not available to visual elements.
 119
 120 Consider the Button component from the
 121 \l{qml-define-components}{Defining New Components} section; it's top-level
 122 object is a \l Rectangle. When imported, the Button component will possess the
 123 Rectangle's properties, methods, signals, and any custom properties.
 124
 125 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent begin
 126 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses
 127 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml properties
 128 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses
 129 \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent end
 130
 131 The Button's \c text alias is accessible from outside the component as well as
 132 the Rectangle's visual properties and signals such as \c x, \c y, \c anchors,
 133 and \c states.
 134
 135 Alternatively, we may choose a \l {Keyboard Focus in QML}{FocusScope} as our
 136 top-level object. The \l FocusScope element manage keyboard focus for its
 137 children which is beneficial for certain types of interfaces. However, since
 138 \c FocusScopes are not visual elements, the visual properties of its child need
 139 to be exposed.
 140
 141 \snippet doc/src/snippets/declarative/reusablecomponents/focusbutton.qml document
 142 */
 143