110 \qmlclass Loader QDeclarativeLoader |
110 \qmlclass Loader QDeclarativeLoader |
111 \since 4.7 |
111 \since 4.7 |
112 \inherits Item |
112 \inherits Item |
113 |
113 |
114 \brief The Loader item allows dynamically loading an Item-based |
114 \brief The Loader item allows dynamically loading an Item-based |
115 subtree from a QML URL or Component. |
115 subtree from a URL or Component. |
116 |
116 |
117 Loader instantiates an item from a component. The component to |
117 The Loader element instantiates an item from a component. The component to |
118 instantiate may be specified directly by the \c sourceComponent |
118 be instantiated may be specified directly by the \l sourceComponent |
119 property, or loaded from a URL via the \c source property. |
119 property, or loaded from a URL via the \l source property. |
120 |
120 |
121 It is also an effective means of delaying the creation of a component |
121 Loader can be used to delay the creation of a component until it |
122 until it is required: |
122 is required. For example, this loads "Page1.qml" as a component |
|
123 into the Loader element, when the \l MouseArea is clicked: |
|
124 |
123 \code |
125 \code |
124 Loader { id: pageLoader } |
126 import Qt 4.7 |
125 Rectangle { |
127 |
126 MouseArea { anchors.fill: parent; onClicked: pageLoader.source = "Page1.qml" } |
128 Item { |
|
129 width: 200; height: 200 |
|
130 |
|
131 MouseArea { |
|
132 anchors.fill: parent |
|
133 onClicked: pageLoader.source = "Page1.qml" |
|
134 } |
|
135 |
|
136 Loader { id: pageLoader } |
127 } |
137 } |
128 \endcode |
138 \endcode |
129 |
139 |
|
140 Note that Loader is like any other graphical Item and needs to be positioned |
|
141 and sized accordingly to become visible. When a component is loaded, the |
|
142 Loader is automatically resized to the size of the component. |
|
143 |
130 If the Loader source is changed, any previous items instantiated |
144 If the Loader source is changed, any previous items instantiated |
131 will be destroyed. Setting \c source to an empty string, or setting |
145 will be destroyed. Setting \l source to an empty string, or setting |
132 sourceComponent to \e undefined |
146 sourceComponent to \e undefined |
133 will destroy the currently instantiated items, freeing resources |
147 will destroy the currently instantiated items, freeing resources |
134 and leaving the Loader empty. For example: |
148 and leaving the Loader empty. For example: |
135 |
149 |
136 \code |
150 \code |
137 pageLoader.source = "" |
151 pageLoader.source = "" |
|
152 \endcode |
|
153 |
138 or |
154 or |
|
155 |
|
156 \code |
139 pageLoader.sourceComponent = undefined |
157 pageLoader.sourceComponent = undefined |
140 \endcode |
158 \endcode |
141 |
159 |
142 unloads "Page1.qml" and frees resources consumed by it. |
160 unloads "Page1.qml" and frees resources consumed by it. |
143 |
161 |
145 */ |
163 */ |
146 |
164 |
147 /*! |
165 /*! |
148 \internal |
166 \internal |
149 \class QDeclarativeLoader |
167 \class QDeclarativeLoader |
150 \qmlclass Loader |
|
151 */ |
168 */ |
152 |
169 |
153 /*! |
170 /*! |
154 Create a new QDeclarativeLoader instance. |
171 Create a new QDeclarativeLoader instance. |
155 */ |
172 */ |
156 QDeclarativeLoader::QDeclarativeLoader(QDeclarativeItem *parent) |
173 QDeclarativeLoader::QDeclarativeLoader(QDeclarativeItem *parent) |
157 : QDeclarativeItem(*(new QDeclarativeLoaderPrivate), parent) |
174 : QDeclarativeItem(*(new QDeclarativeLoaderPrivate), parent) |
158 { |
175 { |
159 Q_D(QDeclarativeItem); |
176 Q_D(QDeclarativeLoader); |
160 d->flags |= QGraphicsItem::ItemIsFocusScope; |
177 d->flags |= QGraphicsItem::ItemIsFocusScope; |
161 } |
178 } |
162 |
179 |
163 /*! |
180 /*! |
164 Destroy the loader instance. |
181 Destroy the loader instance. |
165 */ |
182 */ |
166 QDeclarativeLoader::~QDeclarativeLoader() |
183 QDeclarativeLoader::~QDeclarativeLoader() |
167 { |
184 { |
|
185 Q_D(QDeclarativeLoader); |
|
186 if (d->item) { |
|
187 if (QDeclarativeItem *qmlItem = qobject_cast<QDeclarativeItem*>(d->item)) { |
|
188 QDeclarativeItemPrivate *p = |
|
189 static_cast<QDeclarativeItemPrivate *>(QGraphicsItemPrivate::get(qmlItem)); |
|
190 p->removeItemChangeListener(d, QDeclarativeItemPrivate::Geometry); |
|
191 } |
|
192 } |
168 } |
193 } |
169 |
194 |
170 /*! |
195 /*! |
171 \qmlproperty url Loader::source |
196 \qmlproperty url Loader::source |
172 This property holds the URL of the QML component to |
197 This property holds the URL of the QML component to |
338 \o Loader.Ready - the QML source has been loaded |
365 \o Loader.Ready - the QML source has been loaded |
339 \o Loader.Loading - the QML source is currently being loaded |
366 \o Loader.Loading - the QML source is currently being loaded |
340 \o Loader.Error - an error occurred while loading the QML source |
367 \o Loader.Error - an error occurred while loading the QML source |
341 \endlist |
368 \endlist |
342 |
369 |
343 Note that a change in the status property does not cause anything to happen |
370 Use this status to provide an update or respond to the status change in some way. |
344 (although it reflects what has happened to the loader internally). If you wish |
371 For example, you could: |
345 to react to the change in status you need to do it yourself, for example in one |
372 |
346 of the following ways: |
373 \e {Trigger a state change:} |
347 \list |
374 \qml |
348 \o Create a state, so that a state change occurs, e.g. State{name: 'loaded'; when: loader.status = Loader.Ready;} |
375 State { name: 'loaded'; when: loader.status = Loader.Ready } |
349 \o Do something inside the onLoaded signal handler, e.g. Loader{id: loader; onLoaded: console.log('Loaded');} |
376 \endqml |
350 \o Bind to the status variable somewhere, e.g. Text{text: if(loader.status!=Loader.Ready){'Not Loaded';}else{'Loaded';}} |
377 |
351 \endlist |
378 \e {Implement an \c onStatusChanged signal handler:} |
352 \sa progress |
379 \qml |
|
380 Loader { |
|
381 id: loader |
|
382 onStatusChanged: if (loader.status == Loader.Ready) console.log('Loaded') |
|
383 } |
|
384 \endqml |
|
385 |
|
386 \e {Bind to the status value:} |
|
387 \qml |
|
388 Text { text: loader.status != Loader.Ready ? 'Not Loaded' : 'Loaded' } |
|
389 \endqml |
353 |
390 |
354 Note that if the source is a local file, the status will initially be Ready (or Error). While |
391 Note that if the source is a local file, the status will initially be Ready (or Error). While |
355 there will be no onStatusChanged signal in that case, the onLoaded will still be invoked. |
392 there will be no onStatusChanged signal in that case, the onLoaded will still be invoked. |
|
393 |
|
394 \sa progress |
356 */ |
395 */ |
357 |
396 |
358 QDeclarativeLoader::Status QDeclarativeLoader::status() const |
397 QDeclarativeLoader::Status QDeclarativeLoader::status() const |
359 { |
398 { |
360 Q_D(const QDeclarativeLoader); |
399 Q_D(const QDeclarativeLoader); |