C
Loader QML Type
Allows dynamic loading of a subtree from a URL or Component. More...
Import Statement: | import QtQuick |
Since: | Qt Quick Ultralite 2.3 |
Properties
- active : bool
- item : ItemBase*
- source : string
- sourceComponent : Component
- status : enumeration
Signals
- loaded()
Methods
- void setSource(string source)
Detailed Description
Loader can load a pre-compiled QML component (using the source property) or a Component object (using the 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 should not be created unnecessarily for performance reasons.
Here is a Loader that loads "Page1.qml" as a component when the MouseArea
is clicked:
import QtQuick 2.15 Item { width: 200; height: 200 Loader { id: pageLoader } MouseArea { anchors.fill: parent onClicked: pageLoader.source = "Page1.qml" } }
If the source or sourceComponent changes, any previously instantiated items are destroyed. Setting source to an empty string or setting sourceComponent to undefined
destroys the currently loaded object, freeing resources and leaving the Loader empty.
Allocation
The Qt Quick Ultralite Loader allocates its items using the QmlDynamicObjects memory allocator.
The allocation happens each time the source or sourceComponent changes. The deallocation happens before each allocation, and when the active property changes to false
.
Note that all allocations in Qt Quick Ultralite are performed on a single thread. Depending on the duration of user-defined initialization routines (class constructors), short UI freezes may occur.
Loader Sizing Behavior
The Loader applies the following sizing rules:
- If an explicit size is not specified for the Loader, the Loader is automatically resized to the size of the loaded item once the component is loaded.
- If the size of the Loader is specified explicitly by setting the width, height or by anchoring, the loaded item will be resized to the size of the Loader.
In both scenarios the size of the item and the Loader are identical. This ensures that anchoring to the Loader is equivalent to anchoring to the loaded item.
SizeLoader.qml | SizeItem.qml | MyRect.qml |
---|---|---|
import QtQuick 2.15 Rectangle { width: 50 height: 50 color: "red" } | ||
The red rectangle will be sized to the size of the root item. | The red rectangle will be 50x50, centered in the root item. |
Limitations
Communication with the loaded items
Unlike in Qt Quick Loader, Qt Quick Ultralite Loader does not support accessing loaded items using the item property due to the lack of an object introspection system.
This limitation effectively disables interactions like reading or writing properties and calling functions using Loader.item.
To work around this limitation, one can create a mediator singleton. For example:
This singleton is then used in the main.qml file:
import QtQuick 2.15 import Mediator Column { Text { text: "Text from loaded item: " + Mediator.text } Loader { source: "MyText.qml" } }
And the MyText.qml:
import QtQuick 2.15 import Mediator Text { text: "mytext" Component.onCompleted: Mediator.text = text }
The mediator singleton is not necessary when using the sourceComponent property, since the Component can have bindings on other items in the document:
import QtQuick 2.15 Rectangle { id: root Item { id: globalSettings property int usersVisisted: 0 property color page1Color: "orange" signal updatePageStats() } Component { id: page1 Rectangle { color: globalSettings.page1Color width: 100 height: 100 Connections { target: globalSettings function onUpdatePageStats() { globalSettings.usersVisisted = 999 } } } } Column { Loader { id: loader1 sourceComponent: page1 Component.onCompleted: { globalSettings.page1Color = "pink" globalSettings.updatePageStats() } } Text { text: "users visited: " + globalSettings.usersVisisted } } }
View Delegates
The Qt Quick Ultralite Loader cannot be used within a View Delegate.
See also Known Issues or Limitations.
Property Documentation
active : bool |
item : ItemBase* |
This property holds the top-level object that is currently loaded.
See also Communication with the loaded items.
source : string |
This property holds the URL of the QML item to instantiate.
Loader can load visual items (those that inherit from Item) only.
Setting this property to either an empty string or a new URL, unloads the item that is loaded from the previous URL.
The value of the source
property must be the source file of a QML item in the current module. If you want to use an item from another module, use sourceComponent instead. Consider the following snippet, where "MyModuleItem.qml" is part of the module MyModule
:
See also sourceComponent.
[since Qt Quick Ultralite 2.4] sourceComponent : Component |
This property holds the Component to instantiate.
Item { Component { id: redSquare Rectangle { color: "red"; width: 10; height: 10 } } Loader { sourceComponent: redSquare } Loader { sourceComponent: redSquare; x: 10 } }
To unload the currently loaded object, set this property to undefined
.
Loader can load visual items (those that inherit from Item) only.
This property was introduced in Qt Quick Ultralite 2.4.
See also source.
[since Qt Quick Ultralite 2.6] status : enumeration |
This property holds the QML component's loading status. It can be one of following values:
Constant | Description |
---|---|
Loader.Null | The loader is inactive or no QML source has been set. |
Loader.Ready | The QML source has been loaded. |
Loader.Error | An error occurred while loading the QML source. |
Use this status to provide an update or respond to the status change in some way. For example, you could:
- Trigger a state change:
State { name: 'loaded' when: loader.status == Loader.Ready }
- Implement an
onStatusChanged
signal handler:Loader { id: loader onStatusChanged: { if (loader.status == Loader.Ready) console.log('Loaded'); } }
- Bind to the status value:
Text { text: loader.status == Loader.Ready ? 'Loaded' : 'Not loaded' }
Note: If source
is a local file, the initial status
is either Ready
or Error
. In such cases, you will get notified for the onLoaded
signal only, but not the onStatusChanged
signal.
This property was introduced in Qt Quick Ultralite 2.6.
Signal Documentation
loaded() |
Method Documentation
void setSource(string source) |
Creates an object instance of the given source component. The instance will be accessible using the item property once loading and instantiation is complete.
If the active property is false
at the time when this function is called, the given source component will not be loaded but the source will be cached. When the loader is made active, an instance of the source component will be created.
See also Communication with the loaded items.
Available under certain Qt licenses.
Find out more.