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

Signals

Methods

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.qmlSizeItem.qmlMyRect.qml
import QtQuick 2.15

Item {
    width: 200; height: 200

    Loader {
        // Explicitly set the size of the
        // Loader to the parent item's size
        anchors.fill: parent
        source: "MyRect.qml"
    }
}
import QtQuick 2.15

Item {
    width: 200; height: 200

    Loader {
        // position the Loader in the center
        // of the parent
        anchors.centerIn: parent
        source: "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:

import QtQuick 2.15
pragma singleton

QtObject {
    property string text: ""
}

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

This property is true if the Loader is currently active. It is true by default.

If the Loader is inactive, changing the source will not instantiate the items until the Loader is active.

Setting the value to false, releases all the items loaded by the loader, but it does not affect the source.


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.

Item {
    Loader {
        source: "MyItem.qml"
    }
}

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:

import MyModule

Item {
    Loader {
        sourceComponent: MyModuleItem {}
    }
}

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:

ConstantDescription
Loader.NullThe loader is inactive or no QML source has been set.
Loader.ReadyThe QML source has been loaded.
Loader.ErrorAn 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()

This signal is emitted when the item is successfully loaded.

Loading failure results in item being set to null. This can be detected by the onItemChanged handler.

Note: The corresponding handler is onLoaded.

See also source and setSource.


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.