diff options
Diffstat (limited to 'src/doc/src/declarative/qmlviews.qdoc')
| -rw-r--r-- | src/doc/src/declarative/qmlviews.qdoc | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/src/doc/src/declarative/qmlviews.qdoc b/src/doc/src/declarative/qmlviews.qdoc new file mode 100644 index 00000000..f5020e0e --- /dev/null +++ b/src/doc/src/declarative/qmlviews.qdoc @@ -0,0 +1,114 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qml-views.html +\ingroup qml-features +\contentspage QML Features +\previouspage {QML Data Models}{Structuring Data with Models} +\nextpage {Extending QML Functionalities using C++} +\title Presenting 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 +\li \l{WebView}{WebView} - available from the \l {QtWebKit QML Module}. +\endlist +Unlike other views, \l WebView is not a fully-featured view item, and needs +to be combined with a \l Flickable item to create a view that performs like +a Web browser. + +These elements have properties and behaviors exclusive to each element. Visit +their respective documentation for more information. + +\section1 Models + +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}. + +To assign a model to a view, bind the view's \c model property to a model. +\snippet doc/src/snippets/declarative/listview.qml model +\snippet doc/src/snippets/declarative/listview.qml view + +For more information, consult the \l {QML Data Models} article. + +\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/declarative/listview.qml delegate +\image listview-setup.png + +\section1 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/declarative/listview-decorations.qml model +\snippet doc/src/snippets/declarative/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/declarative/listview-decorations.qml decorations +\image listview-decorations.png + +\section1 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/declarative/listview-sections.qml model +\snippet doc/src/snippets/declarative/listview-sections.qml delegate + +The ListView element has the \c section +\l{Property Binding#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/declarative/listview-sections.qml section +\image listview-section.png +*/ |