Loader

This property is true if the Loader is currently active. The default value for the active property is true.

If the Loader is inactive, changing the source or sourceComponent will not cause the item to be instantiated until the Loader is made active.

Setting the value to inactive will cause any item loaded by the loader to be released, but will not affect the source or sourceComponent.

The status of an inactive loader is always Null.

See also source and sourceComponent.

This property holds whether the component will be instantiated asynchronously.

When used in conjunction with the source property, loading and compilation will also be performed in a background thread.

Loading asynchronously creates the objects declared by the component across multiple frames, and reduces the likelihood of glitches in animation. When loading asynchronously the status will change to Loader.Loading. Once the entire component has been created, the item will be available and the status will change to Loader.Ready.

To avoid seeing the items loading progressively set visible appropriately, e.g.

 Loader {
     source: "mycomponent.qml"
     asynchronous: true
     visible: status == Loader.Ready
 }

Note that this property affects object instantiation only; it is unrelated to loading a component asynchronously via a network.

This property holds the top-level item that is currently loaded.

This property holds the progress of loading QML data from the network, from 0.0 (nothing loaded) to 1.0 (finished). Most QML files are quite small, so this value will rapidly change from 0 to 1.

See also status.

This property holds the URL of the QML component to instantiate.

Note the QML component must be an Item-based component. The loader cannot load non-visual components.

To unload the currently loaded item, set this property to an empty string, or set sourceComponent to undefined. Setting source to a new URL will also cause the item created by the previous URL to be unloaded.

See also sourceComponent, status, and progress.

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 item, set this property to an empty string or undefined.

See also source and progress.

This property holds the status of QML loading. It can be one of:

• Loader.Null - the loader is inactive or no QML source has been set
• Loader.Ready - the QML source has been loaded
• Loader.Loading - the QML source is currently being 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 that if the source is a local file, the status will initially be Ready (or Error). While there will be no onStatusChanged signal in that case, the onLoaded will still be invoked.

See also progress.

This handler is called when the status becomes Loader.Ready, or on successful initial load.

Creates an object instance of the given source component that will have the given properties. The properties argument is optional. The instance will be accessible via 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 and initial properties will be cached. When the loader is made active, an instance of the source component will be created with the initial properties set.

Setting the initial property values of an instance of a component in this manner will not trigger any associated Behaviors.

Note that the cached properties will be cleared if the source or sourceComponent is changed after calling this function but prior to setting the loader active.

Example:

 // ExampleComponent.qml
 import QtQuick 2.0
 Rectangle {
     id: rect
     color: "red"
     width: 10
     height: 10

     Behavior on color {
         NumberAnimation {
             target: rect
             property: "width"
             to: (rect.width + 20)
             duration: 0
         }
     }
 }

 // example.qml
 import QtQuick 2.0
 Item {
     Loader {
         id: squareLoader
         onLoaded: console.log(squareLoader.item.width); // prints [10], not [30]
     }

     Component.onCompleted: {
         squareLoader.setSource("ExampleComponent.qml", { "color": "blue" });
         // will trigger the onLoaded code when complete.
     }
 }

See also source and active.