diff options
Diffstat (limited to 'doc/src/qtquick2/modelview.qdoc')
| -rw-r--r-- | doc/src/qtquick2/modelview.qdoc | 378 |
1 files changed, 0 insertions, 378 deletions
diff --git a/doc/src/qtquick2/modelview.qdoc b/doc/src/qtquick2/modelview.qdoc deleted file mode 100644 index 28f5a5766b..0000000000 --- a/doc/src/qtquick2/modelview.qdoc +++ /dev/null @@ -1,378 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ -/*! -\page qtquick-modelview.html -\title Models and Views -\brief how to display and form data in QML - -Simply put, applications need to form data and display the data. QML has the -notion of \e models, \e views, and \e delegates to display data. They modularize -the visualization of data in order to give the developer or designer control -over the different aspects of the data. A developer can swap a list view with a -grid view with little changes to the data. Similarly, encapsulating an instance -of the data in a delegate allows the developer to dictate how to present or -handle the data. - -\image modelview-overview.png -\list -\li \b Model - contains the data and its structure. There are several QML -elements for creating models. -\li \b View - a container that displays the data. The view might -display the data in a list or a grid. -\li \b Delegate - dictates how the data should appear in the view. -The delegate takes each data in the model and encapsulates it. The data is -accessible through the delegate. -\endlist - -To visualize data, bind the view's \c model property to a model and the -\c delegate property to a component or an element. - -\section1 Displaying Data with Views - - Views are containers for collections of items. They are feature-rich and can be - customizable to meet style or behavior requirements. - - \keyword qml-view-elements - A set of standard views are provided in the basic set of Qt Quick - graphical elements: - - \list - \li \l{ListView} - arranges items in a horizontal or vertical list - \li \l{GridView} - arranges items in a grid within the available space - \li \l{PathView} - arranges items on a path - \endlist - - These elements have properties and behaviors exclusive to each element. - Visit their respective documentation for more information. - - \section2 Decorating Views - - Views allow visual customization through \e decoration properties such as - the \c header, \c footer, and \c section properties. By binding an object, - usually another visual object, to these properties, the views are - decoratable. A footer may include a \l Rectangle element showcasing borders - or a header that displays a logo on top of the list. - - Suppose that a specific club wants to decorate its members list with its brand - colors. A member list is in a \c model and the \c delegate will display the - model's content. - \snippet doc/src/snippets/qml/listview-decorations.qml model - \snippet doc/src/snippets/qml/listview-decorations.qml delegate - - The club may decorate the members list by binding visual objects to the \c - header and \c footer properties. The visual object may be defined inline, in - another file, or in a \l {Component} element. - \snippet doc/src/snippets/qml/listview-decorations.qml decorations - \image listview-decorations.png - - \section2 Mouse and Touch Handling - - The views handle dragging and flicking of their content, however they do - not handle touch interaction with the individual delegates. In order for the - delegates to react to touch input, e.g. to set the \c currentIndex, a MouseArea - with the appropriate touch handling logic must be provided by the delegate. - - Note that if \c highlightRangeMode is set to \c StrictlyEnforceRange the - currentIndex will be affected by dragging/flicking the view, since the view - will always ensure that the \c currentIndex is within the highlight range - specified. - - - \section2 ListView Sections - - \l {ListView} contents may be grouped into \e sections, where related list - items are labeled according to their sections. Further, the sections may be - decorated with \l{qml-view-delegate}{delegates}. - - A list may contain a list indicating people's names and the team on which - team the person belongs. - \snippet doc/src/snippets/qml/listview-sections.qml model - \snippet doc/src/snippets/qml/listview-sections.qml delegate - - The ListView element has the \c section \l{Property Binding in QML#Attached - Properties}{attached property} that can combine adjacent and related - elements into a section. The section's \c property property is for selecting - which list element property to use as sections. The \c criteria can dictate - how the section names are displayed and the \c delegate is similar to the - views' \l {qml-view-delegate}{delegate} property. - \snippet doc/src/snippets/qml/listview-sections.qml section - \image listview-section.png - -\keyword qml-view-delegate -\section1 View Delegates - - Views need a \e delegate to visually represent an item in a list. A view will - visualize each item list according to the template defined by the delegate. - Items in a model are accessible through the \c index property as well as the - item's properties. - \snippet doc/src/snippets/qml/listview.qml delegate - \image listview-setup.png - - \section2 Accessing Views and Models from Delegates - - The list view to which the delegate is bound is accessible from the delegate - through the \c{ListView.view} property. Likewise, the GridView - \c{GridView.view} is available to delegates. The corresponding model and its - properties, therefore, are available through \c{ListView.view.model}. In - addition, any defined signals or methods in the model are also accessible. - - This mechanism is useful when you want to use the same delegate for a number - of views, for example, but you want decorations or other features to be - different for each view, and you would like these different settings to be - properties of each of the views. Similarly, it might be of interest to - access or show some properties of the model. - - In the following example, the delegate shows the property \e{language} of - the model, and the color of one of the fields depends on the property - \e{fruit_color} of the view. - - \snippet doc/src/snippets/qml/models/views-models-delegates.qml rectangle - -\keyword qml-data-models -\section1 Models - - Data is provided to the delegate via named data roles which the delegate may - bind to. Here is a ListModel with two roles, \e type and \e age, and a - ListView with a delegate that binds to these roles to display their values: - - \snippet doc/src/snippets/qml/qml-data-models/listmodel-listview.qml document - - If there is a naming clash between the model's properties and the delegate's - properties, the roles can be accessed with the qualified \e model name - instead. For example, if a \l Text element had \e type or \e age properties, - the text in the above example would display those property values instead of - the \e type and \e age values from the model item. In this case, the - properties could have been referenced as \c model.type and \c model.age - instead to ensure the delegate displays the property values from the model - item. - - A special \e index role containing the index of the item in the model is - also available to the delegate. Note this index is set to -1 if the item is - removed from the model. If you bind to the index role, be sure that the - logic accounts for the possibility of index being -1, i.e. that the item is - no longer valid. (Usually the item will shortly be destroyed, but it is - possible to delay delegate destruction in some views via a \c delayRemove - attached property.) - - Models that do not have named roles (such as the ListModel shown - below) will have the data provided via the \e modelData role. The \e - modelData role is also provided for models that have only one role. In this - case the \e modelData role contains the same data as the named role. - - QML provides several types of data models among the built-in set of QML - elements. In addition, models can be created with Qt C++ and then made - available to the \l{The QML Engine}{QML engine} for use by - QML components. For information about creating these models, visit the - \l{Exposing C++ Models} and \l{Creating QML Types} articles. - - The use of positioner items to arrange items from a model is covered in - \l{Generating Items with Repeaters}. - - \section2 ListModel - - ListModel is a simple hierarchy of elements specified in QML. The - available roles are specified by the \l ListElement properties. - - \snippet doc/src/snippets/qml/qml-data-models/listelements.qml model - - The above model has two roles, \e name and \e cost. These can be bound - to by a ListView delegate, for example: - - \snippet doc/src/snippets/qml/qml-data-models/listelements.qml view - - ListModel provides methods to manipulate the ListModel directly via JavaScript. - In this case, the first item inserted determines the roles available - to any views that are using the model. For example, if an empty ListModel is - created and populated via JavaScript, the roles provided by the first - insertion are the only roles that will be shown in the view: - - \snippet doc/src/snippets/qml/qml-data-models/dynamic-listmodel.qml model - \dots - \snippet doc/src/snippets/qml/qml-data-models/dynamic-listmodel.qml mouse area - - When the MouseArea is clicked, \c fruitModel will have two roles, \e cost and \e name. - Even if subsequent roles are added, only the first two will be handled by views - using the model. To reset the roles available in the model, call ListModel::clear(). - - - \section2 XmlListModel - - XmlListModel allows construction of a model from an XML data source. The roles - are specified via the \l XmlRole element. The element needs to be imported. - - \code - import QtQuick.XmlListModel 2.0 - \endcode - - - The following model has three roles, \e title, \e link and \e description: - \qml - XmlListModel { - id: feedModel - source: "http://rss.news.yahoo.com/rss/oceania" - query: "/rss/channel/item" - XmlRole { name: "title"; query: "title/string()" } - XmlRole { name: "link"; query: "link/string()" } - XmlRole { name: "description"; query: "description/string()" } - } - \endqml - - The \l{declarative/rssnews}{RSS News demo} shows how XmlListModel can - be used to display an RSS feed. - - - \section2 VisualItemModel - - VisualItemModel allows QML items to be provided as a model. - - This model contains both the data and delegate; the child items of a - VisualItemModel provide the contents of the delegate. The model - does not provide any roles. - - \snippet doc/src/snippets/qml/models/visual-model-and-view.qml visual model and view - - Note that in the above example there is no delegate required. - The items of the model itself provide the visual elements that - will be positioned by the view. - - \section2 Integers as Models - - An integer can be used as a model that contains a certain number - of elements. In this case, the model does not have any data roles. - - The following example creates a ListView with five elements: - \qml - Item { - width: 200; height: 250 - - Component { - id: itemDelegate - Text { text: "I am item number: " + index } - } - - ListView { - anchors.fill: parent - model: 5 - delegate: itemDelegate - } - - } - \endqml - - - \section2 Object Instances as Models - - An object instance can be used to specify a model with a single object - element. The properties of the object are provided as roles. - - The example below creates a list with one item, showing the color of the \e - myText text. Note the use of the fully qualified \e model.color property to - avoid clashing with \e color property of the Text element in the delegate. - - \qml - Rectangle { - width: 200; height: 250 - - Text { - id: myText - text: "Hello" - color: "#dd44ee" - } - - Component { - id: myDelegate - Text { text: model.color } - } - - ListView { - anchors.fill: parent - anchors.topMargin: 30 - model: myText - delegate: myDelegate - } - } - \endqml - - \keyword qml-c++-models - \section2 C++ Data Models - - Models can be defined in C++ and then made available to QML. This mechanism - is useful for exposing existing C++ data models or otherwise complex - datasets to QML. - - For information, visit the \l{Exposing C++ Models} article. - - -\section1 Repeaters - -\div {class="float-right"} -\inlineimage repeater-index.png -\enddiv - -Repeaters create items from a template for use with positioners, using data -from a model. Combining repeaters and positioners is an easy way to lay out -lots of items. A \l Repeater item is placed inside a positioner, and generates -items that the enclosing positioner arranges. - -Each Repeater creates a number of items by combining each element of data -from a model, specified using the \l{Repeater::model}{model} property, with -the template item, defined as a child item within the Repeater. -The total number of items is determined by the amount of data in the model. - -The following example shows a repeater used with a \l{#Grid}{Grid} item to -arrange a set of Rectangle items. The Repeater item creates a series of 24 -rectangles for the Grid item to position in a 5 by 5 arrangement. - -\snippet doc/src/snippets/qml/repeaters/repeater-grid-index.qml document - -The number of items created by a Repeater is held by its \l{Repeater::}{count} -property. It is not possible to set this property to determine the number of -items to be created. Instead, as in the above example, we use an integer as -the model. This is explained in the \l{QML Data Models#An Integer}{QML Data Models} -document. - -It is also possible to use a delegate as the template for the items created -by a Repeater. This is specified using the \l{Repeater::}{delegate} property. - -\section1 Using Transitions - -Transitions can be used to animate items that are added to, moved within, -or removed from a positioner. - -Transitions for adding items apply to items that are created as part of a -positioner, as well as those that are reparented to become children of a -positioner. -Transitions for removing items apply to items within a positioner that are -deleted, as well as those that are removed from a positioner and given new -parents in a document. - -Additionally, changing the opacity of items to zero will cause them to -disappear using the remove transition, and making the opacity non-zero will -cause them to appear using the add transition. - - -*/ |