diff options
author | Chris Adams <christopher.adams@nokia.com> | 2011-10-10 12:11:21 +1000 |
---|---|---|
committer | Qt by Nokia <qt-info@nokia.com> | 2011-12-06 02:46:28 +0100 |
commit | 564d58025e46c825ec763193767defd78f5e13a0 (patch) | |
tree | 31d046ac0c016df416afd4923fb749d8bf73d6bc /doc | |
parent | 8601f3444f7926a7b47ae217d8bf51044ff61809 (diff) |
Ensure that scarce resources work with var properties
Now that we have a new property type which stores JavaScript handles,
we need to ensure that scarce resources can be used with them.
Task-number: QMLNG-18
Task-number: QTBUG-21843
Change-Id: I4a920ae39e7d33cf5e33362e5e0ee21c74cb35e3
Reviewed-by: Martin Jones <martin.jones@nokia.com>
Diffstat (limited to 'doc')
11 files changed, 624 insertions, 136 deletions
diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc index 98eea78a07..a908e73ca8 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/declarative/basictypes.qdoc @@ -479,6 +479,19 @@ } \endqml + A \c var type property can also hold an image or pixmap. + A \c var which contains a QPixmap or QImage is known as a + "scarce resource" and the declarative engine will attempt to + automatically release such resources after evaluation of any JavaScript + expression which requires one to be copied has completed. + + Clients may explicitly release such a scarce resource by calling the + "destroy" method on the \c var property from within JavaScript. They + may also explicitly preserve the scarce resource by calling the + "preserve" method on the \c var property from within JavaScript. + For more information regarding the usage of a scarce resource, please + see \l{Scarce Resources in JavaScript}. + \sa {QML Basic Types} */ 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 */ diff --git a/doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp b/doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp new file mode 100644 index 0000000000..eb521e1e7e --- /dev/null +++ b/doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp @@ -0,0 +1,124 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "avatarExample.h" +#include <QDeclarativeEngine> +#include <QDeclarativeComponent> + +void registerTypes() +{ +//![0] + qmlRegisterType<AvatarExample>("Qt.example", 1, 0, "AvatarExample"); +//![0] +} + +void expectOne() +{ +//![1] +QDeclarativeComponent component(&engine, "exampleOne.qml"); +QObject *object = component.create(); +// The scarce resource will have been released automatically +// by this point, after the binding expression was evaluated. +delete object; +//![1] +} + +void expectTwo() +{ +//![2] +QDeclarativeComponent component(&engine, "exampleTwo.qml"); +QObject *object = component.create(); +// The scarce resource will not 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: +bool expectedResult = (object->property("avatar").isValid() == true); +delete object; +//![2] +} + +void expectThree() +{ +//![3] +QDeclarativeComponent component(&engine, "exampleThree.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: +bool expectedResult = (object->property("avatar").isValid() == true); +// The scarce resource will not be released until all references to +// the resource are released, and the JavaScript garbage collector runs. +delete object; +//![3] +} + +void expectFour() +{ +//![4] +QDeclarativeComponent component(&engine, "exampleFour.qml"); +QObject *object = component.create(); +// The scarce resource was explicitly preserved by the client during +// the importAvatar() function, and so the scarce resource +// remains valid until the explicit call to releaseAvatar(). As such, +// we get the expected results: +bool expectedResultOne = (object->property("avatarOne").isValid() == true); +bool expectedResultTwo = (object->property("avatarTwo").isValid() == false); +// Because the scarce resource referenced by avatarTwo 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; +//![4] +} + +void expectFive() +{ +//![5] +QDeclarativeComponent component(&engine, "exampleFive.qml"); +QObject *object = component.create(); +// We have the expected results: +bool expectedResultOne = (object->property("avatarOne").isValid() == false); +bool expectedResultTwo = (object->property("avatarTwo").isValid() == false); +// Because although only avatarTwo was explicitly released, +// avatarOne and avatarTwo were referencing the same +// scarce resource. +delete object; +//![5] +} diff --git a/doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.h b/doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.h new file mode 100644 index 0000000000..17cef5e5cd --- /dev/null +++ b/doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.h @@ -0,0 +1,73 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef AVATAREXAMPLE_P_H +#define AVATAREXAMPLE_P_H + +#include <QObject> +#include <QPixmap> + +//![0] +// avatarExample.h +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; +}; +//![0] + +#endif diff --git a/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleFive.qml b/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleFive.qml new file mode 100644 index 0000000000..33326b744d --- /dev/null +++ b/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleFive.qml @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +// exampleFive.qml +import QtQuick 2.0 +import Qt.example 1.0 +import "exampleFour.js" as ExampleFourJs // use factory from example four + +QtObject { + property var avatarOne: ExampleFourJs.importAvatar() + property var avatarTwo: avatarOne + + Component.onCompleted: { + ExampleFourJs.releaseAvatar(avatarTwo); + } +} +//![0]
\ No newline at end of file diff --git a/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleFour.js b/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleFour.js new file mode 100644 index 0000000000..476e03fdf8 --- /dev/null +++ b/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleFour.js @@ -0,0 +1,56 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +// exampleFour.js +.import Qt.example 1.0 as QtExample + +function importAvatar() { + var component = Qt.createComponent("exampleTwo.qml"); + var exampleOneElement = component.createObject(null); + var avatarExample = exampleOneElement.a; + var retn = avatarExample.avatar; + retn.preserve(); + return retn; +} + +function releaseAvatar(avatar) { + avatar.destroy(); +} +//![0]
\ No newline at end of file diff --git a/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleFour.qml b/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleFour.qml new file mode 100644 index 0000000000..e423771a20 --- /dev/null +++ b/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleFour.qml @@ -0,0 +1,56 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +// exampleFour.qml +import QtQuick 2.0 +import Qt.example 1.0 +import "exampleFour.js" as ExampleFourJs + +QtObject { + property var avatarOne + property var avatarTwo + + Component.onCompleted: { + avatarOne = ExampleFourJs.importAvatar(); + avatarTwo = ExampleFourJs.importAvatar(); + ExampleFourJs.releaseAvatar(avatarTwo); + } +} +//![0]
\ No newline at end of file diff --git a/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleOne.qml b/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleOne.qml new file mode 100644 index 0000000000..c8579b7c6c --- /dev/null +++ b/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleOne.qml @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +// exampleOne.qml +import QtQuick 1.0 +import Qt.example 1.0 + +QtObject { + property AvatarExample a; + a: AvatarExample { id: example } + property var avatarWidth: example.avatar,100 + // Here, we use "example.avatar,100" purely for illustration. + // The value of `avatarWidth' will be 100 after evaluation. + // E.g., you could imagine some js function which takes + // an avatar, and returns the width of the avatar. +} +//![0]
\ No newline at end of file diff --git a/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleThree.js b/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleThree.js new file mode 100644 index 0000000000..4fefb1e3f7 --- /dev/null +++ b/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleThree.js @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +// exampleThree.js +.import Qt.example 1.0 as QtExample + +var component = Qt.createComponent("exampleTwo.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; +} +//![0]
\ No newline at end of file diff --git a/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleThree.qml b/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleThree.qml new file mode 100644 index 0000000000..58382902c8 --- /dev/null +++ b/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleThree.qml @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +// exampleThree.qml +import QtQuick 1.0 +import Qt.example 1.0 +import "exampleThree.js" as ExampleThreeJs + +QtObject { + property var avatar: ExampleThreeJs.importAvatar() +} +//![0]
\ No newline at end of file diff --git a/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleTwo.qml b/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleTwo.qml new file mode 100644 index 0000000000..610a75b97f --- /dev/null +++ b/doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleTwo.qml @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +// exampleTwo.qml +import QtQuick 1.0 +import Qt.example 1.0 + +QtObject { + property AvatarExample a; + a: AvatarExample { id: example } + property var avatar: example.avatar + // Now `avatar' contains a reference to the scarce resource. +} +//![0]
\ No newline at end of file |