/****************************************************************************
**
** 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:LGPL$
** 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 Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights.  These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page tutorial2.html
\title Tutorial 2 - QML Component

This chapter adds a color picker to change the color of the text.

\image declarative-tutorial2.png

Our color picker is made of six cells with different colors.
To avoid writing the same code multiple times, we first create a new \c Cell component.
A component provides a way of defining a new type that we can re-use in other QML files.
A QML component is like a black-box and interacts with the outside world through properties, signals and slots and is generally
defined in its own QML file (for more details, see \l {Defining new Components}).
The component's filename must always start with a capital letter.

Here is the QML code for \c Cell.qml:

\snippet examples/declarative/tutorials/helloworld/Cell.qml 0

\section1 Walkthrough

\section2 The Cell Component

\snippet examples/declarative/tutorials/helloworld/Cell.qml 1

The root element of our component is an \l Item with the \c id \e container.
An \l Item is the most basic visual element in QML and is often used as a container for other elements.

\snippet examples/declarative/tutorials/helloworld/Cell.qml 4

We declare a \c color property. This property is accessible from  \e outside our component, this allows us
to instantiate the cells with different colors.
This property is just an alias to an existing property - the color of the rectangle that compose the cell (see \l{intro-properties}{Properties}).

\snippet examples/declarative/tutorials/helloworld/Cell.qml 5

We want our component to also have a signal that we call \e clicked with a \e color parameter.
We will use this signal to change the color of the text in the main QML file later.

\snippet examples/declarative/tutorials/helloworld/Cell.qml 2

Our cell component is basically a colored rectangle with the \c id \e rectangle.

The \c anchors.fill property is a convenient way to set the size of an element.
In this case the rectangle will have the same size as its parent (see \l{anchor-layout}{Anchor-based Layout}).

\snippet examples/declarative/tutorials/helloworld/Cell.qml 3

In order to change the color of the text when clicking on a cell, we create a \l MouseArea element with
the same size as its parent.

A \l MouseArea defines a signal called \e clicked.
When this signal is triggered we want to emit our own \e clicked signal with the color as parameter.

\section2 The main QML file

In our main QML file, we use our \c Cell component to create the color picker:

\snippet examples/declarative/tutorials/helloworld/tutorial2.qml 0

We create the color picker by putting 6 cells with different colors in a grid.

\snippet examples/declarative/tutorials/helloworld/tutorial2.qml 1

When the \e clicked signal of our cell is triggered, we want to set the color of the text to the color passed as a parameter.
We can react to any signal of our component through a property of the name \e 'onSignalName' (see \l{Signal Handlers}).

[Previous: \l {Tutorial 1 - Basic Types}] [Next: \l {Tutorial 3 - States and Transitions}]

*/