diff options
Diffstat (limited to 'doc/src/declarative/javascriptblocks.qdoc')
| -rw-r--r-- | doc/src/declarative/javascriptblocks.qdoc | 172 |
1 files changed, 36 insertions, 136 deletions
diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc index a9e383c258..34a1986db6 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -362,7 +362,7 @@ Item { \section1 Scarce Resources in JavaScript -As described in the documentation for \l{QML Basic Types}, a \c variant type +As described in the documentation for \l{QML Basic Types}, a \c var type property may hold a "scarce resource" (image or pixmap). There are several important semantics of scarce resources which should be noted: @@ -379,30 +379,12 @@ may be necessary for clients to manually preserve or destroy resources for themselves. For the following examples, imagine that we have defined the following class: -\code -class AvatarExample : public QObject -{ - Q_OBJECT - Q_PROPERTY(QPixmap avatar READ avatar WRITE setAvatar NOTIFY avatarChanged) -public: - AvatarExample(QObject *parent = 0) : QObject(parent), m_value(100, 100) { m_value.fill(Qt::blue); } - ~AvatarExample() {} - - QPixmap avatar() const { return m_value; } - void setAvatar(QPixmap v) { m_value = v; emit avatarChanged(); } - -signals: - void avatarChanged(); - -private: - QPixmap m_value; -}; -\endcode + +\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.h 0 and that we have registered it with the QML type-system as follows: -\code -qmlRegisterType<AvatarExample>("Qt.example", 1, 0, "AvatarExample"); -\endcode + +\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp 0 The AvatarExample class has a property which is a pixmap. When the property is accessed in JavaScript scope, a copy of the resource will be created and @@ -414,141 +396,59 @@ unless the client explicitly preserves it. \section2 Example One: Automatic Release -In this example, the resource will be automatically +In the following example, the scarce resource will be automatically released +after the binding evaluation is complete. + +\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleOne.qml 0 + +\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp 1 + +\section2 Example Two: Automatic Release Prevented By Reference + +In this example, the resource will not be automatically released after the binding expression evaluation is -complete. +complete, because there is a property var referencing the +scarce resource. -\qml -// exampleOne.qml -import QtQuick 1.0 -import Qt.example 1.0 - -QtObject { - property AvatarExample a; - a: AvatarExample { id: example } - property variant avatar: example.avatar -} -\endqml +\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleTwo.qml 0 -\code -QDeclarativeComponent component(&engine, "exampleOne.qml"); -QObject *object = component.create(); -// The scarce resource will have been released automatically -// after the binding expression was evaluated. -// Since the scarce resource was not released explicitly prior -// to the binding expression being evaluated, we get the -// expected result: -//object->property("scarceResourceCopy").isValid() == true -delete object; -\endcode +\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp 2 -\section2 Example Two: Explicit Preservation +\section2 Example Three: Explicit Preservation In this example, the resource must be explicitly preserved in order to prevent the declarative engine from automatically releasing the resource after evaluation of the imported script. -\code -// exampleTwo.js -.import Qt.example 1.0 as QtExample - -var component = Qt.createComponent("exampleOne.qml"); -var exampleOneElement = component.createObject(null); -var avatarExample = exampleOneElement.a; -var retn = avatarExample.avatar; - -// without the following call, the scarce resource held -// by retn would be automatically released by the engine -// after the import statement in exampleTwo.qml, prior -// to the variable assignment. -retn.preserve(); - -function importAvatar() { - return retn; -} -\endcode +\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleThree.js 0 -\qml -// exampleTwo.qml -import QtQuick 1.0 -import Qt.example 1.0 -import "exampleTwo.js" as ExampleTwoJs +\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleThree.qml 0 -QtObject { - property variant avatar: ExampleTwoJs.importAvatar() -} -\endqml +\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp 3 -\code -QDeclarativeComponent component(&engine, "exampleTwo.qml"); -QObject *object = component.create(); -// The resource was preserved explicitly during evaluation of the -// JavaScript expression. Thus, during property assignment, the -// scarce resource was still valid, and so we get the expected result: -//object->property("avatar").isValid() == true -// The scarce resource may not have been cleaned up by the JS GC yet; -// it will continue to consume system resources until the JS GC runs. -delete object; -\endcode - -\section2 Example Three: Explicit Destruction +\section2 Example Four: Explicit Destruction In the following example, we release (via destroy()) an explicitly preserved scarce resource variant. This example shows how a client may free system resources by releasing the scarce resource held in a JavaScript object, if required, during evaluation of a JavaScript expression. -\code -// exampleThree.js -.import Qt.example 1.0 as QtExample +\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleFour.js 0 -var component = Qt.createComponent("exampleOne.qml"); -var exampleOneElement = component.createObject(null); -var avatarExample = exampleOneElement.a; -var retn = avatarExample.avatar; -retn.preserve(); +\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleFour.qml 0 -function importAvatar() { - return retn; -} +\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp 4 -function releaseAvatar() { - retn.destroy(); -} -\endcode +\section2 Example Five: Explicit Destruction And JavaScript References -\qml -// exampleThree.qml -import QtQuick 1.0 -import Qt.example 1.0 -import "exampleThree.js" as ExampleThreeJs - -QtObject { - property variant avatarOne - property variant avatarTwo - - Component.onCompleted: { - avatarOne = ExampleThreeJs.importAvatar(); // valid at this stage - ExampleThreeJs.releaseAvatar(); // explicit release - avatarTwo = ExampleThreeJs.importAvatar(); // invalid at this stage - } -} -\endqml +One thing to be aware of when using "var" type properties is that they +hold references to JavaScript objects. As such, if multiple references +to one scarce resource is held, and the client calls destroy() on one +of those references (to explicitly release the scarce resource), all of +the references will be affected. -\code -QDeclarativeComponent component(&engine, "exampleThree.qml"); -QObject *object = component.create(); -// The scarce resource was explicitly preserved by the client during -// the evaluation of the imported script, and so the scarce resource -// remains valid until the explicit call to releaseAvatar(). As such, -// we get the expected results: -//object->property("avatarOne").isValid() == true -//object->property("avatarTwo").isValid() == false -// Because the scarce resource was released explicitly, it will no longer -// be consuming any system resources (beyond what a normal JS Object would; -// that small overhead will exist until the JS GC runs, as per any other -// JavaScript object). -delete object; -\endcode +\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleFive.qml 0 + +\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp 5 */ |