Doc: Overhaul of doc/src/declarative and QtQuick2 docs.

-Consolidated model/view documentation into one.
-Added a new navigation for all overviews (grouped the pages)
-New front page that shows the grouping
-Separated the Qt C++ from the main QML overviews
-Consolidated Qt C++ into the "declarative runtime" section
-New articles about JavaScript, the engine, and plugins
-Fixed the older examples. New snippet comments
-Renamed some of the articles
-kept the qtquick2 qmlmodule
-"Qt Quick Elements"

Moved contents of doc/src/declarative into respective
module dirs.

-Qt Quick 2, LocalStorage, Particles, and QML are now
separate.
-Removed unused or duplicate documentation.
-edited C++ examples
-removed navigation and "\inqmlmodule QtQuick 2" for
those pages that are not in Qt Quick 2
-fixed doc/src/ licenses to header.FDL from qtbase

Change-Id: Ib36f9c07565d91160fa8d04f9670c438f684b82a
Reviewed-by: Sergio Ahumada <sergio.ahumada@nokia.com>

1 files changed, 194 insertions, 0 deletions

diff --git a/doc/src/qml/qmlcomponents.qdoc b/doc/src/qml/qmlcomponents.qdoc
new file mode 100644
index 0000000000..bcc465f4b2
--- /dev/null
+++ b/doc/src/qml/qmlcomponents.qdoc
@@ -0,0 +1,194 @@
+/****************************************************************************
+**
+** 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/declarative/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/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
+
+
+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/declarative/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/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}{identifier}. 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 \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/declarative/reusablecomponents/Button.qml parent begin
+\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses
+\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml properties
+\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses
+\snippet doc/src/snippets/declarative/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/declarative/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/declarative/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/declarative/reusablecomponents/Button.qml parent begin
+\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml object alias
+\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml text
+\snippet doc/src/snippets/declarative/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/declarative/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.
+*/
+