summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--doc/src/getting-started/gettingstartedqml.qdoc10
-rw-r--r--doc/src/snippets/declarative/loader/KeyReader.qml53
-rw-r--r--doc/src/snippets/declarative/loader/MyItem.qml55
-rw-r--r--doc/src/snippets/declarative/loader/connections.qml57
-rw-r--r--doc/src/snippets/declarative/loader/focus.qml62
-rw-r--r--doc/src/snippets/declarative/loader/simple.qml54
-rw-r--r--src/declarative/graphicsitems/qdeclarativeloader.cpp107
7 files changed, 353 insertions, 45 deletions
diff --git a/doc/src/getting-started/gettingstartedqml.qdoc b/doc/src/getting-started/gettingstartedqml.qdoc
index 885e6ce..a19d281 100644
--- a/doc/src/getting-started/gettingstartedqml.qdoc
+++ b/doc/src/getting-started/gettingstartedqml.qdoc
@@ -224,15 +224,13 @@
\code
import Qt 4.7 \\import the main Qt QML module
import "folderName" \\import the contents of the folder
- import "Button.qml" \\import a QML file
- import "NewButton.qml" as ButtonModule \\import a QML file and give it a name
import "script.js" as Script \\import a Javascript file and name it as Script
\endcode
- To use the \c Button element in \c FileMenu.qml, we need to import \c Button.qml.
- The syntax shown above, shows how to use the \c import keyword. However, the
- \c {import Button.qml} is not necessary; qmlviewer will import all the contents
- of the current directory. We can directly create a \c Button element by declaring
+ The syntax shown above shows how to use the \c import keyword. This is required to
+ use JavaScript files, or QML files that are not within the same directory. Since
+ \c Button.qml is in the same directory as \c FileMenu.qml, we do not need to import
+ the \c Button.qml file to use it. We can directly create a \c Button element by declaring
\c Button{}, similar to a \c Rectangle{} declaration.
\code
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
{
generated by cgit v0.12 at 2024-11-11 15:52:51 (GMT)