Qt Reference Documentation

QML Loader Element

The Loader item allows dynamically loading an Item-based subtree from a URL or Component. More...

Inherits Item

  • List of all members, including inherited members
  • Properties

    Signals

    Detailed Description

    The Loader element instantiates an item from a component. The component to be instantiated may be specified directly by the sourceComponent property, or loaded from a URL via the source property.

    Loader can be used to delay the creation of a component until it is required. For example, this loads "Page1.qml" as a component into the Loader element, when the MouseArea is clicked:

     import Qt 4.7
    
     Item {
         width: 200; height: 200
    
         MouseArea {
             anchors.fill: parent
             onClicked: pageLoader.source = "Page1.qml"
         }
    
         Loader { id: pageLoader }
     }

    Note that Loader is like any other graphical Item and needs to be positioned and sized accordingly to become visible. When a component is loaded, the Loader is automatically resized to the size of the component.

    If the Loader source is changed, any previous items instantiated will be destroyed. Setting source to an empty string, or setting sourceComponent to undefined will destroy the currently instantiated items, freeing resources and leaving the Loader empty. For example:

     pageLoader.source = ""

    or

     pageLoader.sourceComponent = undefined

    unloads "Page1.qml" and frees resources consumed by it.

    Note that Loader is a focus scope. Its focus property must be set to true for any of its children to get the active focus (see the focus documentation page for more details).

    See also Dynamic Object Creation.

    Property Documentation

    read-onlyitem : Item

    This property holds the top-level item created from source.


    read-onlyprogress : real

    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.


    source : url

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

    See also sourceComponent, status, and progress.


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

    Note this value must hold a Component object; it cannot be a Item.

    See also source and progress.


    read-onlystatus : enumeration

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

    • Loader.Null - 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 ? 'Not Loaded' : '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.


    Signal Documentation

    Loader::onLoaded ()

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


    X

    Thank you for giving your feedback.

    Make sure it is related to this specific page. For more general bugs and requests, please use the Qt Bug Tracker.