68     \brief The Repeater item allows you to repeat an Item-based component using a model.

    68     \brief The Repeater element allows you to repeat an Item-based component using a model.

    69 

    69 

    70     The Repeater item is used to create a large number of

    70     The Repeater element is used to create a large number of

    71     similar items.  For each entry in the model, an item is instantiated

    71     similar items. Like other view elements, a Repeater has a \l model and a \l delegate:

    72     in a context seeded with data from the model.  If the repeater will

    72     for each entry in the model, the delegate is instantiated

    73     be instantiating a large number of instances, it may be more efficient to

    73     in a context seeded with data from the model. A Repeater item is usually

    74     use one of Qt Declarative's \l {xmlViews}{view items}.

    74     enclosed in a positioner element such as \l Row or \l Column to visually

    75 

    75     position the multiple delegate items created by the Repeater.

    76     The model may be either an object list, a string list, a number or a Qt model.

    76 

    77     In each case, the data element and the index is exposed to each instantiated

    77     The following Repeater creates three instances of a \l Rectangle item within

    78     component.  

    78     a \l Row:

    79     

    79 

    80     The index is always exposed as an accessible \c index property.

    80     \snippet doc/src/snippets/declarative/repeater.qml import

    81     In the case of an object or string list, the data element (of type string

    81     \codeline

    82     or object) is available as the \c modelData property.  In the case of a Qt model,

    82     \snippet doc/src/snippets/declarative/repeater.qml simple

    83     all roles are available as named properties just like in the view classes. The

    83 

    84     following example shows how to use the index property inside the instantiated

    84     \image repeater-simple.png

    85     items.

    85 

    86 

    86     The \l model of a Repeater can be any of the supported \l {qmlmodels}{Data Models}.

    87     \snippet doc/src/snippets/declarative/repeater-index.qml 0

    88 

    89     \image repeater-index.png

    93     the repeater's position in its parent stacking list.  This is to allow

    90     the repeater's position in its parent stacking list.  This allows

    94     you to use a Repeater inside a layout.  The following QML example shows how

    91     a Repeater to be used inside a layout. For example, the following Repeater's

    95     the instantiated items would visually appear stacked between the red and

    92     items are stacked between a red rectangle and a blue rectangle:

    96     blue rectangles.

    93    

    97 

    94     \snippet doc/src/snippets/declarative/repeater.qml layout

    98     \snippet doc/src/snippets/declarative/repeater.qml 0

   102     The repeater instance continues to own all items it instantiates, even

    98 

   103     if they are otherwise manipulated.  It is illegal to manually remove an item

    99     \section2 The \c index and \c modelData properties

   104     created by the Repeater.

   100 

   105 

   101     The index of a delegate is exposed as an accessible \c index property in the delegate.

   106     \note Repeater is Item-based, and cannot be used to repeat non-Item-derived objects.

   102     Properties of the model are also available depending upon the type of \l {qmlmodels}{Data Model}.

   107     For example, it cannot be used to repeat QtObjects.

   103 

   104     Here is a Repeater that uses the \c index property inside the instantiated items:

   105 

   106     \table

   107     \row

   108     \o \snippet doc/src/snippets/declarative/repeater.qml index

   109     \o \image repeater-index.png

   110     \endtable

   111 

   112     Here is another Repeater that uses the \c modelData property to reference the data for a

   113     particular index:

   114 

   115     \table

   116     \row

   117     \o \snippet doc/src/snippets/declarative/repeater.qml modeldata

   118     \o \image repeater-modeldata.png

   119     \endtable

   120 

   121 

   122     A Repeater item owns all items it instantiates. Removing or dynamically destroying

   123     an item created by a Repeater results in unpredictable behavior.

   124 

   125 

   126     \section2 Considerations when using Repeater

   127 

   128     The Repeater element creates all of its delegate items when the repeater is first

   129     created. This can be inefficient if there are a large number of delegate items and

   130     not all of the items are required to be visible at the same time. If this is the case,

   131     consider using other view elements like ListView (which only creates delegate items 

   132     when they are scrolled into view) or use the \l {Dynamic Object Creation} methods to 

   133     create items as they are required.

   134 

   135     Also, note that Repeater is \l {Item}-based, and can only repeat \l {Item}-derived objects. 

   136     For example, it cannot be used to repeat QtObjects:

   110         //XXX illegal. Can't repeat QtObject as it doesn't derive from Item.

   139         //XXX does not work! Can't repeat QtObject as it doesn't derive from Item.

   146     The model may be either an object list, a string list, a number or a Qt model.

   174     This property can be set to any of the following:

   175 

   176     \list

   177     \o A number that indicates the number of delegates to be created

   178     \o A model (e.g. a ListModel item, or a QAbstractItemModel subclass)

   179     \o A string list

   180     \o An object list

   181     \endlist

   182