Update copyright headers
[qt:qt.git] / doc / src / declarative / qmlreusablecomponents.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
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