/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page qml-components.html
\ingroup qml-features
\contentspage QML Reference

\title QML Components
\brief creating and instantiating components

A \i component is an instantiable QML definition, typically contained in a \c
.qml file. For instance, a Button \i component may be defined in \c Button.qml
file. The \l{The QML Engine}{QML engine} may instantiate this Button
component to create Button \i objects. Alternatively, a component may be defined
inside a \l Component element.

Moreover, the Button definition may also contain other components. A Button
component might have a Text element for its label and other components to
implement its functions. Compounding components to form new components
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, whose 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/qml/reusablecomponents/Button.qml document

The component name, \c Button, matches the QML filename, \c Button.qml.
Also, 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. The section on \l{Importing a Component} has information about
naming components with different filenames.

Alternatively, a \l Component element may encapsulate a QML object to form a
component.
\snippet doc/src/snippets/qml/reusablecomponents/component.qml parent begin
\snippet doc/src/snippets/qml/reusablecomponents/component.qml define inline component
\snippet doc/src/snippets/qml/reusablecomponents/component.qml parent end


Components may incorporate any \l{Qt Quick}{QML feature} such as:
\list
\o \l{Property Binding in QML}{Properties} - for binding to data and functions
\o \l{JavaScript Expressions in QML}{JavaScript functions} - for performing routines and logic
\o \l{QML Signal and Handler Event System}{Signals and handlers} - t notify other
objects about events
\o \l{QML States}{States} and \l{QML Animation and Transitions}{Transitions}
\o many others
\endlist
For information about these features, visit the respective overviews or the
main Qt Quick \l{Qt Quick}{reference} page.

\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/qml/reusablecomponents/application.qml document

Note that the component name, \c Button, matches the QML filename, \c Button.qml.
Also, 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, be
in an imported path.
\snippet doc/src/snippets/qml/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}{identifier}. Thus, the created object may
have its bindings set and read like a normal QML object.
\snippet doc/src/snippets/qml/reusablecomponents/component.qml define inline component
\snippet doc/src/snippets/qml/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 \c{Component.onCompleted} attached signal handler is called when the
component completes initialization. It is useful for executing any commands
after component initialization. Similarly, the \c{Component.onDestruction}
signal handler executes when the component finishes destruction.

\keyword qml-top-level
\section1 Top-Level Component

Choosing the \i{top-level} or the \i{root} object of components is an important
design aspect because the top-level object dictates which properties are
accessible outside the component. Some elements are not visual elements and
will not have visual properties exposed outside the component. Likewise, some
elements add functionality that are not available to visual elements.

Consider the Button component from the
\l{qml-define-components}{Defining New Components} section; it's top-level
object is a \l Rectangle. When imported, the Button component will possess the
Rectangle's properties, methods, signals, and any custom properties.

\snippet doc/src/snippets/qml/reusablecomponents/Button.qml parent begin
\snippet doc/src/snippets/qml/reusablecomponents/Button.qml ellipses
\snippet doc/src/snippets/qml/reusablecomponents/Button.qml properties
\snippet doc/src/snippets/qml/reusablecomponents/Button.qml ellipses
\snippet doc/src/snippets/qml/reusablecomponents/Button.qml parent end

The Button's \c text alias is accessible from outside the component as well as
the Rectangle's visual properties and signals such as \c x, \c y, \c anchors,
and \c states.

Alternatively, we may choose a \l {Keyboard Focus in QML}{FocusScope} as our
top-level object. The \l FocusScope element manage keyboard focus for its
children which is beneficial for certain types of interfaces. However, since
\c FocusScopes are not visual elements, the visual properties of its child need
to be exposed.

\snippet doc/src/snippets/qml/reusablecomponents/focusbutton.qml document

\keyword qml-id
\section2 The Object Identifier

Each QML object may be given a special unique identifier called an \c id.
No other object within the same QML component (see \l{QML Documents}) can have
the same \c id value. QML objects may then access an object using the \c id
property.
\snippet doc/src/snippets/qml/properties.qml id property
A component may readily access its parent's properties by using the \c parent
property.

Note that an \c id must begin with a lower-case letter or an underscore. The
\c id cannot contain characters other than letters, numbers, underscores, and
\l {JavaScript Reserved Words}{JavaScript reserved words}.

\section2 Child Components

Objects or Items declared within a component can be made accessible by binding their id to a
property alias.

\snippet doc/src/snippets/qml/reusablecomponents/Button.qml parent begin
\snippet doc/src/snippets/qml/reusablecomponents/Button.qml object alias
\snippet doc/src/snippets/qml/reusablecomponents/Button.qml text
\snippet doc/src/snippets/qml/reusablecomponents/Button.qml parent end

The advantage of using an alias instead a property of type of the object is that the value of
the alias cannot be overridden, and members of the object can be used in property bindings when
declaring an instance of the component.
\snippet doc/src/snippets/qml/reusablecomponents/application.qml grouped property
If a property of type \c Text was used instead of an alias in this instance there would be no
guarantee that \c label would be initialized before the binding was attempted which would cause
the binding to fail.
*/