From 2d4e6ff9dd1e0e3410c4dc002c25d80fecfeafd2 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Thu, 9 Feb 2012 17:31:02 +0100 Subject: Doc: Overhaul of doc/src/declarative and QtQuick2 docs. -Consolidated model/view documentation into one. -Added a new navigation for all overviews (grouped the pages) -New front page that shows the grouping -Separated the Qt C++ from the main QML overviews -Consolidated Qt C++ into the "declarative runtime" section -New articles about JavaScript, the engine, and plugins -Fixed the older examples. New snippet comments -Renamed some of the articles -kept the qtquick2 qmlmodule -"Qt Quick Elements" Moved contents of doc/src/declarative into respective module dirs. -Qt Quick 2, LocalStorage, Particles, and QML are now separate. -Removed unused or duplicate documentation. -edited C++ examples -removed navigation and "\inqmlmodule QtQuick 2" for those pages that are not in Qt Quick 2 -fixed doc/src/ licenses to header.FDL from qtbase Change-Id: Ib36f9c07565d91160fa8d04f9670c438f684b82a Reviewed-by: Sergio Ahumada --- doc/src/examples/dynamicview-tutorial.qdoc | 246 +++++++++++++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 doc/src/examples/dynamicview-tutorial.qdoc (limited to 'doc/src/examples/dynamicview-tutorial.qdoc') diff --git a/doc/src/examples/dynamicview-tutorial.qdoc b/doc/src/examples/dynamicview-tutorial.qdoc new file mode 100644 index 0000000000..517dacc2f1 --- /dev/null +++ b/doc/src/examples/dynamicview-tutorial.qdoc @@ -0,0 +1,246 @@ +/**************************************************************************** +** +** 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 qml-dynamicview-tutorial.html +\inqmlmodule QtQuick 2 +\title QML Dynamic View Ordering Tutorial +\brief A tutorial describing how to re-arrange items in a QML ListView +\nextpage QML Dynamic View Ordering Tutorial 1 - A Simple ListView and Delegate + +This tutorial shows how items in a ListView can be re-ordered without modifying the source model. +It demonstrates using drag and drop to reposition individual items within a view and using model +data to dynamically sort all items in a view. + +Tutorial chapters: + +\list 1 +\o \l {declarative/tutorials/dynamicview/dynamicview1}{A Simple ListView and Delegate} +\o \l {declarative/tutorials/dynamicview/dynamicview2}{Dragging View Items} +\o \l {declarative/tutorials/dynamicview/dynamicview3}{Moving Dragged Items} +\o \l {declarative/tutorials/dynamicview/dynamicview4}{Sorting Items} +\endlist + +All the code in this tutorial can be found in Qt's \c examples/declarative/tutorials/dynamicview +directory. +*/ + +/*! +\page qml-dynamicview-tutorial1.html +\inqmlmodule QtQuick 2 +\title QML Dynamic View Ordering Tutorial 1 - A Simple ListView and Delegate +\contentspage QML Dynamic View Ordering Tutorial +\previouspage QML Dynamic View Ordering Tutorial +\nextpage QML Dynamic View Ordering Tutorial 2 - Dragging View Items + +\example declarative/tutorials/dynamicview/dynamicview1 + +We begin our application by defining a ListView, a model which will provide data to the view, and a +delegate which provides a template for constructing items in the view. + +The code for the ListView and delegate looks like this: + +\snippet declarative/tutorials/dynamicview/dynamicview1/dynamicview.qml 0 + +The model is defined in a separate QML file which looks like this: + +\snippet declarative/tutorials/dynamicview/dynamicview1/PetsModel.qml 0 +\snippet declarative/tutorials/dynamicview/dynamicview1/PetsModel.qml 1 + +\section2 Walkthrough + +The first item defined within the application's root Rectangle is the delegate Component. This +is the template from which each item in the ListView is constructed. + +The \c name, \c age, \c type, and \c size variables referenced in the delegate are sourced from +the model data. The names correspond to roles defined in the model. + +\snippet declarative/tutorials/dynamicview/dynamicview1/dynamicview.qml 1 + +The second part of the application is the ListView itself to which we bind the model and delegate. + +\snippet declarative/tutorials/dynamicview/dynamicview1/dynamicview.qml 2 +*/ + +/*! +\page qml-dynamicview-tutorial2.html +\inqmlmodule QtQuick 2 +\title QML Dynamic View Ordering Tutorial 2 - Dragging View Items +\contentspage QML Dynamic View Ordering Tutorial +\previouspage QML Dynamic View Ordering Tutorial 1 - A Simple ListView and Delegate +\nextpage QML Dynamic View Ordering Tutorial 3 - Moving Dragged Items + +\example declarative/tutorials/dynamicview/dynamicview2 + +Now that we have a visible list of items we want to be able to interact with them. We'll start +by extending the delegate so the visible content can be dragged up and down the screen. The +updated delegate looks like this: + +\snippet declarative/tutorials/dynamicview/dynamicview2/dynamicview.qml 0 + +\section2 Walkthrough + +The major change here is the root item of the delegate is now a MouseArea which provides handlers +for mouse events and will allow us to drag the delegate's content item. It also acts as +a container for the content item which is important as a delegate's root item is positioned by +the view and cannot be moved by other means. + +\snippet declarative/tutorials/dynamicview/dynamicview2/dynamicview.qml 1 +\snippet declarative/tutorials/dynamicview/dynamicview2/dynamicview.qml 2 + +Dragging the content item is enabled by binding it to the MouseArea's +\l {QtQuick2::MouseArea::drag.target}{drag.target} property. Because we still want the view to be +flickable we wait until the MouseArea's \l {QtQuick2::MouseArea::onPressAndHold}{onPressAndHold} +handler is triggered before binding the drag target. This way when mouse moves before the hold +timeout has expired it is interpreted as moving the list and if it moves after it is interpreted as +dragging an item. To make it more obvious to the user when an item can be dragged we'll change the +background color of the content item when the timeout has expired. + +\snippet declarative/tutorials/dynamicview/dynamicview2/dynamicview.qml 3 + +The other thing we'll need to do before an item can be dragged is to unset any anchors on the +content item so it can be freely moved around. We do this in a state change that is triggered +when the delegate item is held, at the same time we can reparent the content item to the root item +so that is above other items in the stacking order and isn't obscured as it is dragged around. + +\snippet declarative/tutorials/dynamicview/dynamicview2/dynamicview.qml 4 + +*/ + +/*! +\page qml-dynamicview-tutorial3.html +\inqmlmodule QtQuick 2 +\title QML Dynamic View Ordering Tutorial 3 - Moving Dragged Items +\contentspage QML Dynamic View Ordering Tutorial +\previouspage QML Dynamic View Ordering Tutorial 2 - Dragging View Items +\nextpage QML Dynamic View Ordering Tutorial 4 - Sorting Items + +\example declarative/tutorials/dynamicview/dynamicview3 + +The next step in our application to move items within the list as they're dragged so that we +can re-order the list. To achieve this we introduce three new elements to our application; +VisualDataModel, \l Drag and DropArea. + +\snippet declarative/tutorials/dynamicview/dynamicview3/dynamicview.qml 0 +\snippet declarative/tutorials/dynamicview/dynamicview3/dynamicview.qml 1 +\snippet declarative/tutorials/dynamicview/dynamicview3/dynamicview.qml 2 +\snippet declarative/tutorials/dynamicview/dynamicview3/dynamicview.qml 5 + +\section2 Walkthrough + +In order to re-order the view we need to determine when one item has been dragged over another. With +the Drag attached property we can generate events that are sent to the scene graph whenever the item +it is attached to moves. + +\snippet declarative/tutorials/dynamicview/dynamicview3/dynamicview.qml 1 + +Drag events are only sent while the active property is true, so in this example the first event +would be sent when the delegate was held with additional event sents when dragging. The +\l {QtQuick2::Drag::hotSpot}{hotSpot} property specifies the relative position of the drag events +within the dragged item, the center of the item in this instance. + +Then we use a DropArea in each view item to determine when the hot spot of the dragged item +intersects another item, when a drag enters one of these DropAreas we can move the dragged item +to the index of the item it was dragged over. + +\snippet declarative/tutorials/dynamicview/dynamicview3/dynamicview.qml 3 + +To move the items within the view we use a VisualDataModel. The VisualDataModel element is used by +the view elements to instantiate delegate items from model data and when constructed explicitly can +be used to filter and re-order the model items provided to ListView. The +\l {QtQuick2::VisualDataModel::items}{items} property of VisualDataModel provides access to the +view's items and allows us to change the visible order without modifying the source model. To +determine the current visible index of the items we use \l {QtQuick2::VisualDataModel::itemsIndex} +{itemsIndex} property on the VisualDataModel attached property of the delegate item. + +To utilize a VisualDataModel with a ListView we bind it to the \l {QtQuick2::ListView::model}{model} +property of the view and bind the \l {QtQuick2::VisualDataModel::model}{model} and +\l {QtQuick2::VisualDataModel::delegate}{delegate} to the VisualDataModel. + +\snippet declarative/tutorials/dynamicview/dynamicview3/dynamicview.qml 4 + +*/ + +/*! +\page qml-dynamicview-tutorial4.html +\inqmlmodule QtQuick 2 +\title QML Dynamic View Ordering Tutorial 4 - Sorting Items +\contentspage QML Dynamic View Ordering Tutorial +\previouspage QML Dynamic View Ordering Tutorial 3 - Moving Dragged Items + +\example declarative/tutorials/dynamicview/dynamicview4 + +Drag and drop isn't the only way items in a view can be re-ordered, using a VisualDataModel it is +also possible to sort items based on model data. To do that we extend our VisualDataModel instance +like this: + +\snippet declarative/tutorials/dynamicview/dynamicview4/dynamicview.qml 0 + +\section2 Walkthrough + +Items in a VisualDataModel are filtered into groups represented by the VisualDataGroup type, +normally all items in the model belong to a default \l {QtQuick2::VisualDataModel::items}{items} +group but this default can be changed with the includeByDefault property. To implement our sorting +we want items to first be added to an unsorted group from where we can transfer them to a sorted +position in the items group. To do that we clear includeByDefault on the items group and set it on +a new group name 'unsorted'. + +\snippet declarative/tutorials/dynamicview/dynamicview4/dynamicview.qml 1 +\snippet declarative/tutorials/dynamicview/dynamicview4/dynamicview.qml 2 + +We sort the items by first finding the position in the items group to insert the first unsorted +item and then transfer the item to the items group before moving it to the pre-determined index and +repeat until the unsorted group is empty. + +To find the insert position for an item we request a handle for the item from the unsorted group +with the \l {QtQuick2::VisualDataModel::get} {get} function. Through the model property on this +handle we can access the same model data that is available in a delegate instance of that item and +compare against other items to determine relative position. + +\snippet declarative/tutorials/dynamicview/dynamicview4/dynamicview.qml 3 + +The lessThan argument to the sort function is a comparsion function which will determine the order +of the list. In this example it can be one of the following: + +\snippet declarative/tutorials/dynamicview/dynamicview4/dynamicview.qml 4 + +A sort is triggered whenever new items are added to the unsorted VisualDataGroup which we are +notified of by the \l {QtQuick2::VisualDataGroup::onChanged}{onChanged} handler. If no sort +function is currently selected we simply transfer all items from the unsorted group to the items +group, otherwise we call sort with the selected sort function. + +\snippet declarative/tutorials/dynamicview/dynamicview4/dynamicview.qml 5 + +Finally when the selected sort order changes we can trigger a full re-sort of the list by moving +all items from the items group to the unsorted group, which will trigger the +\l {QtQuick2::VisualDataGroup::onChanged}{onChanged} handler and transfer the items back to the +items group in correct order. Note that the \l {QtQuick2::VisualDataGroup::onChanged}{onChanged} +handler will not be invoked recursively so there's no issue with it being invoked during a sort. + +\snippet declarative/tutorials/dynamicview/dynamicview4/dynamicview.qml 6 + +*/ -- cgit v1.2.3