Doc: Add data model, view, and delegate properties

Describe using Qt Creator/Qt Design Studio to edit data
models.

Move Path View and Svg Path docs to the new topics using
\include files.

Fixes: QDS-3030
Change-Id: I1ea09e133a4f1fe20c6e89a6323158eb1ce16c33
Reviewed-by: Thomas Hartmann <thomas.hartmann@qt.io>

doc/qtcreator/src/qtcreator-toc.qdoc

@@ -98,6 +98,7 @@
                         \list
                             \li \l{Editing 2D Content}
                             \li \l{Shapes}
+                            \li \l{Lists and Other Data Models}
                             \li \l{Creating Buttons}
                             \li \l{Creating Scalable Buttons and Borders}
                         \endlist
@@ -120,7 +121,6 @@
                             \li \l{Managing C++ Backend Objects}
                         \endlist
                         \li \l {Adding States}
-                        \li \l {Editing PathView Properties}
                     \endlist
                 \li \l{Editing 3D Scenes}
                         \list

doc/qtcreator/src/qtquick/library/qtquick-data-models.qdoc

@@ -0,0 +1,255 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Creator documentation.
+**
+** 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 The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html.
+**
+****************************************************************************/
+
+/*!
+    \page quick-data-models.html
+    \previouspage quick-text.html
+    \nextpage quick-buttons.html
+
+    \title Lists and Other Data Models
+
+    Applications typically need to handle and display data that is organized
+    into list or grid views. Qt Quick uses models, views, and delegates for
+    this purpose. They modularize the visualization of data in order to give
+    you control over the different aspects of the data. For example, you 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
+    developers to dictate how to present or handle the data.
+
+    A \e model contains the data and its structure. There are several QML
+    types for creating different types of models. A \e view is a container
+    that displays the data in a list or a grid, or along a path. A \e delegate
+    dictates how the data should appear in the view. The delegate takes each
+    piece of data in the model and encapsulates it. The data is then accessible
+    through the delegate.
+
+    To visualize data, the view's model property is bound to a model and the
+    delegate property to a component.
+
+    For more information, see \l{Models and Views in Qt Quick}.
+
+    \section1 List and Grid Views
+
+    A list view organizes items as a list, whereas a grid view organizes them as
+    a grid. By default, items in list and grid views flow vertically from left
+    to right. They are laid out from left to right horizontally, and from top to
+    bottom vertically.
+
+    You can change the list view orientation in the \uicontrol Orientation
+    field and the grid view flow in the \uicontrol Flow field. You can change
+    the layout direction in the \uicontrol {Layout direction} field. These
+    properties can be combined to produce a variety of layouts.
+
+    \image qtquick-designer-listview-properties.png "List View properties"
+
+    For a list view, you can specify space between list items in the
+    \uicontrol Spacing field. For a grid view, you can specify the width
+    and height of each cell in the \uicontrol W and \uicontrol H fields.
+
+    \image qtquick-designer-gridview-properties.png "Grid View properties"
+
+    Select the \uicontrol {Navigation wraps} check box to specify that key
+    navigation wraps around and moves the selection to the next line or cell
+    in the other end of the view when it reaches the end of the view.
+
+    Both list and grid views are inherently \l {Flickable}{flickable}.
+
+    The value of the \uicontrol {Snap mode} field determines how the view
+    scrolling will settle following a drag or flick. By default, the view
+    stops anywhere within the visible area. If you select \uicontrol SnapToRow,
+    the view settles with a row (or column for a grid view top-to-bottom flow)
+    aligned with the start of the view. If you select \uicontrol SnapOneRow,
+    the view will settle no more than one row or column away from the first
+    visible row at the time the mouse button is released. This option is
+    particularly useful for moving one page at a time.
+
+    \section1 Delegate Cache
+
+    The value of the \uicontrol Cache field determines whether delegates are
+    retained outside the visible area of the view.
+
+    If this value is greater than zero, the view may keep as many delegates
+    instantiated as will fit within the cache specified. For example, if in
+    a vertical view the delegate is 20 pixels high, there are three columns
+    and the cache is set to 40, then up to six delegates above and below the
+    visible area may be created or retained. The cached delegates are created
+    asynchronously, allowing creation to occur across multiple frames and
+    reducing the likelihood of skipping frames. In order to improve painting
+    performance delegates outside the visible area are not painted.
+
+    The default value of this property is platform dependent, but will usually
+    be a value greater than zero. Negative values are ignored.
+
+    The cache is not a pixel buffer. It only maintains additional instantiated
+    delegates.
+
+    \note Setting the \uicontrol Cache property is not a replacement for
+    creating efficient delegates. It can improve the smoothness of scrolling
+    behavior at the expense of additional memory usage. The fewer objects and
+    bindings in a delegate, the faster a view can be scrolled. It is important
+    to realize that setting a cache will only postpone issues caused by
+    slow-loading delegates, it is not a solution to this problem.
+
+    \section1 View Highlight
+
+    The current item in a list or grid view is higlighted if you set
+    the value of the \uicontrol Range field to \uicontrol ApplyRange
+    or \uicontrol StrictlyEnforceRange. When you select to apply the
+    range, the view attempts to maintain the highlight within the range.
+    However, the highlight can move outside of the range at the ends of
+    the view or due to mouse interaction. When you select to enforce the
+    range, the highlight never moves outside of the range. The current
+    item changes if a keyboard or mouse action would cause the highlight
+    to move outside of the range.
+
+    The values of the \uicontrol {Preferred begin} and \uicontrol {Preferred end}
+    fields affect the position of the current item when the view is scrolled.
+    For example, if the currently selected item should stay in the middle of the
+    view when it is scrolled, set the begin and end values to the top and bottom
+    coordinates of where the middle item would be. If the current item is
+    changed programmatically, the view will automatically scroll so that the
+    current item is in the middle of the view. The begin value must be less than
+    the end value.
+
+    Select the \uicontrol {Follows current item} check box to enable the view to
+    manage the highlight. The highlight is moved smoothly to follow the current
+    item. Otherwise, the highlight is not moved by the view, and any movement
+    must be implemented by the highlight.
+
+    The values of the \uicontrol {Move duration}, \uicontrol {Move velocity}
+    \uicontrol {Resize duration}, and \uicontrol {Resize velocity} fields
+    control the speed of the move and resize animations for the highlight.
+
+    \section1 Editing List Models
+
+    When you add a \l{GridView}{Grid View}, \l{ListView}{List View}, or
+    \l{PathView}{Path View}, the ListModel and the delegate component that
+    creates an instance for each item in the model are added automatically.
+    For grid and list views, you can edit the list model in \QC.
+
+    \image qtquick-designer-listview-preview.png "Preview of a list view"
+
+    To edit list models:
+
+    \list 1
+        \li Drag and drop a \uicontrol {Grid View} or \uicontrol {List View}
+            from \uicontrol Library to \uicontrol Navigator or
+            \uicontrol {Form Editor}.
+        \li Right-click the view in \uicontrol Navigator, and select
+            \uicontrol {Edit List Model} in the context-menu to open
+            the list model editor:
+            \image qtquick-designer-edit-list-model.png "List view in model editor"
+        \li Double-click the column headings and cells to change their values.
+        \li Use the toolbar buttons to add, remove, or move rows and columns.
+            In a list, each column represents a property and each row adds a
+            list item.
+    \endlist
+
+    You can replace the default model and delegate with other,
+    more complex models and delegates in \uicontrol {Text Editor}.
+    \l{ItemDelegate}{Item Delegate} and \l{SwipeDelegate}{Swipe Delegate}
+    types are also available in \uicontrol Library.
+
+    \include qtquick-pathview-editor.qdocinc pathview
+    \if defined(qtdesignstudio)
+    \include qtquick-pathview-editor.qdocinc svgpath
+    \endif
+
+    \section1 Summary of Model Components
+
+    The following table lists the QML types that you can use to add data models
+    to UIs. The \e Location column contains the tab name where you can find the
+    type in \uicontrol Library. The \e MCU column indicates which types are
+    supported on MCUs.
+
+    \table
+    \header
+        \li Icon
+        \li Name
+        \li Location
+        \li MCU
+        \li Purpose
+    \row
+        \li \inlineimage gridview-icon16.png
+        \li \l{GridView}{Grid View}
+        \li Qt Quick - Views
+        \li
+        \li A grid vizualization of a model.
+    \row
+        \li \inlineimage icons/itemdelegate-icon16.png
+        \li \l{ItemDelegate}{Item Delegate}
+        \li Qt Quick - Controls 2
+        \li
+        \li A standard view item that can be used as a delegate in various
+            views and controls, such as \l ListView and \l ComboBox.
+    \row
+        \li \inlineimage listview-icon16.png
+        \li \l{ListView}{List View}
+        \li Qt Quick - Views
+        \li \inlineimage ok
+        \li A list vizualization of a model.
+    \row
+        \li \inlineimage pathview-icon16.png
+        \li \l{Path View}
+        \li Qt Quick - Views
+        \li
+        \li Vizualizes the contents of a model along a path.
+    \row
+        \li \inlineimage icons/scrollview-icon16.png
+        \li \l [QtQuickControls] {ScrollView}{Scroll View}
+        \li Qt Quick - Controls 2
+        \li
+        \li Provides scrolling for user-defined content. It can be used instead
+            of a \l Flickable item.
+    \row
+        \li \inlineimage icons/stackview-icon16.png
+        \li \l [QtQuickControls] {StackView}{Stack View}
+        \li Qt Quick - Controls 2
+        \li
+        \li A stack-based navigation model.
+    \if defined(qtdesignstudio)
+    \row
+        \li \inlineimage icons/item-svg-16px.png
+        \li SvgPath
+        \li Studio Components
+        \li
+        \li An SVG path data string that is used to draw a path as a line.
+    \endif
+    \row
+        \li \inlineimage icons/itemdelegate-icon16.png
+        \li \l{SwipeDelegate}{Swipe Delegate}
+        \li Qt Quick - Controls 2
+        \li
+        \li A view item that can be swiped left or right to expose more
+            options or information. It is used as a delegate in views such
+            as \l ListView.
+    \row
+        \li \inlineimage icons/swipeview-icon16.png
+        \li \l[QtQuickControls] {SwipeView}{Swipe View}
+        \li Qt Quick - Controls 2
+        \li \inlineimage ok
+        \li Enables users to navigate pages by swiping sideways.
+    \endtable
+*/

doc/qtcreator/src/qtquick/library/qtquick-pathview-editor.qdocinc

@@ -0,0 +1,98 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Creator documentation.
+**
+** 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 The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html.
+**
+****************************************************************************/
+
+/*!
+//! [pathview]
+
+    \section1 Path View
+
+    The Path View type lays out data provided by data models on a \l{Path}.
+
+    A graphical spline editor enables you to specify path view paths, which
+    is a non-trivial task to do in the code editor.
+
+    \image qmldesigner-pathview-editor.png "Path View editor"
+
+    To start editing the path, double-click the path view in
+    \uicontrol {Form Editor}. The editor composes the path of PathCubic path
+    objects. They are cubic Bezier curves to a given position with two control
+    points. Drag and drop the control points in \uicontrol {Form Editor} to
+    construct the curve.
+
+    In addition, PathLine and PathQuad path objects are supported indirectly.
+    To make a curve segment linear, select \uicontrol {Make Curve Segment Straight} in
+    the context menu.
+
+    By default, the path is closed, which means that its start and end points
+    are identical. To create separate start and end points for it, right-click
+    an edit point to open a context menu, and deselect \uicontrol {Closed Path}.
+
+    To add intermediary points to a curve segment, select \uicontrol {Split Segment}
+    in the context menu.
+
+    In the \uicontrol Properties view, you can specify other properties for
+    the path view. The value of the \uicontrol {Drag margin} field specifies
+    the maximum distance from the path that initiates mouse dragging.
+
+    \image qtquick-designer-pathview-properties.png "Path View properties"
+
+    Select the \uicontrol Interactive check box to make an item flickable.
+    The value of the \uicontrol {Flick deceleration} field specifies the
+    rate at which a flick will decelerate.
+
+    In the \uicontrol Offset field, specify how far along the path the items
+    are from their initial positions. This is a real number that ranges from
+    0 to the value of the \uicontrol {Item count} field, which displays the
+    number of items in the model.
+
+    \if defined(qtdesignstudio)
+    \note You can also use the \l SvgPath Studio Component to specify an SVG
+    path data string that draws a path.
+    \endif
+
+//! [pathview]
+
+//! [svgpath]
+
+    \section1 SvgPath
+
+    The Svg Path type uses an SVG path data string to draw a path as a line.
+
+    The stroke property values that specify the appearance of the path are
+    described in \l{Strokes}.
+
+    \image studio-svgpath-properties.png "Svg Path properties"
+
+    The \uicontrol {Path data} field contains the SVG path data
+    string that  specifies the path. For more information, see
+    \l{https://www.w3.org/TR/SVG/paths.html#PathData}{W3C SVG Path Data}.
+
+    \note Mixing SvgPath with other types of elements is not always supported.
+    For example, when \l Shape is backed by \c GL_NV_path_rendering, a
+    \l ShapePath can contain one or more SvgPath elements, or one or more
+    elements of other types, but not both.
+
+//! [svgpath]
+*/

doc/qtcreator/src/qtquick/qtquick-adding-dynamics.qdoc

@@ -61,9 +61,5 @@
             logic. You can associate transitions with items to define
             how their properties will animate when they change due to a state
             change.
-        \li \l {Editing PathView Properties}
-
-            You can use a graphical spline editor to specify \l{PathView} paths.
-            A path view lays out data provided by data models on a \l{Path}.
     \endlist
 */

doc/qtcreator/src/qtquick/qtquick-buttons.qdoc

@@ -30,7 +30,7 @@
 // **********************************************************************
 
 /*!
-    \previouspage qtquick-form-editor.html
+    \previouspage quick-data-models.html
     \page quick-buttons.html
     \nextpage quick-scalable-image.html
 

doc/qtcreator/src/qtquick/qtquick-components.qdoc

@@ -119,10 +119,9 @@
 
     \list
         \li \l Shapes
-        \li Text
-        \li Images
         \li UI controls
         \li Screens
+        \li \l {Lists and Other Data Models}
     \endlist
 
     \section2 Basic QML Types
@@ -150,36 +149,6 @@
         \li \l [QtQuick]{TextInput}{Text Input} adds a single line of editable
             plain text that can be validated.
     \endlist
-
-    \section2 Using Data Models
-
-    You can create the following types of views to organize items provided by
-    \l{Models and Views in Qt Quick}{data models}:
-
-    \list
-        \li \l{GridView}{Grid View} provides a grid vizualization of a model.
-        \li \l{ListView}{List View} provides a list vizualization of a model.
-        \li \l{PathView}{Path View} visualizes the contents of a model along a
-            path. For more information, see \l{Editing PathView Properties}.
-        \li \l [QtQuickControls] {ScrollView}{Scroll View} provides scrolling
-            for user-defined content. It can be used instead of a \l Flickable
-            item.
-        \li \l [QtQuickControls] {StackView}{Stack View} provides a stack-based
-            navigation model.
-        \li \l[QtQuickControls] {SwipeView}{Swipe View} enables users to
-            navigate pages by swiping sideways.
-    \endlist
-
-    When you add a \l{GridView}{Grid View}, \l{ListView}{List View}, or
-    \l{PathView}{Path View}, the ListModel and the delegate component that
-    creates an instance for each item in the model are added automatically.
-    You can edit item properties in \uicontrol Properties or in
-    \uicontrol {Text Editor}. You can also replace the default model and
-    delegate with other, more complex models and delegates in
-    \uicontrol {Text Editor}. \l{ItemDelegate}{Item Delegate} and
-    \l{SwipeDelegate}{Swipe Delegate} delegate components are also available
-    in \uicontrol Library.
-
     \section1 User Interaction Methods
 
     You can use the following QML types to add basic interaction methods to

doc/qtcreator/src/qtquick/qtquick-pathview-editor.qdoc

@@ -1,66 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2020 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the Qt Creator documentation.
-**
-** 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 The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html.
-**
-****************************************************************************/
-
-/*!
-    \page qmldesigner-pathview-editor.html
-    \previouspage quick-states.html
-    \nextpage studio-3d.html
-
-    \title Editing PathView Properties
-
-    A \l{PathView}{Path View} lays out data provided by data models on a
-    \l{Path}.
-
-    A graphical spline editor enables you to specify path view paths, which
-    is a non-trivial task to do in the code editor.
-
-    \image qmldesigner-pathview-editor.png "PathView editor"
-
-    To start editing the path, double-click the path view on the canvas. The
-    editor composes the path of PathCubic path objects. They are cubic Bezier
-    curves to a given position with two control points. Drag and drop the
-    control points to construct the curve.
-
-    In addition, PathLine and PathQuad path objects are supported indirectly.
-    To make a curve segment linear, select \uicontrol {Make Curve Segment Straight} in
-    the context menu.
-
-    By default, the path is closed, which means that its start and end points
-    are identical. To create separate start and end points for it, right-click
-    an edit point to open a context menu, and deselect \uicontrol {Closed Path}.
-
-    To add intermediary points to a curve segment, select \uicontrol {Split Segment}
-    in the context menu.
-
-    In the \uicontrol Properties view, you can specify other properties for
-    the path view. For example, what is the maximum distance from the path that
-    initiates mouse dragging and what is the rate at which a flick will
-    decelerate.
-
-    \if defined(qtdesignstudio)
-    \note You can also use the \l SvgPath Qt Quick Studio Component to
-    specify an SVG path data string that draws a path.
-    \endif
-*/

doc/qtcreator/src/qtquick/qtquick-states.qdoc

@@ -30,7 +30,7 @@
     \else
     \previouspage quick-connections-backend.html
     \endif
-    \nextpage qmldesigner-pathview-editor.html
+    \nextpage studio-3d.html
 
     \title Adding States
 

doc/qtdesignstudio/src/qtdesignstudio-components.qdocinc

@@ -33,15 +33,12 @@
     and back sides, like a card. The studio components are built on top of
     \l {Qt Quick Shapes QML Types}, with some additional properties.
 
-    You can drag-and-drop the following studio components from the
+    You can drag-and-drop the following studio components from
-    \uicontrol Library to the \uicontrol {Form Editor} or the
+    \uicontrol Library to \uicontrol {Form Editor} or \uicontrol Navigator:
-    \uicontrol Navigator:
 
     \list
         \li \l Flipable provides a surface that can be flipped.
         \li \l Group provides an item with the size property.
-        \li \l {Iso}{Iso Icon} adds a container for an ISO 7000 icon.
-        \li \l SvgPath adds an SVG path.
     \endlist
 
 //! [studio components]

doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc

@@ -82,6 +82,7 @@
                 \list
                     \li \l{Editing 2D Content}
                     \li \l{Shapes}
+                    \li \l{Lists and Other Data Models}
                     \li \l{Creating Buttons}
                     \li \l{Creating Scalable Buttons and Borders}
                 \endlist
@@ -102,7 +103,6 @@
                     \li\l{Adding Bindings Between Properties}
                 \endlist
                 \li \l{Adding States}
-                \li \l{Editing PathView Properties}
             \endlist
         \li \l{Editing 3D Scenes}
                 \list

doc/qtdesignstudio/src/qtdesignstudio.qdoc

@@ -73,7 +73,6 @@
                 \li \l{Creating Animations}
                 \li \l{Adding Connections}
                 \li \l{Adding States}
-                \li \l{Editing PathView Properties}
             \endlist
         \row
             \li \inlineimage studio-3d-scenes.png

doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d.qdoc

@@ -25,7 +25,7 @@
 
 /*!
     \page studio-3d.html
-    \previouspage qmldesigner-pathview-editor.html
+    \previouspage quick-states.html
     \if defined(qtdesignstudio)
     \nextpage studio-3d-design-mode.html
     \else