1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qmlreusablecomponents.html
\ingroup qml-features
\previouspage {Keyboard Focus in QML}{Keyboard Focus}
\nextpage {QML States}{States}
\contentspage QML Features
\title Importing Reusable Components
A \e component is an instantiable QML definition, typically contained in a
\c .qml file. For instance, a Button \e component may be defined in
\c Button.qml. The QML runtime may instantiate this Button component to create
Button \e objects. Alternatively, a component may be defined inside a
\l Component element.
Moreover, the Button definition may also contain other components. A Button
component could use a Text element for its label and other components to
implement its functions. Compounding components to form new components
(and effectively new interfaces) is the emphasis in QML.
\keyword qml-define-components
\section1 Defining New Components
Any snippet of QML code may become a component, by placing the code in a QML
file (extension is \c .qml). A complete Button component that responds to user
input may be in a Button.qml file.
\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml document
Alternatively, a \l Component element may encapsulate a QML object to form a
component.
\snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent begin
\snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component
\snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent end
\keyword qml-loading-components
\section1 Loading a Component
The initialization of inline components is different from loading a component
from a \c .qml file.
\section2 Importing a Component
A component defined in a \c .qml file is directly usable by declaring the name
of the component. For example, a button defined in \c Button.qml is created by
declaring a \c Button. The button is defined in the
\l {qml-define-components}{Defining New Components} section.
\snippet doc/src/snippets/declarative/reusablecomponents/application.qml document
Note that the component name, \c Button, matches the QML filename, \c Button.qml.
Specifically, the first character is in upper case. Matching the names allow
components in the same directory to be in the direct import path of the
application.
For flexibility, a \c qmldir file is for dictating which additional components,
plugins, or directories should be imported. By using a \c qmldir file,
component names do not need to match the filenames. The \c qmldir file should,
however, in an imported path.
\snippet doc/src/snippets/declarative/reusablecomponents/qmldir document
\section2 Loading an Inline Component
A consequence of inline components is that initialization may be deferred or
delayed. A component may be created during a MouseArea event or by using a
\l Loader element. The component can create an object, which is addressable in a
similar way as an \l {qml-id-propert}{id property}. Thus, the created object may
have its bindings set and read like a normal QML object.
\snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component
\snippet doc/src/snippets/declarative/reusablecomponents/component.qml create inline component
\keyword qml-component-properties
\section1 Component Properties
Initializing a component, either from a .qml file or initializing an inline
component, have several properties to facilitate component execution.
Specifically, there are \l{attached-properties}{attached properties} and
\l{attached-signalhandlers}{attached signal handlers} for setting properties
during the lifetime of a component.
*/
The root object in \c Button.qml defines the attributes that are available to users of the
\c Button component. In this case, the root object is a \l Rectangle, so any properties, methods
and signals of \l Rectangle are made available, allowing \c application.qml to
customize the \c width, \c height, \c radius and \c color properties of \c Button objects.
If \c Button.qml was not in the same directory, \c application.qml would need to load it as a
\l {Modules}{module} from a specific filesystem path or \l{QDeclarativeExtensionPlugin}{plugin}.
Also, note the letter case of the component file name is significant on some (notably UNIX)
filesystems. It is recommended the file name case matches the case of the QML component name
exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the
QML component will be deployed.
\snippet doc/src/snippets/declarative/qml-extending-types/components/Button.qml 0
\table
\row
\o \snippet doc/src/snippets/declarative/qml-extending-types/components/application.qml 0
\o \image qml-extending-types.png
\endtable
|
