doc/src/qtquick1/qmlviews.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: http://www.qt-project.org/
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qml-views.html
  30 \inqmlmodule QtQuick 1
  31 \ingroup qml-features
  32 \contentspage QML Features
  33 \previouspage {QML Data Models}{Structuring Data with Models}
  34 \nextpage {Extending QML Functionalities using C++}
  35 \title Presenting Data with Views
  36
  37 Views are containers for collections of items. They are feature-rich and can be
  38 customizable to meet style or behavior requirements.
  39
  40 \keyword qml-view-elements
  41 A set of standard views are provided in the basic set of Qt Quick
  42 graphical elements:
  43
  44 \list
  45 \o \l{ListView} arranges items in a horizontal or vertical list
  46 \o \l{GridView} arranges items in a grid within the available space
  47 \o \l{PathView} arranges items on a path
  48 \o \l{WebView}{WebView} - available from the \l {QtWebKit QML Module}.
  49 \endlist
  50 Unlike other views, \l WebView is not a fully-featured view item, and needs
  51 to be combined with a \l Flickable item to create a view that performs like
  52 a Web browser.
  53
  54 These elements have properties and behaviors exclusive to each element. Visit
  55 their respective documentation for more information.
  56
  57 \section1 Models
  58
  59 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}.
  60
  61 To assign a model to a view, bind the view's \c model property to a model.
  62 \snippet doc/src/snippets/declarative/listview.qml model
  63 \snippet doc/src/snippets/declarative/listview.qml model
  64
  65 For more information, consult the \l {QML Data Models} article.
  66
  67 \keyword qml-view-delegate
  68 \section1 View Delegates
  69
  70 Views need a \e delegate to visually represent an item in a list. A view will
  71 visualize each item list according to the template defined by the delegate.
  72 Items in a model are accessible through the \c index property as well as the
  73 item's properties.
  74 \snippet doc/src/snippets/declarative/listview.qml delegate
  75 \image listview-setup.png
  76
  77 \section1 Decorating Views
  78
  79 Views allow visual customization through \e decoration properties such as the \c header, \c footer, and \c section properties. By binding an object, usually
  80 another visual object, to these properties, the views are decoratable. A footer
  81 may include a \l Rectangle element showcasing borders or a header that displays
  82 a logo on top of the list.
  83
  84 Suppose that a specific club wants to decorate its members list with its brand
  85 colors. A member list is in a \c model and the \c delegate will display the
  86 model's content.
  87 \snippet doc/src/snippets/declarative/listview-decorations.qml model
  88 \snippet doc/src/snippets/declarative/listview-decorations.qml delegate
  89
  90 The club may decorate the members list by binding visual objects to the
  91 \c header and \c footer properties. The visual object may be defined inline, in another file, or in a
  92 \l {Component} element.
  93 \snippet doc/src/snippets/declarative/listview-decorations.qml decorations
  94 \image listview-decorations.png
  95
  96 \section1 Mouse/touch Handling
  97
  98 The views handle dragging and flicking of their content, however they do
  99 not handle touch interaction with the individual delegates.  In order for the
 100 delegates to react to touch input, e.g. to set the \c currentIndex, a MouseArea
 101 with the appropriate touch handling logic must be provided by the delegate.
 102
 103 Note that if \c highlightRangeMode is set to \c StrictlyEnforceRange the
 104 currentIndex will be affected by dragging/flicking the view, since the view
 105 will always ensure that the \c currentIndex is within the highlight range
 106 specified.
 107
 108
 109 \section1 ListView Sections
 110
 111 \l {ListView} contents may be grouped into \e sections, where related list items
 112 are labeled according to their sections. Further, the sections may be decorated
 113 with \l{qml-view-delegate}{delegates}.
 114
 115 A list may contain a list indicating people's names and the team on which team
 116 the person belongs.
 117 \snippet doc/src/snippets/declarative/listview-sections.qml model
 118 \snippet doc/src/snippets/declarative/listview-sections.qml delegate
 119
 120 The ListView element has the \c section
 121 \l{Property Binding#Attached Properties}{attached property} that can combine
 122 adjacent and related elements into a section. The section's \c property
 123 property is for selecting which list element property to use as sections.
 124 The \c criteria can dictate how the section names are displayed and the
 125 \c delegate is similar to the views' \l {qml-view-delegate}{delegate} property.
 126 \snippet doc/src/snippets/declarative/listview-sections.qml section
 127 \image listview-section.png
 128 */