diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/declarative/behaviors-and-states.qdoc | 206 | ||||
| -rw-r--r-- | doc/src/declarative/qtbinding.qdoc | 19 | ||||
| -rw-r--r-- | doc/src/platforms/platform-notes.qdoc | 32 | ||||
| -rw-r--r-- | doc/src/snippets/declarative/qtbinding/enums/standalone.qml | 15 |
4 files changed, 248 insertions, 24 deletions
diff --git a/doc/src/declarative/behaviors-and-states.qdoc b/doc/src/declarative/behaviors-and-states.qdoc new file mode 100644 index 0000000..0815b39 --- /dev/null +++ b/doc/src/declarative/behaviors-and-states.qdoc @@ -0,0 +1,206 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qml-behaviors-and-states.html +\title Using QML Behaviors with States + +\section1 Using Behaviors with States + +In some cases you may choose to use a Behavior to animate a property change caused by a state change. While this works well for some situations, in other situations it may lead to unexpected behavior. + +Here's an example that shows the problem: + +\qml +import QtQuick 1.0 + +Rectangle { + width: 400 + height: 400 + + Rectangle { + id: coloredRect + width: 100 + height: 100 + anchors.centerIn: parent + + color: "red" + Behavior on color { + ColorAnimation {} + } + + MouseArea { + id: mouser + anchors.fill: parent + hoverEnabled: true + } + + states: State { + name: "GreenState" + when: mouser.containsMouse + + PropertyChanges { + target: coloredRect + color: "green" + } + } + } +} +\endqml + +Testing the example by quickly and repeatedly moving the mouse in to and out of the colored rectangle shows that the colored rectangle will settle into a green color over time, never returning to full red. This is not what we wanted! The +problem occurs because we have used a Behavior to animate the change in color, and our state change is trigged by the mouse entering or exiting the MouseArea, which is easily interrupted. + +To state the problem more formally, using States and Behaviors together can cause unexpected behavior when: +\list +\o a Behavior is used to animate a property change, specifically when moving from an explicitly defined state back to the implicit base state; and +\o this Behavior can be interrupted to (re-)enter an explicitly defined state. +\endlist + +The problem occurs because of the way the base state is defined for QML: as the "snapshot" state of the application just prior to entering an explicitly defined state. In this case, if we are in the process of animating from green back +to red, and interrupt the animation to return to "GreenState", the base state will include the color in its intermediate, mid-animation form. + +While future versions of QML should be able to handle this situation more gracefully, there are currently several ways to rework your application to avoid this problem. + +1. Use a transition to animate the change, rather than a Behavior. + +\qml +import QtQuick 1.0 + +Rectangle { + width: 400 + height: 400 + + Rectangle { + id: coloredRect + width: 100 + height: 100 + anchors.centerIn: parent + + color: "red" + + MouseArea { + id: mouser + anchors.fill: parent + hoverEnabled: true + } + + states: State { + name: "GreenState" + when: mouser.containsMouse + + PropertyChanges { + target: coloredRect + color: "green" + } + } + + transitions: Transition { + ColorAnimation {} + } + } +} +\endqml + +2. Use a conditional binding to change the property value, rather than a state + +\qml +import QtQuick 1.0 + +Rectangle { + width: 400 + height: 400 + + Rectangle { + id: coloredRect + width: 100 + height: 100 + anchors.centerIn: parent + + color: mouser.containsMouse ? "green" : "red" + Behavior on color { + ColorAnimation {} + } + + MouseArea { + id: mouser + anchors.fill: parent + hoverEnabled: true + } + } +} +\endqml + +3. Use only explicitly defined states, rather than an implicit base state + +\qml +import QtQuick 1.0 + +Rectangle { + width: 400 + height: 400 + + Rectangle { + id: coloredRect + width: 100 + height: 100 + anchors.centerIn: parent + + Behavior on color { + ColorAnimation {} + } + + MouseArea { + id: mouser + anchors.fill: parent + hoverEnabled: true + } + + states: [ + State { + name: "GreenState" + when: mouser.containsMouse + + PropertyChanges { + target: coloredRect + color: "green" + } + }, + State { + name: "RedState" + when: !mouser.containsMouse + + PropertyChanges { + target: coloredRect + color: "red" + } + }] + } +} +\endqml + +*/ diff --git a/doc/src/declarative/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc index d11825e..3659caa 100644 --- a/doc/src/declarative/qtbinding.qdoc +++ b/doc/src/declarative/qtbinding.qdoc @@ -368,6 +368,10 @@ instead to create the signal handler: \o \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/MyItem.qml 0 \endtable +C++ signals can use enum values as parameters provided that the enum is declared in the +class that is emitting the signal, and that the enum is registered using Q_ENUMS. +See \l {Using enumerations of a custom type} below for details. + \section2 Modifying properties @@ -503,6 +507,21 @@ the \l {Extending QML Functionalities using C++} reference documentation for more information. +\section2 Using enumeration values as signal parameters + +C++ signals may pass enumeration values as signal parameters to QML, providing that the enumeration +and the signal are declared within the same class, or that the enumeration value is one of those declared +in the \l {Qt}{Qt Namespace}. + +Additionally, if a C++ signal with an enum parameter should be connectable to a QML function using the +\l {Connecting signals to methods and other signals}{connect()} function, the enum type must be +registered using qRegisterMetaType(). + +For QML signals, enum values may be used as signal parameters using the \c int type: + +\snippet doc/src/snippets/declarative/qtbinding/enums/standalone.qml 1 + + \section2 Automatic type conversion from strings As a convenience, some basic types can be specified in QML using format strings to make it easier to diff --git a/doc/src/platforms/platform-notes.qdoc b/doc/src/platforms/platform-notes.qdoc index de6eb7f..f4eb8bd 100644 --- a/doc/src/platforms/platform-notes.qdoc +++ b/doc/src/platforms/platform-notes.qdoc @@ -645,28 +645,8 @@ \section1 Supported Devices - Qt is designed to work on any device which runs one of the following - versions of Symbian: - - \table - \header \o Symbian Version - \row \o S60 3.1 - \row \o S60 3.2 - \row \o S60 5.0 (Symbian ^1) - \endtable - - Qt has received \l{Tier 1 Platforms}{Tier 1} testing on the following phone models: - - \table - \header \o Phone - \row \o Nokia 5800 - \row \o Nokia E71 - \row \o Nokia E72 - \row \o Nokia N78 - \row \o Nokia N95 - \row \o Nokia N97 - \row \o Samsung i8910 - \endtable + See the list of supported devices at + http://wiki.forum.nokia.com/index.php/Nokia_Smart_Installer_for_Symbian#Supported_Devices \section1 Supported Functionality @@ -679,8 +659,6 @@ \o Planned for future release. \row \o QtDBus \o No current plans to support this feature. - \row \o QtOpenGL ES - \o Planned for future release. \row \o Printing support \o No current plans to support this feature. \row \o Qt3Support @@ -774,6 +752,12 @@ plugin. If the Helix plugin fails to load, the MMF plugin, if present on the device, will be loaded instead. + \section1 QtOpenGL Support + + Qt 4.7 introduces the QtOpenGL module to Symbian^3. QtOpenGL is supported on + devices which support OpenGL ES 2.0. Symbian platforms prior to Symbian^3 + are not supported. + \section1 UI Performance in devices prior to Symbian^3 Qt uses the QPainter class to perform low-level painting on widgets and diff --git a/doc/src/snippets/declarative/qtbinding/enums/standalone.qml b/doc/src/snippets/declarative/qtbinding/enums/standalone.qml index 5721870..74e2c9c 100644 --- a/doc/src/snippets/declarative/qtbinding/enums/standalone.qml +++ b/doc/src/snippets/declarative/qtbinding/enums/standalone.qml @@ -38,6 +38,9 @@ ** ****************************************************************************/ import MyLibrary 1.0 +import QtQuick 1.0 + +Item { //![0] ImageViewer { @@ -47,3 +50,15 @@ ImageViewer { } } //![0] + +//![1] +ImageViewer { + signal someOtherSignal(int statusValue) + + Component.onCompleted: { + someOtherSignal(ImageViewer.Loading) + } +} +//![1] + +} |