doc/src/declarative/qmlviews.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Free Documentation License
  17 ** Alternatively, this file may be used under the terms of the GNU Free
  18 ** Documentation License version 1.3 as published by the Free Software
  19 ** Foundation and appearing in the file included in the packaging of this
  20 ** file.
  21 **
  22 ** If you have questions regarding the use of this file, please contact
  23 ** Nokia at qt-info@nokia.com.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qml-views.html
  30 \ingroup qml-features
  31 \contentspage QML Features
  32 \previouspage {QML Data Models}{Structuring Data with Models}
  33 \nextpage {Extending QML Functionalities using C++}
  34 \title Presenting Data with Views
  35
  36 Views are containers for collections of items. They are feature-rich and can be
  37 customizable to meet style or behavior requirements.
  38
  39 \keyword qml-view-elements
  40 A set of standard views are provided in the basic set of Qt Quick
  41 graphical elements:
  42
  43 \list
  44 \o \l{ListView} arranges items in a horizontal or vertical list
  45 \o \l{GridView} arranges items in a grid within the available space
  46 \o \l{PathView} arranges items on a path
  47 \o \l{WebView}{WebView} - available from the \l {QtWebKit QML Module}.
  48 \endlist
  49 Unlike other views, \l WebView is not a fully-featured view item, and needs
  50 to be combined with a \l Flickable item to create a view that performs like
  51 a Web browser.
  52
  53 These elements have properties and behaviors exclusive to each element. Visit
  54 their respective documentation for more information.
  55
  56 \section1 Models
  57
  58 Views display \l{qml-data-models}{models} onto the screen. A model could be a simple list of \l{QML Data Models#An Integer}{integer} or a \l{qml-c++-models}{C++ model}.
  59
  60 To assign a model to a view, bind the view's \c model property to a model.
  61 \snippet doc/src/snippets/declarative/listview.qml model
  62 \snippet doc/src/snippets/declarative/listview.qml model
  63
  64 For more information, consult the \l {QML Data Models} article.
  65
  66 \keyword qml-view-delegate
  67 \section1 View Delegates
  68
  69 Views need a \e delegate to visually represent an item in a list. A view will
  70 visualize each item list according to the template defined by the delegate.
  71 Items in a model are accessible through the \c index property as well as the
  72 item's properties.
  73 \snippet doc/src/snippets/declarative/listview.qml delegate
  74 \image listview-setup.png
  75
  76 \section1 Decorating Views
  77
  78 Views allow visual customization through \e decoration properties such as the \c header, \c footer, and \c section properties. By binding an object, usually
  79 another visual object, to these properties, the views are decoratable. A footer
  80 may include a \l Rectangle element showcasing borders or a header that displays
  81 a logo on top of the list.
  82
  83 Suppose that a specific club wants to decorate its members list with its brand
  84 colors. A member list is in a \c model and the \c delegate will display the
  85 model's content.
  86 \snippet doc/src/snippets/declarative/listview-decorations.qml model
  87 \snippet doc/src/snippets/declarative/listview-decorations.qml delegate
  88
  89 The club may decorate the members list by binding visual objects to the
  90 \c header and \c footer properties. The visual object may be defined inline, in another file, or in a
  91 \l {Component} element.
  92 \snippet doc/src/snippets/declarative/listview-decorations.qml decorations
  93 \image listview-decorations.png
  94
  95 \section1 ListView Sections
  96
  97 \l {ListView} contents may be grouped into \e sections, where related list items
  98 are labeled according to their sections. Further, the sections may be decorated
  99 with \l{qml-view-delegate}{delegates}.
 100
 101 A list may contain a list indicating people's names and the team on which team
 102 the person belongs.
 103 \snippet doc/src/snippets/declarative/listview-sections.qml model
 104 \snippet doc/src/snippets/declarative/listview-sections.qml delegate
 105
 106 The ListView element has the \c section
 107 \l{Property Binding#Attached Properties}{attached property} that can combine
 108 adjacent and related elements into a section. The section's \c property
 109 property is for selecting which list element property to use as sections.
 110 The \c criteria can dictate how the section names are displayed and the
 111 \c delegate is similar to the views' \l {qml-view-delegate}{delegate} property.
 112 \snippet doc/src/snippets/declarative/listview-sections.qml section
 113 \image listview-section.png
 114 */