117     The Loader element instantiates an item from a component. The component to

   118     Loader is used to dynamically load visual QML components. It can load a

   118     be instantiated may be specified directly by the \l sourceComponent

   119     QML file (using the \l source property) or a \l Component object (using 

   119     property, or loaded from a URL via the \l source property.

   120     the \l sourceComponent property). It is useful for delaying the creation 

   120 

   121     of a component until it is required: for example, when a component should 

   121     Loader can be used to delay the creation of a component until it

   122     be created on demand, or when a component should not be created 

   122     is required.  For example, this loads "Page1.qml" as a component

   123     unnecessarily for performance reasons.

   123     into the Loader element, when the \l MouseArea is clicked:

   124 

   124 

   125     Here is a Loader that loads "Page1.qml" as a component when the 

   125     \code

   126     \l MouseArea is clicked:

   126     import Qt 4.7

   127 

   127 

   128     \snippet doc/src/snippets/declarative/loader/simple.qml 0

   128     Item {

   129 

   129         width: 200; height: 200

   130     The loaded item can be accessed using the \l item property.

   130 

   131 

   131         MouseArea { 

   132     Loader is like any other visual item and must be positioned and sized 

   132             anchors.fill: parent

   133     accordingly to become visible. Once the component is loaded, the Loader 

   133             onClicked: pageLoader.source = "Page1.qml"

   134     is automatically resized to the size of the component.

   134         }

   135 

   135 

   136     If the \l source or \l sourceComponent changes, any previously instantiated

   136         Loader { id: pageLoader }

   137     items are destroyed. Setting \l source to an empty string or setting

   137     }

   138     \l sourceComponent to \c undefined destroys the currently loaded item,

   138     \endcode

   139     freeing resources and leaving the Loader empty.

   139 

   140 

   140     Note that Loader is like any other graphical Item and needs to be positioned 

   141 

   141     and sized accordingly to become visible. When a component is loaded, the 

   142     \section2 Receiving signals from loaded items

   142     Loader is automatically resized to the size of the component.

   143 

   143 

   144     Any signals emitted from the loaded item can be received using the 

   144     If the Loader source is changed, any previous items instantiated

   145     \l Connections element. For example, the following \c application.qml

   145     will be destroyed.  Setting \l source to an empty string, or setting

   146     loads \c MyItem.qml, and is able to receive the \c message signal from

   146     sourceComponent to \e undefined

   147     the loaded item through a \l Connections object:

   147     will destroy the currently instantiated items, freeing resources

   148 

   148     and leaving the Loader empty.  For example:

   149     \table

   149 

   150     \row 

   150     \code

   151     \o application.qml

   151     pageLoader.source = ""

   152     \o MyItem.qml

   152     \endcode

   153     \row

   153 

   154     \o \snippet doc/src/snippets/declarative/loader/connections.qml 0

   154       or

   155     \o \snippet doc/src/snippets/declarative/loader/MyItem.qml 0

   155 

   156     \endtable

   156     \code

   157 

   157     pageLoader.sourceComponent = undefined

   158     Alternatively, since \c MyItem.qml is loaded within the scope of the

   158     \endcode

   159     Loader, it could also directly call any function defined in the Loader or

   159 

   160     its parent \l Item.

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

   161 

   162 

   163     \section2 Focus and key events

   164 

   165     Loader is a focus scope. Its \l {Item::}{focus} property must be set to 

   166     \c true for any of its children to get the \e {active focus}. (See 

   167     \l{qmlfocus#Acquiring Focus and Focus Scopes}{the focus documentation page} 

   168     for more details.) Any key events received in the loaded item should likely

   169     also be \l {KeyEvent::}{accepted} so they are not propagated to the Loader.

   170 

   171     For example, the following \c application.qml loads \c KeyReader.qml when

   172     the \l MouseArea is clicked.  Notice the \l {Item::}{focus} property is 

   173     set to \c true for the Loader as well as the \l Item in the dynamically 

   174     loaded object:

   175 

   176     \table

   177     \row 

   178     \o application.qml

   179     \o KeyReader.qml

   180     \row

   181     \o \snippet doc/src/snippets/declarative/loader/focus.qml 0

   182     \o \snippet doc/src/snippets/declarative/loader/KeyReader.qml 0

   183     \endtable

   184 

   185     Once \c KeyReader.qml is loaded, it accepts key events and sets 

   186     \c event.accepted to \c true so that the event is not propagated to the

   187     parent \l Rectangle.

   197     This property holds the URL of the QML component to

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

   198     instantiate.

   214 

   215     Note the QML component must be an \l Item-based component. Loader cannot

   216     load non-visual components.

   217 

   218     To unload the currently loaded item, set this property to an empty string,

   219     or set \l sourceComponent to \c undefined.

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

   278     To unload the currently loaded item, set this property to an empty string,

   279     or set \l sourceComponent to \c undefined.

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

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