Loader QML Type

Allows dynamic loading of a subtree from a URL. More...

• List of all members, including inherited members

Properties

• active : bool
• item : ItemBase*
• source : string

Methods

• void setSource(string source)

Detailed Description

Loader can load a pre-compiled QML component (using the source 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"
    }
}

Allocation

The Qt Quick Ultralite Loader allocates its items using the QmlDynamicObjects memory allocator.

The allocation happens each time the source 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.

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"
}

Limitations

Behavioral and functional differences

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 object introspection system.

This limitation effectively disables interactions (reading/writing properties or 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
}

View Delegates

The Qt Quick Ultralite Loader cannot be used within a View Delegate.

See also Known Issues or Limitations.

Property Documentation

Method Documentation

Available under certain Qt licenses.
Find out more.