Loader QML Type

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

• List of all members, including inherited members

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.

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

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

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

import MyModule

Item {
    Loader {
        sourceComponent: MyModuleItem {}
    }
}

Item {
    Component {
        id: redSquare
        Rectangle { color: "red"; width: 10; height: 10 }
    }

    Loader { sourceComponent: redSquare }
    Loader { sourceComponent: redSquare; x: 10 }
}

Signal Documentation

Method Documentation

Available under certain Qt licenses.
Find out more.