ownership of it unless the object has had its ownership previously
explicitly set (to QQmlEngine::CppOwnership).
-\section1 Data Provided In A Custom C++ Model
-
-Models can be defined in C++ and then made available to QML. This is useful
-for exposing existing C++ data models or otherwise complex datasets to QML.
-
-A C++ model class can be defined as a \l QStringList, a QObjectList or a
-\l QAbstractItemModel. The first two are useful for exposing simpler datasets,
-while QAbstractItemModel provides a more flexible solution for more complex
-models.
-
-\section2 QStringList-based Model
-
-A model may be a simple \l QStringList, which provides the contents of the list
-via the \e modelData role.
-
-Here is a ListView with a delegate that references its model item's
-value using the \c modelData role:
-
-\snippet examples/quick/modelviews/stringlistmodel/view.qml 0
-
-A Qt application can load this QML document and set the value of \c myModel
-to a QStringList:
-
-\snippet examples/quick/modelviews/stringlistmodel/main.cpp 0
-
-The complete example is available in Qt's \l {quick/modelviews/stringlistmodel}{examples/quick/modelviews/stringlistmodel} directory.
-
-\b{Note:} There is no way for the view to know that the contents of a QStringList
-have changed. If the QStringList changes, it will be necessary to reset
-the model by calling QQmlContext::setContextProperty() again.
-
-
-\section2 QObjectList-based model
-
-A list of QObject* values can also be used as a model. A QList<QObject*> provides
-the properties of the objects in the list as roles.
-
-The following application creates a \c DataObject class that with
-Q_PROPERTY values that will be accessible as named roles when a
-QList<DataObject*> is exposed to QML:
-
-\snippet examples/quick/modelviews/objectlistmodel/dataobject.h 0
-\dots 4
-\snippet examples/quick/modelviews/objectlistmodel/dataobject.h 1
-\codeline
-\snippet examples/quick/modelviews/objectlistmodel/main.cpp 0
-\dots
-
-The QObject* is available as the \c modelData property. As a convenience,
-the properties of the object are also made available directly in the
-delegate's context. Here, \c view.qml references the \c DataModel properties in
-the ListView delegate:
-
-\snippet examples/quick/modelviews/objectlistmodel/view.qml 0
-
-Note the use of the fully qualified access to the \c color property.
-The properties of the object are not replicated in the \c model
-object, since they are easily available via the \c modelData
-object.
-
-The complete example is available in Qt's \l {quick/modelviews/objectlistmodel}{examples/quick/modelviews/objectlistmodel} directory.
-
-Note: There is no way for the view to know that the contents of a QList
-have changed. If the QList changes, it will be necessary to reset
-the model by calling QQmlContext::setContextProperty() again.
-
-
-\section2 QAbstractItemModel
-
-A model can be defined by subclassing QAbstractItemModel. This is the
-best approach if you have a more complex model that cannot be supported
-by the other approaches. A QAbstractItemModel can also automatically
-notify a QML view when the model data has changed.
-
-The roles of a QAbstractItemModel subclass can be exposed to QML by calling
-QAbstractItemModel::setRoleNames(). The default role names set by Qt are:
-
-\table
-\header
-\li Qt Role
-\li QML Role Name
-\row
-\li Qt::DisplayRole
-\li display
-\row
-\li Qt::DecorationRole
-\li decoration
-\endtable
-
-Here is an application with a QAbstractListModel subclass named \c AnimalModel
-that has \e type and \e size roles. It calls QAbstractItemModel::setRoleNames() to set the
-role names for accessing the properties via QML:
-
-\snippet examples/quick/modelviews/abstractitemmodel/model.h 0
-\dots
-\snippet examples/quick/modelviews/abstractitemmodel/model.h 1
-\dots
-\snippet examples/quick/modelviews/abstractitemmodel/model.h 2
-\codeline
-\snippet examples/quick/modelviews/abstractitemmodel/model.cpp 0
-\codeline
-\snippet examples/quick/modelviews/abstractitemmodel/main.cpp 0
-\dots
-
-This model is displayed by a ListView delegate that accesses the \e type and \e size
-roles:
-
-\snippet examples/quick/modelviews/abstractitemmodel/view.qml 0
-
-QML views are automatically updated when the model changes. Remember the model
-must follow the standard rules for model changes and notify the view when
-the model has changed by using QAbstractItemModel::dataChanged(),
-QAbstractItemModel::beginInsertRows(), etc. See the \l {Model subclassing reference} for
-more information.
-
-The complete example is available in Qt's \l {quick/modelviews/abstractitemmodel}{examples/quick/modelviews/abstractitemmodel} directory.
-
-QAbstractItemModel presents a hierarchy of tables, but the views currently provided by QML
-can only display list data.
-In order to display child lists of a hierarchical model
-the VisualDataModel element provides several properties and functions for use
-with models of type QAbstractItemModel:
-
-\list
-\li \e hasModelChildren role property to determine whether a node has child nodes.
-\li \l VisualDataModel::rootIndex allows the root node to be specified
-\li \l VisualDataModel::modelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex
-\li \l VisualDataModel::parentModelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex
-\endlist
-
-\section2 Exposing C++ Data Models to QML
-
-The above examples use QQmlContext::setContextProperty() to set
-model values directly in QML components. An alternative to this is to
-register the C++ model class as a QML type (either
-\l{qtqml-registercpptypes.html}{directly} from a C++ entry-point, or within
-the initialization function of a \l{qtqml-modules-cppplugins.html}
-{QML C++ plugin}, as shown below). This would allow the model classes to be
-created directly as elements within QML:
-
-\table
-\row
-
-\li
-\code
-class MyModelPlugin : public QQmlExtensionPlugin
-{
-public:
- void registerTypes(const char *uri)
- {
- qmlRegisterType<MyModel>(uri, 1, 0,
- "MyModel");
- }
-}
-
-Q_EXPORT_PLUGIN2(mymodelplugin, MyModelPlugin);
-\endcode
-
-\li
-\qml
-MyModel {
- id: myModel
- ListElement { someProperty: "some value" }
-}
-\endqml
-
-\qml
-ListView {
- width: 200; height: 250
- model: myModel
- delegate: Text { text: someProperty }
-}
-\endqml
-
-\endtable
-
-See \l {Tutorial: Extending QML with C++} for details on writing QML C++
-plugins.
-
-
-
****************************************************************************/
/*!
-\page qtqml-javascript-dynamicobjects.html
+\page qtqml-javascript-dynamicobjectcreation.html
\title Dynamic QML object creation from JavaScript
\brief instantiating and managing QML objects from JavaScript
-QML provides a number of ways to dynamically create and manage QML objects.
-The \l{Loader}, \l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView} elements
-all support dynamic object management. Objects can also be created and managed
-from C++, and this is the preferred method for hybrid QML/C++ applications
-(see \l{Exposing C++ Data to QML}).
-
QML also supports the dynamic creation of objects from within JavaScript
code. This is useful if the existing QML elements do not fit the needs of your
application, and there are no C++ components involved.
\list
\li \l{qtqml-javascript-expressions.html}{Using JavaScript Expressions with QML}
\li \l{qtqml-javascript-imports.html}{Importing JavaScript Files in QML Documents}
- \li \l{qtqml-javascript-dynamicobjects.html}{Dynamic QML Object Creation from JavaScript}
\li \l{qtqml-javascript-hostenvironment.html}{JavaScript Host Environment}
\list
\li \l{qtqml-javascript-qmlglobalobject.html}{QML Global Object}
****************************************************************************/
/*!
-\page qtquick-concepts-components.html
-\title Concepts - Reusable Components
+\page qtquick-appdevguide-components.html
+\title Defining Reusable Components
\brief Description of the concept and implementation of reusable UI components in Qt Quick
+############### This needs to be cleaned up to be really simple and talk more about
+"why" you want to make reusable components, and have concrete and practical examples on this,
+instead of having so much details on the "how" since that is now covered in the
+Qt QML syntax documentation. ########################
+
+
+############# Also need to rename this page to avoid using "components"? Or be very specific
+and define how this term is used. ############
+
+
+
One of the key concepts in QML is the ability to define your own QML components that suit
the purposes of your application. The standard \l{qtquick-qmltypereference.html}
{Qt Quick QML types} provide the essential components for creating a QML application;
\section1 Defining Custom QML Types For Re-use
+See \l{qtquick-appdevguide-components.html}{Defining Resuable Components}
+for more details.
+
*/
--- /dev/null
+/****************************************************************************
+**
+** 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-dynamicinstantiation-topic.html
+\title Important Concepts In Qt Quick - Dynamic and Lazy Instantiation
+\brief Overview of the dynamic and lazy instantiation concepts
+
+QML provides a number of ways to dynamically create and manage QML objects.
+The \l{Loader}, \l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView} elements
+all support dynamic object management.
+
+Objects can be created and deleted at runtime from JavaScript code. See
+\l{qtqml-javascript-dynamicobjectcreation.html}{Dynamic QML object creation from JavaScript}
+for more details.
+
+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.
+
+*/
+
For a simple overview of how the system can be used, see \l{Using the Qt Quick Particle System}.
- For details on the performance characteristics see \l{qtquick-concepts-particles-performance.html}{Qt Quick Particle System Performance}.
+ For details on the performance characteristics see \l{qtquick-particles-performance.html}{Qt Quick Particle System Performance}.
*/
/*!
- \page qtquick-concepts-effects-particles.html
+ \page qtquick-effects-particles.html
\inqmlmodule QtQuick.Particles 2.0
\title Using the Qt Quick Particle System
*/
/*!
- \page qtquick-concepts-particles-performance.html
+ \page qtquick-particles-performance.html
\inqmlmodule QtQuick 2.0
\title Particle System Performance Guide
/*!
\group qtquick-shaders
-\page qtquick-concepts-effects-shaders.html
+\page qtquick-effects-shaders.html
\title Qt Quick Shader Effects
\brief For applying OpenGL vertex and fragment shaders to rectangles
/*!
\group qtquick-images-sprites
\ingroup qml-features
-\page qtquick-concepts-effects-sprites.html
+\page qtquick-effects-sprites.html
\title Sprite Animations
\brief Sprite-based animations with flexible transitioning
--- /dev/null
+/****************************************************************************
+**
+** 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-effects-topic.html
+\title Important Concepts In Qt Quick - Graphical Effects
+\brief Overview of graphical effects concepts
+
+\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.
+
+\section1 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-effects-transformations.html}
+{Qt Quick Transformation Types}.
+
+\section1 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-effects-shaders.html}
+{Qt Quick Shader Effects}.
+
+\section1 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-effects-particles.html}{Qt Quick Particle System}.
+
+\section1 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-effects-sprites.html}{Sprite Animations}.
+
+
+*/
+
/*!
\group qtquick-transformations
-\page qtquick-concepts-effects-transformations.html
+\page qtquick-effects-transformations.html
\title Qt Quick Transformation Types
\brief Types for applying transformations to visual types
--- /dev/null
+/****************************************************************************
+**
+** 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-eventinterceptors-topic.html
+\title Important Concepts In Qt Quick - Event Interceptors
+\brief Overview of event interceptor concepts
+
+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.
+
+\section1 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.
+
+\section1 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.
+
+\section1 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 Timer-Based Events
+
+*/
+
****************************************************************************/
/*!
-\page qtquick-concepts-input-focus.html
+\page qtquick-input-focus.html
\ingroup qml-features
\title Keyboard Focus in Qt Quick
\brief handling keyboard focus
****************************************************************************/
/*!
-\page qtquick-concepts-input-mouseevents.html
+\page qtquick-input-mouseevents.html
\ingroup QML Features
\title Mouse Events
\brief handling mouse events in Qt Quick
/*!
\group qtquick-text
-\page qtquick-concepts-input-text.html
+\page qtquick-input-textinput.html
\title Qt Quick Text Input Handling and Validators
\brief Text input and validation
--- /dev/null
+/****************************************************************************
+**
+** 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-input-topic.html
+\title Important Concepts In Qt Quick - User Input
+\brief Overview of user input concepts
+
+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.
+
+\section1 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).
+
+\section1 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.
+
+\section1 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-input-textinput.html}{text input} for
+in-depth information on the topic.
+
+\section1 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-input-mouseevents.html}
+{mouse events in Qt Quick} for more information on the topic.
+
+\section1 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-input-focus.html}{keyboard focus in Qt Quick} for more
+information on this topic.
+
+*/
+
--- /dev/null
+/****************************************************************************
+**
+** 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-modelviewsdata-cppmodels.html
+\title Using C++ Models with QtQuick Views
+\brief using QtQuick views with models defined in C++
+
+
+\section1 Data Provided In A Custom C++ Model
+
+Models can be defined in C++ and then made available to QML. This is useful
+for exposing existing C++ data models or otherwise complex datasets to QML.
+
+A C++ model class can be defined as a \l QStringList, a QObjectList or a
+\l QAbstractItemModel. The first two are useful for exposing simpler datasets,
+while QAbstractItemModel provides a more flexible solution for more complex
+models.
+
+\section2 QStringList-based Model
+
+A model may be a simple \l QStringList, which provides the contents of the list
+via the \e modelData role.
+
+Here is a ListView with a delegate that references its model item's
+value using the \c modelData role:
+
+\snippet examples/quick/modelviews/stringlistmodel/view.qml 0
+
+A Qt application can load this QML document and set the value of \c myModel
+to a QStringList:
+
+\snippet examples/quick/modelviews/stringlistmodel/main.cpp 0
+
+The complete example is available in Qt's \l {quick/modelviews/stringlistmodel}{examples/quick/modelviews/stringlistmodel} directory.
+
+\b{Note:} There is no way for the view to know that the contents of a QStringList
+have changed. If the QStringList changes, it will be necessary to reset
+the model by calling QQmlContext::setContextProperty() again.
+
+
+\section2 QObjectList-based model
+
+A list of QObject* values can also be used as a model. A QList<QObject*> provides
+the properties of the objects in the list as roles.
+
+The following application creates a \c DataObject class that with
+Q_PROPERTY values that will be accessible as named roles when a
+QList<DataObject*> is exposed to QML:
+
+\snippet examples/quick/modelviews/objectlistmodel/dataobject.h 0
+\dots 4
+\snippet examples/quick/modelviews/objectlistmodel/dataobject.h 1
+\codeline
+\snippet examples/quick/modelviews/objectlistmodel/main.cpp 0
+\dots
+
+The QObject* is available as the \c modelData property. As a convenience,
+the properties of the object are also made available directly in the
+delegate's context. Here, \c view.qml references the \c DataModel properties in
+the ListView delegate:
+
+\snippet examples/quick/modelviews/objectlistmodel/view.qml 0
+
+Note the use of the fully qualified access to the \c color property.
+The properties of the object are not replicated in the \c model
+object, since they are easily available via the \c modelData
+object.
+
+The complete example is available in Qt's \l {quick/modelviews/objectlistmodel}{examples/quick/modelviews/objectlistmodel} directory.
+
+Note: There is no way for the view to know that the contents of a QList
+have changed. If the QList changes, it will be necessary to reset
+the model by calling QQmlContext::setContextProperty() again.
+
+
+\section2 QAbstractItemModel
+
+A model can be defined by subclassing QAbstractItemModel. This is the
+best approach if you have a more complex model that cannot be supported
+by the other approaches. A QAbstractItemModel can also automatically
+notify a QML view when the model data has changed.
+
+The roles of a QAbstractItemModel subclass can be exposed to QML by calling
+QAbstractItemModel::setRoleNames(). The default role names set by Qt are:
+
+\table
+\header
+\li Qt Role
+\li QML Role Name
+\row
+\li Qt::DisplayRole
+\li display
+\row
+\li Qt::DecorationRole
+\li decoration
+\endtable
+
+Here is an application with a QAbstractListModel subclass named \c AnimalModel
+that has \e type and \e size roles. It calls QAbstractItemModel::setRoleNames() to set the
+role names for accessing the properties via QML:
+
+\snippet examples/quick/modelviews/abstractitemmodel/model.h 0
+\dots
+\snippet examples/quick/modelviews/abstractitemmodel/model.h 1
+\dots
+\snippet examples/quick/modelviews/abstractitemmodel/model.h 2
+\codeline
+\snippet examples/quick/modelviews/abstractitemmodel/model.cpp 0
+\codeline
+\snippet examples/quick/modelviews/abstractitemmodel/main.cpp 0
+\dots
+
+This model is displayed by a ListView delegate that accesses the \e type and \e size
+roles:
+
+\snippet examples/quick/modelviews/abstractitemmodel/view.qml 0
+
+QML views are automatically updated when the model changes. Remember the model
+must follow the standard rules for model changes and notify the view when
+the model has changed by using QAbstractItemModel::dataChanged(),
+QAbstractItemModel::beginInsertRows(), etc. See the \l {Model subclassing reference} for
+more information.
+
+The complete example is available in Qt's \l {quick/modelviews/abstractitemmodel}{examples/quick/modelviews/abstractitemmodel} directory.
+
+QAbstractItemModel presents a hierarchy of tables, but the views currently provided by QML
+can only display list data.
+In order to display child lists of a hierarchical model
+the VisualDataModel element provides several properties and functions for use
+with models of type QAbstractItemModel:
+
+\list
+\li \e hasModelChildren role property to determine whether a node has child nodes.
+\li \l VisualDataModel::rootIndex allows the root node to be specified
+\li \l VisualDataModel::modelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex
+\li \l VisualDataModel::parentModelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex
+\endlist
+
+\section2 Exposing C++ Data Models to QML
+
+The above examples use QQmlContext::setContextProperty() to set
+model values directly in QML components. An alternative to this is to
+register the C++ model class as a QML type (either
+\l{qtqml-registercpptypes.html}{directly} from a C++ entry-point, or within
+the initialization function of a \l{qtqml-modules-cppplugins.html}
+{QML C++ plugin}, as shown below). This would allow the model classes to be
+created directly as elements within QML:
+
+\table
+\row
+
+\li
+\code
+class MyModelPlugin : public QQmlExtensionPlugin
+{
+public:
+ void registerTypes(const char *uri)
+ {
+ qmlRegisterType<MyModel>(uri, 1, 0,
+ "MyModel");
+ }
+}
+
+Q_EXPORT_PLUGIN2(mymodelplugin, MyModelPlugin);
+\endcode
+
+\li
+\qml
+MyModel {
+ id: myModel
+ ListElement { someProperty: "some value" }
+}
+\endqml
+
+\qml
+ListView {
+ width: 200; height: 250
+ model: myModel
+ delegate: Text { text: someProperty }
+}
+\endqml
+
+\endtable
+
+See \l {Tutorial: Extending QML with C++} for details on writing QML C++
+plugins.
+
+
+*/
+
+
****************************************************************************/
/*!
-\page qtquick-concepts-data-localstorage.html
+\page qtquick-modelviewsdata-localstorage.html
\title Local Storage
\brief SQL storage for Qt Quick
****************************************************************************/
/*!
-\page qtquick-concepts-data-modelview.html
+\page qtquick-modelviewsdata-modelview.html
\title Models and Views in Qt Quick
\brief how to display and form data in Qt Quick
elements. In addition, models can be created with Qt C++ and then made
available to the \l{qtqml-cppclasses-engine.html}{QML engine} for use by
QML components. For information about creating these models, visit the
- \l{qtqml-cppintegration-data.html#data-provided-in-a-custom-c++-model}
- {exposing C++ models} and \l{qtqml-typesystem-topic.html#qml-object-types}
+ \l{qtquick-modelviewsdata-cppmodels.html}{Using C++ Models with QtQuick Views}
+ and \l{qtqml-typesystem-topic.html#qml-object-types}
{creating QML types} articles.
The use of positioner items to arrange items from a model is covered in
datasets to QML.
For information, visit the
- \l{qtqml-cppintegration-data.html#data-provided-in-a-custom-c++-model}
- {exposing C++ models} article.
+ \l{qtquick-modelviewsdata-cppmodels.html}{Using C++ Models with QtQuick Views}
+ article.
\section1 Repeaters
--- /dev/null
+/****************************************************************************
+**
+** 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-modelviewsdata-topic.html
+\title Important Concepts In Qt Quick - Data - Models, Views and Data Storage
+\brief Overview of the data, model and view concepts
+
+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.
+
+\section1 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-modelviewsdata-modelview.html}
+{Models and Views in Qt Quick}.
+
+\section1 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-modelviewsdata-localstorage.html}{Qt Quick local storage module}.
+
+*/
+
****************************************************************************/
/*!
-\page qtquick-concepts-positioning-anchors.html
+\page qtquick-positioning-anchors.html
\title Positioning with Anchors
\brief placing items with anchor properties
/*!
\group qtquick-positioners
-\page qtquick-concepts-positioning-layouts.html
+\page qtquick-positioning-layouts.html
\ingroup qml-features
\title Item Layouts
****************************************************************************/
/*!
-\page qtquick-concepts-positioning-righttoleft.html
+\page qtquick-positioning-righttoleft.html
\ingroup qml-features
\title Right-to-left User Interfaces
\brief switching text flow and layout
****************************************************************************/
/*!
-\page qtquick-concepts-positioning.html
-\title Concepts - Positioning
-\brief Description of the concept of visual object positioning in Qt Quick
+\page qtquick-positioning-topic.html
+\title Important Concepts In Qt Quick - Positioning
+\brief Overview of positioning concepts
+
+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.
-This page describes the concept of positioning visual user-interface elements
-and the various elements which Qt Quick provides to support precise
-positioning, and the ways in which positioning in Qt Quick can be automated.
\section1 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.
+
In any user-interface, the visual elements exist at a particular location in
the screen coordinates at any instant in time. While fluidly animated and
dynamic user-interfaces are a major focus of Qt Quick, statically-positioned
documented in proceeding sections.
In Qt Quick, every visual object is positioned within the
-\l{qtquick-concepts-visual-coordinates.html}{coordinate system}
+\l{qtquick-visual-coordinates.html}{coordinate system}
provided by the Qt Quick visual canvas. As described in that document, the
x and y coordinates of a visual object are relative to those of its visual
parent, with the top-left corner have the value [0, 0].
\section1 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.
+
The position and dimensions of a visual object can also be set through property
bindings. This has the advantage that the values will automatically be updated
as the dependencies of the bindings change. For example, the width of one
layouts, it should be noted that there is some performance cost associated with
them, and where possible, pristine Anchor layouts should be preferred.
+
\section1 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.
+
A visual object can be thought of as having various anchor-points (or more
correctly, anchor-lines). Other items can be anchored to those points, which
means that as any object changes, the other objects which are anchored to it
will adjust automatically to maintain the anchoring.
Qt Quick provides anchors as a top-level concept. See the documentation about
-\l{qtquick-concepts-positioning-anchors.html}{positioning with anchors}
+\l{qtquick-positioning-anchors.html}{positioning with anchors}
for in-depth information on the topic.
It is important to note that anchor-based layouts are generally far more
anchoring and bindings (either on position-related [x,y] properties or on
dimension-related [width,height] properties) to determine the position.
-\section1 Pre-defined Layouts
+\section1 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.
There are many well-known layouts which work well in user-interfaces, such as
grids and lists, rows and columns. Qt Quick supports these sort of pre-defined
layouts, which can often be more performant to draw than anchor or
binding-based layouts. See the documentation on
-\l{qtquick-concepts-positioning-layouts.html}{layout elements} for more
+\l{qtquick-positioning-layouts.html}{layout elements} for more
information about utilizing pre-defined layouts.
+
+
\section1 Right-To-Left Support
The directionality of the written form of a language often has a great impact
as well as right-to-left text layouts.
Please see the documentation about
-\l{qtquick-concepts-positioning-righttoleft.html}
+\l{qtquick-positioning-righttoleft.html}
{right-to-left support in Qt Quick} for in-depth information on the topic.
+
*/
+
/*!
\group qtquick-transitions-animations
-\page qtquick-concepts-statesanimations-animations.html
+\page qtquick-statesanimations-animations.html
\title Animation and Transitions In Qt Quick
\brief the animation system in Qt Quick
****************************************************************************/
/*!
-\page qtquick-qmltypereference-behaviors.html
+\page qtquick-statesanimations-behaviors.html
\title Using Qt Quick Behaviors with States
\brief animating property changes with behaviors
****************************************************************************/
/*!
-\group qtquick--states
-\page qtquick-concepts-statesanimations-states.html
+\group qtquick-states
+\page qtquick-statesanimations-states.html
\title Qt Quick States
\brief Creating and setting states
State changes induce abrupt value changes. The \l Transition element allow
smoother changes during state changes. In transitions, animations and
interpolation behaviors are definable. The
-\l{qtquick-concepts-statesanimations-animations.html}
+\l{qtquick-statesanimations-animations.html}
{Animation and Transitions} article has more information about creating state
animations.
demonstrates how to declare a basic set of states and apply animated
transitions between them.
-\l{qtquick-qmltypereference-behaviors.html}{Using QML Behaviors with States}
+\l{qtquick-statesanimations-behaviors.html}{Using QML Behaviors with States}
explains a common problem when using Behaviors to animate state changes.
\section1 State Fast Forwarding
****************************************************************************/
/*!
-\page qtquick-concepts-statesanimations.html
+\page qtquick-statesanimations-topic.html
\title Concepts - States And Animations
\brief Description of the concepts of states, transitions and animations in Qt Quick
+In any modern user-interface, transitioning between states and animating
+the user-interface is highly beneficial. These are first-class concepts in
+Qt Quick.
+
This page describes the concept of states, state transitions, and property
animations. It details which concepts are important and why, and how those
concepts interrelate. It also provides links to in-depth detail about the QML
Qt Quick provides a \c{State} element with properties which define its semantics
and can be used to trigger behavior or animations. See the documentation about
-\l{qtquick-concepts-statesanimations-states.html}{Qt Quick States} for more
+\l{qtquick-statesanimations-states.html}{Qt Quick States} for more
information.
\section1 Transitions
Qt Quick provides the \c{Transition} element which has properties which define
what will occur when the application changes from one state to another. See
the documentation on
-\l{qtquick-concepts-statesanimations-animations.html#transitions-during-state-changes}
+\l{qtquick-statesanimations-animations.html#transitions-during-state-changes}
{Transitions during State Changes} for more information about transitions.
\section1 Animations
These types of animations are supported in Qt Quick through various animation
and transition elements. See the documentation on
-\l{qtquick-concepts-statesanimations-animations.html}
+\l{qtquick-statesanimations-animations.html}
{Animations and Transitions In Qt Quick} for information about these elements
and how to use them.
This type of animation is supported in Qt Quick with the \c{Behavior} element
through the \tt{"Behavior on <Property>"} syntax. Please see the documentation
about
-\l{qtquick-concepts-statesanimations-animations.html#default-animation-as-behaviors}
+\l{qtquick-statesanimations-animations.html#default-animation-as-behaviors}
{default property animation behaviors} for more information about the Behavior
element and how to use it.
It is important to note, however, that using default property animations
(using Behavior elements) as well as state-transition animations can sometimes
results in undefined behavior occurring. Please see the documentation about
-\l{qtquick-qmltypereference-behaviors.html}
+\l{qtquick-statesanimations-behaviors.html}
{using Qt Quick Behaviors with States} for more information about this topic.
\section1 Animated Sprites
The concept of animated sprites is separate to the concept of animations as
used elsewhere on this page. If you want to create or use an animated image
or sprite, please see the documentation about
-\l{qtquick-concepts-effects-sprites.html}{sprite animations}.
+\l{qtquick-effects-sprites.html}{sprite animations}.
*/
+++ /dev/null
-/****************************************************************************
-**
-** 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.
-
-*/
****************************************************************************/
/*!
-\page qtquick-concepts-visual-coordinates.html
+\page qtquick-visualcanvas-coordinates.html
\title Concepts - Visual Coordinates in Qt Quick
\brief Description of the concept of visual coordinates in Qt Quick
/*!
\title Qt Quick Scene Graph
-\page qtquick-concepts-visual-scenegraph.html
+\page qtquick-visualcanvas-scenegraph.html
\section1 What is a Scene Graph?
--- /dev/null
+/****************************************************************************
+**
+** 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-visualcanvas-topic.html
+\title Important Concepts In Qt Quick - The Visual Canvas
+\brief Overview of visual canvas concepts
+
+The visual canvas provided by the Qt Quick is a two dimensional canvas with
+z-ordering.
+
+\section1 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-visualcanvas-coordinates.html}{Coordinate System} for
+in-depth information about the coordinate system utilized by Qt Quick.
+
+\section1 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-visualcanvas-visualparent.html}
+{Visual Parent}for more in-depth information on the topic.
+
+\section1 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-visualcanvas-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.
+
+*/
****************************************************************************/
/*!
-\page qtquick-concepts-visual-parent.html
+\page qtquick-visualcanvas-visualparent.html
\title Concepts - Visual Parent in Qt Quick
\brief Description of the concept of visual parent in Qt Quick
****************************************************************************/
/*!
-\page qtquick-concepts-interceptors.html
-\title Concepts - Event Interceptors
-\brief Description of the concept of property interception in Qt Quick
+\page qtquick-visualtypes-topic.html
+\title Important Concepts In Qt Quick - Visual Types
+\brief Overview of visual type concepts
-\section1 Animating Property Assignments
+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.
-\section1 Dynamic Bindings
+See the \l{qtquick-qmltypereference.html}{Qt Quick QML type reference} for the
+complete list of visual object types provided by Qt Quick.
-\section1 Dynamic Signal Connections
+*/
-\section1 Timer-Based Events
-*/
In summary, Qt Quick provides a library of visual types to allow building a
user-interface, and the C++ API to instantiate and interact with it.
-\section1 Qt Quick Module Documentation
+\section1 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.
\list
+\li \l{qtquick-visualcanvas-topic.html}{The Visual Canvas}
+\li \l{qtquick-positioning-topic.html}{Positioning}
+\li \l{qtquick-input-topic.html}{User Input}
+\li \l{qtquick-eventinterceptors-topic.html}{Event Interceptors}
+\li \l{qtquick-statesanimations-topic.html}{States, Transitions And Animations}
+\li \l{qtquick-modelviewsdata-topic.html}{Data - Models, Views and Data Storage}
+\li \l{qtquick-effects-topic.html}{Graphical Effects And Particles}
+\li \l{qtquick-dynamicinstantiation-topic.html}{Dynamic and Lazy Instantiation}
+\endlist
- \li \l{qtquick-concepts-topic.html}{Important Concepts In Qt Quick}
- \list
- \li \l{qtquick-concepts-topic.html#the-visual-canvas}{The Visual Canvas}
- \li \l{qtquick-concepts-topic.html#positioning}{Positioning}
- \li \l{qtquick-concepts-topic.html#user-input}{User Input}
- \li \l{qtquick-concepts-topic.html#event-interceptors}{Event Interceptors}
- \li \l{qtquick-concepts-statesanimations.html}{States, Transitions And Animations}
- \li \l{qtquick-concepts-topic.html#data-models-views-and-data-storage}{Data - Models, Views and Data Storage}
- \li \l{qtquick-concepts-topic.html#graphical-effects-and-particles}{Graphical Effects And Particles}
- \li \l{qtquick-concepts-topic.html#defining-and-using-modular-components}{Defining And Using Modular Components}
+When using the QtQuick module, you will need to know how to write QML
+applications using the QML language. In particular, you should have a grasp
+of the \l{qtquick-quickstart-basics.html}{QML Basics} and
+\l{qtquick-quickstart-essentials.html}{QML Essentials} from the
+\l{qtquick-applicationdevelopers.html}{QML Application Developer Resources}.
+To find out more about using the QML language, see the \l{Qt QML Module Documentation}.
- \endlist
+
+\section1 Qt Quick Module Documentation
+
+\list
\li \l{qtquick-qmltypereference.html}{QML Types Provided By The Qt Quick Module}
\list
projects / profile / ivi / qtdeclarative.git / commitdiff