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, 197 insertions, 0 deletions

diff --git a/doc/src/qml/qtprogrammers.qdoc b/doc/src/qml/qtprogrammers.qdoc
new file mode 100644
index 0000000000..215f71859c
--- /dev/null
+++ b/doc/src/qml/qtprogrammers.qdoc
@@ -0,0 +1,197 @@
+/****************************************************************************
+**
+** 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 qtprogrammers.html
+\target qtprogrammers
+\title QML for Qt Programmers
+\brief learning QML for programmers with Qt knowledge
+
+While QML does not require Qt knowledge to use, if you \i are already familiar with Qt,
+much of your knowledge is directly relevant to learning and using QML. Of course,
+an application with a user interface defined in QML also uses Qt for all the non-UI
+logic.
+
+\section1 Familiar Concepts
+
+QML provides direct access to the following concepts from Qt:
+
+\list
+ \o QAction - the \l {QML Basic Types}{action} type
+ \o QObject signals and slots - available as functions to call in JavaScript
+ \o QObject properties - available as variables in JavaScript
+ \o QWidget - QDeclarativeView is a QML-displaying widget
+ \o Qt models - used directly in data binding (QAbstractItemModel)
+\endlist
+
+Qt knowledge is \i required for \l{Extending QML with C++},
+and also for \l{Integrating QML Code with existing Qt UI code}.
+
+\section1 QML Items Compared with Widgets
+
+QML Items are very similar to widgets: they define the look and feel of the user
+interface. Note that, while widgets haven't traditionally been used to define the
+look and feel of view delegates, QML Items can be used for this as well.
+
+There are three structurally different types of widget:
+
+\list
+ \o Simple widgets that are not used as parents (QLabel, QCheckBox, QToolButton, etc.)
+ \o Parent widgets that are normally used as parents to other widgets (QGroupBox,
+    QStackedWidget, QTabWidget, etc.)
+ \o Compound widgets that are internally composed of child widgets (QComboBox,
+    QSpinBox, QFileDialog, QTabWidget, etc.)
+\endlist
+
+QML Items also serve these purposes. Each is considered separately below.
+
+\section2 Simple Widgets
+
+The most important rule to remember while implementing a new QDeclarativeItem in C++
+is that it should not contain any look and feel policies; leave that to the QML
+usage of the item.
+
+As an example, imagine you wanted a reusable Button item. If you therefore decided
+to write a QDeclarativeItem subclass to implement a button, just as QToolButton
+subclasses QWidget for this purpose, following the rule above, your
+\c QDeclarativeButton would not have any appearance; just the notions of enabled,
+triggering, etc.
+
+However, there is already an object in Qt that does this: QAction.
+
+QAction is the UI-agnostic essence of QPushButton, QCheckBox, QMenu items,
+QToolButton, and other visual widgets that are commonly bound to a QAction.
+
+So, the job of implementing a checkbox abstraction for QML is already done by QAction.
+The look and feel of an action, the appearance of the button, the transition
+between states, and exactly how it responds to mouse, key, or touch input, should
+all be left for definition in QML.
+
+It is illustrative to note that QDeclarativeTextEdit is built upon QTextControl,
+QDeclarativeWebView is built upon QWebPage, and ListView uses QAbstractItemModel,
+just as QTextEdit, QWebView, and QListView are built upon those same UI-agnostic
+components.
+
+The encapsulation of the look and feel that widgets provide is important, and for
+this the QML concept of \l{QML Documents}{components} serves the same purpose.
+If you are building a complete suite of applications which should have a
+consistent look and feel, you should build a set of reusable components with the
+look and feel you desire.
+
+So, to implement your reusable button, you would simply build a QML component.
+
+
+\section2 Parent Widgets
+
+Parent widgets each provide a generic way to provide an interface to one or more
+arbitrary widgets. A QTabWidget provides an interface to multiple "pages", one of
+which is visible at any time, and a mechanism for selecting among them: the QTabBar.
+A QScrollArea provides scrollbars around a widget that is otherwise too large to
+fit in the available space.
+
+Nearly all such components can be created directly in QML. Only a few cases
+which require very particular event handling, such as \l Flickable, require C++
+implementations.
+
+As an example, imagine you decided to make a generic tab widget item to be used
+through your application suite wherever information is in such quantity that it
+needs to be divided up into pages.
+
+A significant difference in the parenting concept with QML compare to QWidgets
+is that while child items are positioned relative to their parents, there is no
+requirement that they be wholly contained ("clipped") to the parent (although the
+\l{Item::}{clipped} property of the child item does allow this where it is needed).
+This difference has rather far-reaching consequences, for example:
+
+\list
+\o A shadow or highlight around a widget could be a child of that widget.
+\o Particle effects can flow outside the object where they originate.
+\o Transitioning animations can "hide" items by visibly moving them beyond
+   the screen bounds.
+\endlist
+
+\section2 Compound Widgets
+
+Some widgets provide functionality by composing other widgets as an "implementation
+detail", providing a higher level API to the composition. QSpinBox for example is a
+line edit and some buttons to increase/decrease the edited value. QFileDialog uses
+a whole host of widgets to give the user a way of finding and selecting a file
+name.
+
+When developing reusable QML Items, you may choose to do the same: build an item
+composed of other items you have already defined.
+
+The only caveat when doing this is to consider the possible animations and
+transitions that users of the compound item might wish to employ. For example, a
+spinbox might need to smoothly transition from an arbitrary \l Text item, or
+characters within a \l Text item, so your spinbox item would need to be sufficiently
+flexible to allow such animation.
+
+\section1 QML Items Compared with Graphics Widgets
+
+The main difference between QML items and QGraphicsWidgets is how they are intended
+to be used. The technical implementation details are much the same, but in practice
+they are different because QML items are made for declarative and compositional use,
+and QGraphicsWidgets are made for imperative and more integrated use. Both QML items
+and QGraphicsWidgets inherit from QGraphicsObject, and can co-exist. The differences
+are in the layout system and the interfacing with other components. Note that, as
+QGraphicsWidgets tend more to be all-in-one packages, the equivalent of a
+QGraphicsWidget may be many QML items composed across several QML files, but it can
+still be loaded and used as a single QGraphicsObject from C++.
+
+QGraphicsWidgets are usually designed to be laid out with QGraphicsLayouts. QML does
+not use QGraphicsLayouts, as the Qt layouts do not mix well with animated and fluid
+UIs, so the geometry interface is one of the main differences. When writing QML
+elements, you allow the designers to place their bounding rectangle using absolute
+geometry, bindings or anchors (all set up for you when you inherit QDeclarativeItem)
+and you do not use layouts or size hints. If size hints are appropriate, then place
+them in the QML documentation so that the designers know how to use the item best,
+but still have complete control over the look and feel.
+
+The other main difference is that QGraphicsWidgets tend to follow the widget model,
+in that they are a self-contained bundle of UI and logic. In contrast, QML
+primitives are usually a single purpose item that does not fulfill a use case on
+its own, but is composed into the equivalent of the widget inside the QML file. So
+when writing QML Items, try to avoid doing UI logic or composing visual elements
+inside the items. Try instead to write more general purpose primitives, so that the
+look and feel (which involves the UI logic) can be written in QML.
+
+Both differences are caused by the different method of interaction. QGraphicsWidget
+is a QGraphicsObject subclass which makes fluid UI development from C++ easier, and
+QDeclarativeItem is a QGraphicsObject subclass which makes fluid UI development
+from QML easier. The difference, therefore, is primarily one of the interface
+exposed, and the design of the items that come with it; the declarative primitives
+for QML and nothing for QGraphicsWidget, because you need to write your own UI
+logic into the subclass.
+
+If you wish to use both QML and C++ to write the UI, for example to ease the
+transition period, it is recommended to use QDeclarativeItem subclasses, although
+you can use QGraphicsWidgets as well. To allow for easier use from C++, make the
+root item of each C++ component a \l LayoutItem, and load individual "widgets" of
+QML (possibly comprised of multiple files, and containing a self-contained bundle
+of UI and logic) into your scene to replace individual QGraphicsWidgets one at a time.
+*/