1 files changed, 347 insertions, 0 deletions
diff --git a/src/quick/doc/src/concepts/topic.qdoc b/src/quick/doc/src/concepts/topic.qdoc
new file mode 100644
index 0000000000..9fd960850c
--- /dev/null
+++ b/src/quick/doc/src/concepts/topic.qdoc
@@ -0,0 +1,347 @@
+/****************************************************************************
+**
+** 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 qtquick-concepts-topic.html
+\title Important Concepts In Qt Quick
+\brief Overview of important concepts in Qt Quick
+
+Qt Quick provides everything needed to create a rich application with a fluid
+and dynamic user interface.  It is based around behavior declaration rather
+than imperative programming, and defines a visual canvas with its own
+coordinate system and drawing implementation.  There are many ways to position
+user-interface elements on the screen, and animation and transition effects are
+a first-class concept in Qt Quick.
+
+\section1 The Visual Canvas
+
+The visual canvas provided by the Qt Quick is a two dimensional canvas with
+z-ordering.
+
+\section2 Coordinate System
+
+The top-left pixel in the Qt Quick coordinate system is the [0, 0] pixel.
+The coordinate system of a child item is relative to its visual parent item.
+See the documentation on the
+\l{qtquick-concepts-visual-coordinates.html}{Coordinate System} for
+in-depth information about the coordinate system utilized by Qt Quick.
+
+\section2 Visual Parent
+
+There are two separate kinds of parenting in a QML application which uses
+Qt Quick.  The first kind is the ownership-parent (also known as the QObject
+parent) which determines object lifetime semantics.  The second kind is the
+visual-parent which determines where on the canvas an item is drawn, and also
+certain properties (for example, opacity applies to visual children).
+
+In almost all cases, the visual-parent is identical to the ownership-parent.
+See the documentation about the \l{qtquick-concepts-visual-parent.html}
+{Visual Parent}for more in-depth information on the topic.
+
+\section2 Scene Graph
+
+Modern computer systems and devices use OpenGL to draw graphics.  Qt Quick
+requires OpenGL and it is used to display applications developed with
+Qt Quick in QML.  In particular, Qt Quick defines a scene graph which is then
+rendered.  See the documentation about the
+\l{qtquick-concepts-visual-scenegraph.html}{Scene Graph} for in-depth
+information about the concept of a scene graph and why it is beneficial, and
+about the scene graph implementation provided by Qt Quick.
+
+\section1 Positioning
+
+Visual items in QML can be positioned in a variety of ways.  The most important
+positioning-related concept is that of anchoring, a form of relative
+positioning where items can be anchored (or attached) to each other at certain
+boundaries.  Other positioning concepts include absolute positioning,
+positioning with coordinate bindings, and layouts.
+
+\section1 Visual Objects
+
+Most user-interfaces include some visual aspect.  While multimodal interfaces
+are extremely interesting and can be very engaging and interactive (using,
+for example, haptic feedback and sounds to notify the user of changes in the
+state of an application), visual objects in a user-interface are able to convey
+a huge amount of information to the user at a glance.
+
+See the \l{qtquick-qmltypereference.html}{Qt Quick QML type reference} for the
+complete list of visual object types provided by Qt Quick.
+
+\section2 Manual Positioning
+
+Items can be positioned manually.  If the user-interface is going to be
+static, manual positioning provides the most efficient form of positioning.
+See the documentation about
+\l{qtquick-concepts-positioning.html#manual-positioning}
+{Absolute Positioning} for in-depth information about this form of positioning.
+
+\section2 Positioning With Bindings
+
+Items may also be positioned by assigning binding expressions to the properties
+associated with their location in the visual canvas.  This type of positioning
+is the most highly dynamic, however some performance cost is associated with
+positioning items in this manner.  See the documentation on
+\l{qtquick-concepts-positioning.html#positioning-with-bindings}
+{positioning with bindings} for in-depth information about this form of
+positioning.
+
+\section2 Anchors
+
+Anchors allows an item to be placed either adjacent to or inside of another,
+by attaching one or more of the item's anchor-points (boundaries) to an
+anchor-point of the other.  These anchors will remain even if the dimensions
+or location of one of the items changes, allowing for highly dynamic
+user-interfaces.  For in-depth information about anchoring, see the
+documentation about \l{qtquick-concepts-positioning-anchors.html}
+{positioning with anchors}
+
+\section2 Layouts
+
+Qt Quick also provides some built-in layout items.  For many use cases, the
+best layout to use is a simple grid, row, or column, and Qt Quick provides
+items which will layout children in these formations in the most efficient
+manner possible.  See the documentation about
+\l{qtquick-concepts-positioning-layouts.html}{layout} for in-depth information
+on the topic.
+
+\section2 Right-To-Left Support
+
+The directionality of the written form of a language often has a great impact
+on how the visual elements of a user-interface should be positioned.  Qt Quick
+supports right-to-left positioning of elements through the predefined-layouts
+as well as right-to-left text layouts.
+
+Please see the documentation about
+\l{qtquick-concepts-positioning-righttoleft.html}
+{right-to-left support in Qt Quick} for in-depth information on the topic.
+
+\section1 User Input
+
+Being able to respond to user-input is a fundamental part of user-interface
+design.  Depending on the use-case that an application solves, and the
+form-factor of the device that the application runs on, the best way
+to receive user-input may be different.
+
+\section2 Touch
+
+Allowing users to physically touch a screen to interact with an application is
+a popular user-interface paradigm on portable devices like smartphones and
+tablets.
+
+Qt Quick was designed specifically with touch-driven user-interfaces in mind,
+and thus touch events are supported in various visual object types, from
+\l{Flickable} lists to the generic \l{MultiPointTouchArea} type, as well as
+in the \l{MouseArea} type (which will be documented thoroughly in a proceeding
+section).
+
+\section2 Motion Gestures
+
+Detecting gestures with an accelerometer, or through camera-based gesture
+recognition, can allow users to interact with an application without requiring
+their full and undevided attention.  It can also provide a more interactive
+and engaging experience.
+
+Qt Quick itself does not offer first-class support for motion gestures, however
+another QML add-on module which provides support for gestures, which uses
+Qt Quick and integrates with Qt Quick's visual canvas does exist.  See the
+Qt Sensors module documentation for more information on the topic.
+
+\section2 Keyboard
+
+Supporting input from a keyboard is a vital component of the user-interface of
+many applications.
+
+XXX TODO: generic keypress event handling documentation?
+
+Qt Quick also provides visual object types which automatically receive keyboard
+events and key-presses, and displays the appropriate text.  Please see the
+documentation about \l{qtquick-concepts-input-text.html}{text input} for
+in-depth information on the topic.
+
+\section2 Mouse
+
+The computer mouse is still a very important vector for user-input.  Detecting
+and reacting to clicks and presses according to their position is a fundamental
+concept in user-interface design.
+
+Qt Quick provides the MouseArea visual object type which automatically receives
+mouse events (including clicks and wheel events) which allows developers to
+create custom user-interface objects to handle mouse input.  Please see the
+documentation about \l{qtquick-concepts-input-mouseevents.html}
+{mouse events in Qt Quick} for more information on the topic.
+
+\section2 Focus
+
+Most user-interfaces have multiple visual objects, but usually only one object
+has focus (that is, receives key-press events) at any time.  Qt Quick has
+support for complex focus specification.  See the documentation about
+\l{qtquick-concepts-input-focus.html}{keyboard focus in Qt Quick} for more
+information on this topic.
+
+\section1 Event Interceptors
+
+In a highly dynamic user-interface, the application developer will often wish
+to intercept some events (such as property assignments) so that the change can
+be animated.  Interceptors are a first-class concept in Qt Quick, and
+application developers can dynamically intercept property assignments and
+signal emissions, and define dynamic bindings.
+
+\section2 Animating Property Assignments
+
+When the location of a visual item changes, it is often suboptimal to simply
+change the location instantaneously.  It may be better to animate the update
+to allow the user's eye to follow the change, thus providing a seamless
+user-experience.  See the documentation on
+\l{qtquick-concepts-interceptors.html#animating-property-assignments}
+{Animating Property Assignments} for more information about property assignment
+interception.
+
+\section2 Dynamic Bindings
+
+Assigning binding expressions to properties is a fundamental concept of QML,
+and Qt Quick extends upon the idea with dynamic bindings where the target of
+the binding can be defined outside of the binding expression itself.  See the
+\l{qtquick-concepts-interceptors.html#dynamic-bindings}{Dynamic Bindings} page
+for more information about this concept.
+
+\section2 Dynamic Signal Connections
+
+Just as bindings can be retargeted dynamically in Qt Quick, so too can signal
+connections.  This allows highly dynamic dispatch to be implemented in a user
+interface where different visual items need to handle different events,
+depending on the situation, at run-time.  See the documentation about
+\l{qtquick-concepts-interceptors.html#dynamic-signal-connections}
+{Dynamic Signal Connections} for in-depth information.
+
+\section1 States, Transitions And Animations
+
+In any modern user-interface, transitioning between states and animating
+the user-interface is highly beneficial.  These are first-class concepts in
+Qt Quick, and are discussed in more detail in the
+\l{qtquick-concepts-statesanimations.html}{States, Transitions And Animations}
+documentation.
+
+\section1 Data - Models, Views and Data Storage
+
+Most applications will have data that needs to be displayed to the user.  That
+data might come from a variety of sources: network sources, local files, and
+databases are all common sources of data.
+
+\section2 Models and Views
+
+It is often advantageous to show similar data in a similar manner, within an
+application, and this gives rise to the idea of having a model which contains
+data, and a view which displays the data.  The view will display a delegate
+for every datum in the model.
+
+For information about how the Model/View paradigm is implemented in Qt Quick,
+see the page titled \l{qtquick-concepts-data-modelview.html}
+{Models and Views in Qt Quick}.
+
+\section2 Data Storage and Access
+
+Databases are commonly used to store information in applications.  Qt Quick
+provides simplified access to relational databases via the
+\l{qtquick-concepts-data-localstorage.html}{Qt Quick local storage module}.
+
+\section1 Graphical Effects and Particles
+
+Visually appealing user-interfaces are more engaging than lacklustre ones.
+That said, the designer must bear in mind that visual effects simply provide
+a useful way to subtlely communicate to the user (for example, which visual
+item is active, or how focus is being transferred).  Over-use of visual
+effects can actually detract from the user-experience.
+
+\section2 Visual Transformation
+
+Visual objects can be transformed.  For example, they can be scaled or rotated.
+These sort of transformations can provide hints about focus or selection, and
+can provide intuitive hints about what events are occurring in an application.
+
+For information about visual transformations to visual objects, see the
+page titled \l{qtquick-concepts-effects-transformations.html}
+{Qt Quick Transformation Types}.
+
+\section2 Shader Effects
+
+Shader effects allow the full, raw power of a graphics processing unit to be
+utilized directly via vertex and pixel shaders.  Using too many shader effects
+can result in increased power usage and sometimes slow performance, but if
+used sparingly and carefully, a shader can allow complex and visually appealing
+effects to be applied to a visual object (for example, ripples in water).
+
+For information about shader programs and shader effects, see the page
+titled \l{qtquick-concepts-effects-shaders.html}
+{Qt Quick Shader Effects}.
+
+\section2 Particles
+
+A particle system allows explosions, fireworks, smoke, fog and wind effects to
+be simulated and displayed to the user.  Qt Quick provides a particle system
+which allows these sort of complex, 2D simulations to be performed, including
+support for environmental effects like gravity and turbulence.
+Particles are most commonly used to add subtle and visually appealing effects
+to currently selected items in lists or in activity notifiers, and in games.
+
+For information about particles, see the documentation about the
+\l{qtquick-concepts-effects-particles.html}{Qt Quick Particle System}.
+
+\section2 Sprites
+
+A sprite is an animated image made up of frames.  Sprites are commonly found
+in games.  Qt Quick provides a visual type to display sprites, as well as a
+complex, stochastic, frame-transition controller for more complex applications
+which use sprites extensively (such as games).
+
+For information about sprite animations, see the page titled
+\l{qtquick-concepts-effects-sprites.html}{Sprite Animations}.
+
+\section1 Defining And Using Modular Components
+
+One of the aims of QML is to allow developers to write modular user-interface
+types which may be reused to build complex, interactive applications which
+are highly maintainable.  Reusable components and dynamic object instantiation
+are fundamental building blocks which allow this paradigm to be realised in
+Qt Quick.
+
+\section2 Defining Reusable Components
+
+Being able to define reusable components is a fundamental feature of the QML
+language.  Qt Quick extends on this, by providing some types which make the
+dynamic construction of reusable components simpler and more efficient.  Please
+see the documentation on \l{qtquick-concepts-components.html}
+{Defining Reusable Components} for more information on the topic.
+
+\section2 Dynamic Instantiation and Lazy Initialization
+
+Qt Quick also provides the Loader type which may be used in conjuction with a
+Component or a QML document to instantiate objects lazily and on-demand.
+Please see the \l{qtquick-performance.html}{performance guide} for more
+information on using dynamic instantiation and lazy initialization to improve
+application performance.
+
+*/