/*! 
\page components.html
\target components
\title Components

A \bold component is a reusable, encapsulated Qml element with a well-defined interface.

Writing and using components allows you to:
\list
\o Reuse sections of Qml without copy-and-paste.
\o Have consistent Look and Feel between different parts of your UI.
\o Create new Qml elements without writing a new C++ class. (See \l {cppitem}{Creating Qml elements in C++})
\endlist

Components are placed in \e <Name>.qml files, allowing \e <Name> to then be used as a tag
elsewhere. For example, if you have a Slider.qml file, you can then use \c {Slider { ... }} to
make a slider, just as if it was a built-in type.

Components may be collected into \l {qmlmodules}{modules}.

\section1 Example: Creating a MyButton Component

This example describes how to create a component from an existing snippet of Qml.

Assume you have an existing UI with a single 'Save' button, defined as follows:

\code
Image {
    source: "pics/button-background.png"
    Text {
        text: "Save"
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.verticalCenter: parent.verticalCenter
    }
    MouseRegion {
        anchors.fill: parent
        onClick: { saveData() }
    }
}
\endcode

For the next release, you plan to add 'Cancel' and 'Reset' buttons. Rather than copying and pasting the above markup, you can create a component:

\list 1
\o Create a file called MyButton.qml, and copy the relevant Qml snippet into that file.
\o Make some minor changes to define the component's interface:

\code
Image {
    property string label
    signal clicked
    source: "pics/button-background.png"
    Text {
        text: parent.label
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.verticalCenter: parent.verticalCenter
    }
    MouseRegion {
        anchors.fill: parent
        onClick: { parent.click.emit() }
    }
}
\endcode

The \a label property and \a click signal that were added effectively become part of the 'public API' of the MyButton component. In a similar manner, the Text and MouseRegion elements become invisible to anyone using the component. Note that the Text element now binds in its data from \a label, and the MouseRegion emits a generic signal.

\o The component can now be used elsewhere as MyButton:

\code
MyButton { label: "Save"; onClicked: saveData() }
...
MyButton { label: "Cancel"; onClicked: cancelData() }
...
MyButton { label: "Reset"; onClicked: resetData() }
\endcode

\endlist

\section1 Placing .qml Files

When one component refers to a another, the second must be found either in the same directory
as the first, or in a directory imported using the \c import statement:

\code
import "library"
\endcode

\section1 Namespaces

Namespaces for QML will be supported in Qt 4.6.

*/