From f0c1beda18d79097ab85f062e9125da175ad04b8 Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Thu, 19 Aug 2010 18:03:16 +1000 Subject: Add info to Loader docs about receiving signals and key events --- doc/src/snippets/declarative/loader/KeyReader.qml | 53 ++++++++++ doc/src/snippets/declarative/loader/MyItem.qml | 55 +++++++++++ .../snippets/declarative/loader/connections.qml | 57 +++++++++++ doc/src/snippets/declarative/loader/focus.qml | 62 ++++++++++++ doc/src/snippets/declarative/loader/simple.qml | 54 +++++++++++ .../graphicsitems/qdeclarativeloader.cpp | 107 +++++++++++++-------- 6 files changed, 349 insertions(+), 39 deletions(-) create mode 100644 doc/src/snippets/declarative/loader/KeyReader.qml create mode 100644 doc/src/snippets/declarative/loader/MyItem.qml create mode 100644 doc/src/snippets/declarative/loader/connections.qml create mode 100644 doc/src/snippets/declarative/loader/focus.qml create mode 100644 doc/src/snippets/declarative/loader/simple.qml diff --git a/doc/src/snippets/declarative/loader/KeyReader.qml b/doc/src/snippets/declarative/loader/KeyReader.qml new file mode 100644 index 0000000..4423ac6 --- /dev/null +++ b/doc/src/snippets/declarative/loader/KeyReader.qml @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtDeclarative module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +import Qt 4.7 + +Item { + Item { + focus: true + Keys.onPressed: { + console.log("Loaded item captured:", event.text); + event.accepted = true; + } + } +} +//![0] diff --git a/doc/src/snippets/declarative/loader/MyItem.qml b/doc/src/snippets/declarative/loader/MyItem.qml new file mode 100644 index 0000000..cc69661 --- /dev/null +++ b/doc/src/snippets/declarative/loader/MyItem.qml @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtDeclarative module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +import Qt 4.7 + +Rectangle { + id: myItem + signal message(string msg) + + width: 100; height: 100 + + MouseArea { + anchors.fill: parent + onClicked: myItem.message("clicked!") + } +} +//![0] diff --git a/doc/src/snippets/declarative/loader/connections.qml b/doc/src/snippets/declarative/loader/connections.qml new file mode 100644 index 0000000..babac4e --- /dev/null +++ b/doc/src/snippets/declarative/loader/connections.qml @@ -0,0 +1,57 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtDeclarative module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +import Qt 4.7 + +Item { + width: 100; height: 100 + + Loader { + id: myLoader + source: "MyItem.qml" + } + + Connections { + target: myLoader.item + onMessage: console.log(msg) + } +} +//![0] diff --git a/doc/src/snippets/declarative/loader/focus.qml b/doc/src/snippets/declarative/loader/focus.qml new file mode 100644 index 0000000..464d986 --- /dev/null +++ b/doc/src/snippets/declarative/loader/focus.qml @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtDeclarative module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +import Qt 4.7 + +Rectangle { + width: 200; height: 200 + + Loader { + id: loader + focus: true + } + + MouseArea { + anchors.fill: parent + onClicked: loader.source = "KeyReader.qml" + } + + Keys.onPressed: { + console.log("Captured:", event.text); + } +} +//![0] + diff --git a/doc/src/snippets/declarative/loader/simple.qml b/doc/src/snippets/declarative/loader/simple.qml new file mode 100644 index 0000000..e0dc6b3 --- /dev/null +++ b/doc/src/snippets/declarative/loader/simple.qml @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtDeclarative module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +import Qt 4.7 + +Item { + width: 200; height: 200 + + Loader { id: pageLoader } + + MouseArea { + anchors.fill: parent + onClicked: pageLoader.source = "Page1.qml" + } +} +//![0] diff --git a/src/declarative/graphicsitems/qdeclarativeloader.cpp b/src/declarative/graphicsitems/qdeclarativeloader.cpp index 4c6268f..2fde4c8 100644 --- a/src/declarative/graphicsitems/qdeclarativeloader.cpp +++ b/src/declarative/graphicsitems/qdeclarativeloader.cpp @@ -115,53 +115,76 @@ void QDeclarativeLoaderPrivate::initResize() \brief The Loader item allows dynamically loading an Item-based subtree from a URL or Component. - The Loader element instantiates an item from a component. The component to - be instantiated may be specified directly by the \l sourceComponent - property, or loaded from a URL via the \l source property. + Loader is used to dynamically load visual QML components. It can load a + QML file (using the \l source property) or a \l Component object (using + the \l sourceComponent property). It is useful for delaying the creation + of a component until it is required: for example, when a component should + be created on demand, or when a component should not be created + unnecessarily for performance reasons. - Loader can be used to delay the creation of a component until it - is required. For example, this loads "Page1.qml" as a component - into the Loader element, when the \l MouseArea is clicked: + Here is a Loader that loads "Page1.qml" as a component when the + \l MouseArea is clicked: - \code - import Qt 4.7 + \snippet doc/src/snippets/declarative/loader/simple.qml 0 - Item { - width: 200; height: 200 + The loaded item can be accessed using the \l item property. - MouseArea { - anchors.fill: parent - onClicked: pageLoader.source = "Page1.qml" - } + Loader is like any other visual item and must be positioned and sized + accordingly to become visible. Once the component is loaded, the Loader + is automatically resized to the size of the component. - Loader { id: pageLoader } - } - \endcode + If the \l source or \l sourceComponent changes, any previously instantiated + items are destroyed. Setting \l source to an empty string or setting + \l sourceComponent to \c undefined destroys the currently loaded item, + freeing resources and leaving the Loader empty. + + + \section2 Receiving signals from loaded items - Note that Loader is like any other graphical Item and needs to be positioned - and sized accordingly to become visible. When a component is loaded, the - Loader is automatically resized to the size of the component. + Any signals emitted from the loaded item can be received using the + \l Connections element. For example, the following \c application.qml + loads \c MyItem.qml, and is able to receive the \c message signal from + the loaded item through a \l Connections object: - If the Loader source is changed, any previous items instantiated - will be destroyed. Setting \l source to an empty string, or setting - sourceComponent to \e undefined - will destroy the currently instantiated items, freeing resources - and leaving the Loader empty. For example: + \table + \row + \o application.qml + \o MyItem.qml + \row + \o \snippet doc/src/snippets/declarative/loader/connections.qml 0 + \o \snippet doc/src/snippets/declarative/loader/MyItem.qml 0 + \endtable - \code - pageLoader.source = "" - \endcode + Alternatively, since \c MyItem.qml is loaded within the scope of the + Loader, it could also directly call any function defined in the Loader or + its parent \l Item. - or - \code - pageLoader.sourceComponent = undefined - \endcode + \section2 Focus and key events - unloads "Page1.qml" and frees resources consumed by it. + Loader is a focus scope. Its \l {Item::}{focus} property must be set to + \c true for any of its children to get the \e {active focus}. (See + \l{qmlfocus#Acquiring Focus and Focus Scopes}{the focus documentation page} + for more details.) Any key events received in the loaded item should likely + also be \l {KeyEvent::}{accepted} so they are not propagated to the Loader. - Note that Loader is a focus scope. Its \c focus property must be set to \c true for any of its children - to get the \e {active focus} (see \l{qmlfocus#Acquiring Focus and Focus Scopes}{the focus documentation page} for more details). + For example, the following \c application.qml loads \c KeyReader.qml when + the \l MouseArea is clicked. Notice the \l {Item::}{focus} property is + set to \c true for the Loader as well as the \l Item in the dynamically + loaded object: + + \table + \row + \o application.qml + \o KeyReader.qml + \row + \o \snippet doc/src/snippets/declarative/loader/focus.qml 0 + \o \snippet doc/src/snippets/declarative/loader/KeyReader.qml 0 + \endtable + + Once \c KeyReader.qml is loaded, it accepts key events and sets + \c event.accepted to \c true so that the event is not propagated to the + parent \l Rectangle. \sa {dynamic-object-creation}{Dynamic Object Creation} */ @@ -198,8 +221,13 @@ QDeclarativeLoader::~QDeclarativeLoader() /*! \qmlproperty url Loader::source - This property holds the URL of the QML component to - instantiate. + This property holds the URL of the QML component to instantiate. + + Note the QML component must be an \l Item-based component. Loader cannot + load non-visual components. + + To unload the currently loaded item, set this property to an empty string, + or set \l sourceComponent to \c undefined. \sa sourceComponent, status, progress */ @@ -258,7 +286,8 @@ void QDeclarativeLoader::setSource(const QUrl &url) } \endqml - Note this value must hold a \l Component object; it cannot be a \l Item. + To unload the currently loaded item, set this property to an empty string, + or set \l sourceComponent to \c undefined. \sa source, progress */ @@ -477,7 +506,7 @@ void QDeclarativeLoaderPrivate::_q_updateSize(bool loaderGeometryChanged) /*! \qmlproperty Item Loader::item - This property holds the top-level item created from source. + This property holds the top-level item that is currently loaded. */ QGraphicsObject *QDeclarativeLoader::item() const { -- cgit v0.12