From b523301a668e6c6cc5fc93440842ad063066f12b Mon Sep 17 00:00:00 2001 From: Chris Adams Date: Tue, 17 Jul 2012 12:19:31 +1000 Subject: [PATCH] Add documentation about property value modifiers Previously, property value modifiers were only documented in QtQuick, when really they are a QtQml module / QML language feature. This commit also improves the QtQuick documentation for convenience types, and rearranges some links and content for improved consistency. Change-Id: Ic4dbe0b8bb85bdfbb8ac2f336c13c2960f8d1842 Reviewed-by: Bea Lam --- src/qml/doc/src/cppclasses/topic.qdoc | 10 ++ src/qml/doc/src/cppclasses/valuesource.qdoc | 36 ++++++++ src/qml/doc/src/qtqml.qdoc | 3 + src/qml/doc/src/typesystem/topic.qdoc | 50 +++++++++++ src/quick/doc/src/concepts/convenience/topic.qdoc | 87 ++++++++++++++++++++ .../src/concepts/dynamicinstantiation/topic.qdoc | 48 ----------- .../doc/src/concepts/eventinterceptors/topic.qdoc | 69 ---------------- .../doc/src/concepts/statesanimations/topic.qdoc | 30 ++++--- src/quick/doc/src/qmltypereference.qdoc | 34 +++----- src/quick/doc/src/qtquick.qdoc | 20 ++--- 10 files changed, 224 insertions(+), 163 deletions(-) create mode 100644 src/qml/doc/src/cppclasses/valuesource.qdoc create mode 100644 src/quick/doc/src/concepts/convenience/topic.qdoc delete mode 100644 src/quick/doc/src/concepts/dynamicinstantiation/topic.qdoc delete mode 100644 src/quick/doc/src/concepts/eventinterceptors/topic.qdoc diff --git a/src/qml/doc/src/cppclasses/topic.qdoc b/src/qml/doc/src/cppclasses/topic.qdoc index 64f02c9..93d7bb3 100644 --- a/src/qml/doc/src/cppclasses/topic.qdoc +++ b/src/qml/doc/src/cppclasses/topic.qdoc @@ -77,4 +77,14 @@ See \l{qtqml-cppclasses-expression.html} {Qt QML Module C++ Classes - QQmlExpression} for in depth information about QQmlExpression. +\section1 The QQmlPropertyValueSource Class + +The QQmlPropertyValueSource class is an abstract class which may be inherited +to provide unique \l{qtqml-typesystem-topic.html#property-modifier-types} +{property value sources}. + +See \l{qtqml-cppclasses-valuesource.html} +{Qt QML Module C++ Classes - QQmlPropertyValueSource} for in depth information +about QQmlPropertyValueSource. + */ diff --git a/src/qml/doc/src/cppclasses/valuesource.qdoc b/src/qml/doc/src/cppclasses/valuesource.qdoc new file mode 100644 index 0000000..92c8c3a --- /dev/null +++ b/src/qml/doc/src/cppclasses/valuesource.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** 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 qtqml-cppclasses-valuesource.html +\title Qt QML Module C++ Classes - QQmlPropertyValueSource +\brief Description of QQmlPropertyValueSource + +QQmlPropertyValueSource may be inherited by client-defined classes to provide +a custom property value source kind of property value modifier. + +*/ diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc index 7bb3453..be4232e 100644 --- a/src/qml/doc/src/qtqml.qdoc +++ b/src/qml/doc/src/qtqml.qdoc @@ -75,6 +75,8 @@ types, animation classes, and canvas integration) for the QML language. \li \l{qtqml-cppclasses-engine.html}{QQmlEngine} \li \l{qtqml-cppclasses-context.html}{QQmlContext} \li \l{qtqml-cppclasses-component.html}{QQmlComponent} + \li \l{qtqml-cppclasses-expression.html}{QQmlExpression} + \li \l{qtqml-cppclasses-valuesource.html}{QQmlPropertyValueSource} \endlist \li \l{qtqml-typesystem-topic.html}{The QML Type System} @@ -86,6 +88,7 @@ types, animation classes, and canvas integration) for the QML language. \li \l{qtqml-documents-definetypes.html}{Defining Object Types from QML} \li \l{qtqml-cppintegration-registercpptypes.html}{Defining Object Types from C++} \endlist + \li \l{qtqml-typesystem-topic.html#property-modifier-types}{Property Modifier Types} \endlist \li \l{qtqml-modules-topic.html}{QML Modules} diff --git a/src/qml/doc/src/typesystem/topic.qdoc b/src/qml/doc/src/typesystem/topic.qdoc index 1de87b5..e128735 100644 --- a/src/qml/doc/src/typesystem/topic.qdoc +++ b/src/qml/doc/src/typesystem/topic.qdoc @@ -98,4 +98,54 @@ re-used in other QML documents. See the documentation about \l{qtqml-typesystem-objecttypes.html}{object types in the QML type system} for in-depth information about object types. +\section1 Property Modifier Types + +A property modifier type is a special kind of QML object type. A property +modifier type instance affects a property (of a QML object instance) which it +is applied to. There are two different kinds of property modifier types: +\list +\li property value write interceptors +\li property value sources +\endlist + +A property value write interceptor can be used to filter or modify values as +they are written to properties. Currently, the only supported property +value write interceptor is the \l Behavior type provided by the \c QtQuick +import. + +A property value source can be used to automatically update the value of a +property over time. Clients can define their own property value source types. +The various \l{qtquick-statesanimations-animations.html}{property animation} +types provided by the \c QtQuick import are examples of property value +sources. + +Property modifier type instances can be created and applied to a property of +a QML object through the " on " syntax, as the +following example shows: + +\qml +import QtQuick 2.0 + +Item { + width: 400 + height: 50 + + Rectangle { + width: 50 + height: 50 + color: "red" + + NumberAnimation on x { + from: 0 + to: 350 + loops: Animation.Infinite + duration: 2000 + } + } +} +\endqml + +See the documentation on \l QQmlPropertyValueSource for information about how +to define your own property value source types. + */ diff --git a/src/quick/doc/src/concepts/convenience/topic.qdoc b/src/quick/doc/src/concepts/convenience/topic.qdoc new file mode 100644 index 0000000..ad70b9a --- /dev/null +++ b/src/quick/doc/src/concepts/convenience/topic.qdoc @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** 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-convenience-topic.html +\title Important Concepts In Qt Quick - Convenience Types +\brief Overview of the convenience types for QML core features + +In a highly dynamic user interface, the application developer will often wish +to react to events and trigger various response logic. QML has built-in +support for these concepts through bindings, signals and signal handlers, and +dynamic object instantiation, but Qt Quick expands upon the support +provided by the language with various convenience types. + +\section1 Dynamic Object Instantiation + +QML provides a number of ways to dynamically create and manage QML objects. + +Objects can be created dynamically from within imperative JavaScript code +in various ways. See \l{qtqml-javascript-dynamicobjectcreation.html} +{Dynamic QML object creation from JavaScript} for more details. + +Qt Quick provides the \l{Loader}, \l{Repeater}, \l{ListView}, \l{GridView} and +\l{PathView} types which also support dynamic object management, and provide +a declarative API. + +Please see the \l{qtquick-performance.html}{performance guide} for more +information on using dynamic instantiation and lazy initialization to improve +application performance. + +\section1 Dynamic Bindings + +Assigning binding expressions to properties is a fundamental concept of QML, +and Qt Quick extends upon the idea with the \l Binding type. While bindings +are typically specified as property initialization assignments, the \l Binding +type allows the target of a binding to be defined explicitly and separately +from the definition of the binding expression itself. +By declaring a \l Binding instance, the client can dynamically bind properties +from arbitrary objects at run-time, and can modify the binding target when +required (or when it becomes available). + +\section1 Dynamic Signal Connections + +QML supports dynamic signal connections through a signal's \c{connect()} +method. The QtQuick module provides the convenience \l Connections type which +allows setting up a signal connection involving an object which isn't part of +the static object hierarchy. It also allows the connection to be dynamically +retargeted at runtime, which allows an application to process different signal +notifications with different functions depending on the program state. + +By declaring a \l Connections instance, the client can dynamically cause +signals emitted by one object to trigger methods of another object, and can +modify the connection target when required (or when it becomes available). + +\section1 Timer-Based Events + +Another common use-case is to trigger functionality some specified period of +time after a particular event occurs. These sort of timer-based triggers are +supported in Qt Quick through the \l Timer type. Both single-shot and +recurring timers are supported. + +*/ + diff --git a/src/quick/doc/src/concepts/dynamicinstantiation/topic.qdoc b/src/quick/doc/src/concepts/dynamicinstantiation/topic.qdoc deleted file mode 100644 index 4040a63..0000000 --- a/src/quick/doc/src/concepts/dynamicinstantiation/topic.qdoc +++ /dev/null @@ -1,48 +0,0 @@ -/**************************************************************************** -** -** 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. - -*/ - diff --git a/src/quick/doc/src/concepts/eventinterceptors/topic.qdoc b/src/quick/doc/src/concepts/eventinterceptors/topic.qdoc deleted file mode 100644 index f6d2e7f..0000000 --- a/src/quick/doc/src/concepts/eventinterceptors/topic.qdoc +++ /dev/null @@ -1,69 +0,0 @@ -/**************************************************************************** -** -** 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 - -*/ - diff --git a/src/quick/doc/src/concepts/statesanimations/topic.qdoc b/src/quick/doc/src/concepts/statesanimations/topic.qdoc index 8ca02fd..25b0958 100644 --- a/src/quick/doc/src/concepts/statesanimations/topic.qdoc +++ b/src/quick/doc/src/concepts/statesanimations/topic.qdoc @@ -89,22 +89,28 @@ and transition elements. See the documentation on {Animations and Transitions In Qt Quick} for information about these elements and how to use them. -Animations are not only related to states and transitions between states; for + +\section1 Animating Property Assignments + +Animations are not only related to states and transitions between states. For example, an animation might be triggered by other events, which are not -associated with a distinct state. It is often beneficial to always animate -changes to certain properties of visual items, regardless of the cause of the -change (for example, opacity effects). +associated with a distinct state. + +It is often beneficial to always animate changes to certain properties of +visual items, regardless of the cause of the change (for example, opacity +effects). Qt Quick provides the \l Behavior type which allows the client to +specify animation behavior for changes to properties. The \l Behavior type +is an example of a QML object +\l{qtqml-typesystem-topic.html#property-modifier-types}{property modifier}. -This type of animation is supported in Qt Quick with the \c{Behavior} element -through the \tt{"Behavior on "} syntax. Please see the documentation -about +Please see the documentation about \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. +{default property animations} for more information about using the \l Behavior +element to provide default property change animations. -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 +It is important to note, that using default property animations (via the +\l Behavior type) in combination with state-transition animations can sometimes +result in undefined behavior occurring. Please see the documentation about \l{qtquick-statesanimations-behaviors.html} {using Qt Quick Behaviors with States} for more information about this topic. diff --git a/src/quick/doc/src/qmltypereference.qdoc b/src/quick/doc/src/qmltypereference.qdoc index def84a3..a9ea971 100644 --- a/src/quick/doc/src/qmltypereference.qdoc +++ b/src/quick/doc/src/qmltypereference.qdoc @@ -177,16 +177,7 @@ Visual object transformations \li \l {Translate} - Assigns item translation behaviors \endlist -\section1 Interceptors - -\list -\li \l {Connections} - Explicitly connects signals and signal handlers -\li \l {Binding} - Binds any value to any property -\li \l {Timer} - Provides timed triggers -\li \l {Behavior} - Triggers animations when a property value is set -\endlist - -\section1 Model/View Types and Data Storage and Access +\section1 Model/View Types And Data Storage And Access Models And Model Data \list @@ -223,6 +214,16 @@ Data Storage \li The \l{QtQuick.Particles 2} module provides a set of Particle System types for QtQuick 2 \endlist +\section1 Convenience Types + +\list +\li \l {Loader} - Eases on-demand loading of items or components +\li \l {Connections} - Explicitly connects signals and signal handlers +\li \l {Binding} - Binds any value to any property +\li \l {Timer} - Provides timed triggers +\li \l {WorkerScript} - Enables the use of threads in a Qt Quick application +\endlist + \section1 Canvas (similar to HTML5 canvas) \list @@ -234,17 +235,4 @@ Data Storage \li \l {TextMetrics} - Provides text and font measurement data for use in a Canvas \endlist -\section1 Dynamic Instantiation Enablers - -\list -\li \l {QML::Component} - Provides a type-instance factory allowing dynamic instantiation -\li \l {Loader} - Controls the loading of items or components -\endlist - -\section1 Threading - -\list -\li \l {WorkerScript} - Enables the use of threads in a Qt Quick application -\endlist - */ diff --git a/src/quick/doc/src/qtquick.qdoc b/src/quick/doc/src/qtquick.qdoc index 3b980c5..a5900ca 100644 --- a/src/quick/doc/src/qtquick.qdoc +++ b/src/quick/doc/src/qtquick.qdoc @@ -53,13 +53,12 @@ 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-positioning-topic.html}{Positioning} +\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} +\li \l{qtquick-effects-topic.html}{Particles And Graphical Effects} +\li \l{qtquick-convenience-topic.html}{Convenience Types} \endlist When using the QtQuick module, you will need to know how to write QML @@ -79,17 +78,16 @@ To find out more about using the QML language, see the \l{Qt QML Module Document \li \l{qtquick-qmltypereference.html#visual-types}{Visual Types} \li \l{qtquick-qmltypereference.html#user-input-types}{User Input Types} \li \l{qtquick-qmltypereference.html#positioning}{Positioning} - \li \l{qtquick-qmltypereference.html#states-transitions-and-animations}{States, Transitions and Animations} - \li \l{qtquick-qmltypereference.html#interceptors}{Interceptors} - \li \l{qtquick-qmltypereference.html#model-view-types-and-data-storage-and-access}{Model/View Types and Data Storage and Access} - \li \l{qtquick-qmltypereference.html#particles-and-graphical-effects}{Particles and Graphical Effects} + \li \l{qtquick-qmltypereference.html#states-transitions-and-animations}{States, Transitions And Animations} + \li \l{qtquick-qmltypereference.html#model-view-types-and-data-storage-and-access}{Model/View Types And Data Storage And Access} + \li \l{qtquick-qmltypereference.html#particles-and-graphical-effects}{Particles And Graphical Effects} + \li \l{qtquick-qmltypereference.html#convenience-types}{Convenience Types} \li \l{qtquick-qmltypereference.html#canvas-similar-to-html5-canvas}{Canvas (similar to HTML5 Canvas)} - \li \l{qtquick-qmltypereference.html#dynamic-instantiation-enablers}{Dynamic Instantiation Enablers} \endlist \li \l{qtquick-cppextensionpoints.html}{C++ Extension Points} \list - \li \l{qtquick-cppextensionpoints.html#user-defined-qquickitem-derived-types}{User-Defined QQuickItem-Derived Types} + \li \l{qtquick-cppextensionpoints.html#user-defined-qquickitem-derived-types}{Creating User-Defined QQuickItem-Derived Types} \li \l{qtquick-cppextensionpoints.html#scene-graph-related-classes}{Scene Graph-Related Classes} \endlist -- 1.7.2.5