From 6f96bf2d8d91cc03aa72fd90517f90ec5804d1ca Mon Sep 17 00:00:00 2001
From: Bea Lam <bea.lam@nokia.com>
Date: Tue, 21 Feb 2012 17:47:10 +1000
Subject: [PATCH] Doc improvements for positioners

- Fix docs that say opacity changes can trigger an add transition since
  this is no longer the case
- Be more clear about when the move transition is applied
- Be more clear about which anchors are allowed/disallowed in which positioners
- Add example to Positioner attached property

Change-Id: I78417ac5b8eba1af5587955121b7fd4e2ca21169
Reviewed-by: Alan Alpert <alan.alpert@nokia.com>
---
 doc/src/images/positioner-example.png              | Bin 0 -> 7020 bytes
 .../declarative/column/column-transitions.qml      |  58 ++++
 .../declarative/column/vertical-positioner.qml     |   1 +
 src/quick/items/qquickpositioners.cpp              | 381 +++++++++------------
 4 files changed, 220 insertions(+), 220 deletions(-)
 create mode 100644 doc/src/images/positioner-example.png
 create mode 100644 doc/src/snippets/declarative/column/column-transitions.qml

diff --git a/doc/src/images/positioner-example.png b/doc/src/images/positioner-example.png
new file mode 100644
index 0000000000000000000000000000000000000000..636eeb7a136c14b6f27579fd226de3bec83a9207
GIT binary patch
literal 7020
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

literal 0
HcmV?d00001

diff --git a/doc/src/snippets/declarative/column/column-transitions.qml b/doc/src/snippets/declarative/column/column-transitions.qml
new file mode 100644
index 0000000..8e291b1
--- /dev/null
+++ b/doc/src/snippets/declarative/column/column-transitions.qml
@@ -0,0 +1,58 @@
+/****************************************************************************
+**
+** 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:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.0
+
+//! [document]
+Column {
+    spacing: 2
+
+    Rectangle { color: "red"; width: 50; height: 50 }
+    Rectangle { id: greenRect; color: "green"; width: 20; height: 50 }
+    Rectangle { color: "blue"; width: 50; height: 20 }
+
+    move: Transition {
+        NumberAnimation { properties: "x,y"; duration: 1000 }
+    }
+
+    focus: true
+    Keys.onSpacePressed: greenRect.visible = !greenRect.visible
+}
+//! [document]
diff --git a/doc/src/snippets/declarative/column/vertical-positioner.qml b/doc/src/snippets/declarative/column/vertical-positioner.qml
index 84de7e7..1661c46 100644
--- a/doc/src/snippets/declarative/column/vertical-positioner.qml
+++ b/doc/src/snippets/declarative/column/vertical-positioner.qml
@@ -43,6 +43,7 @@ import QtQuick 2.0
 //! [document]
 Column {
     spacing: 2
+
     Rectangle { color: "red"; width: 50; height: 50 }
     Rectangle { color: "green"; width: 20; height: 50 }
     Rectangle { color: "blue"; width: 50; height: 20 }
diff --git a/src/quick/items/qquickpositioners.cpp b/src/quick/items/qquickpositioners.cpp
index ccd98f7..fc77cf7 100644
--- a/src/quick/items/qquickpositioners.cpp
+++ b/src/quick/items/qquickpositioners.cpp
@@ -94,8 +94,9 @@ QQuickBasePositioner::QQuickBasePositioner(PositionerType at, QQuickItem *parent
 
     Note that the subclass is responsible for adding the spacing in between items.
 
-    Positioning is usually delayed until before a frame is rendered, to batch multiple repositioning
-    changes into one calculation.
+    Positioning is batched and synchronized with painting to reduce the number of
+    calculations needed. This means that positioners may not reposition items immediately
+    when changes occur, but it will have moved by the next frame.
 */
 
 QQuickBasePositioner::QQuickBasePositioner(QQuickBasePositionerPrivate &dd, PositionerType at, QQuickItem *parent)
@@ -357,9 +358,32 @@ void QQuickBasePositioner::updateAttachedProperties(QQuickPositionerAttached *sp
     \ingroup qml-positioning-elements
     \brief The Positioner type provides attached properties that contain details on where an item exists in a positioner.
 
-    Positioner items (such as Column, Row, Flow and Grid) provide automatic layout
-    for child items. Attaching this property allows a child item to determine
-    where it exists within the positioner.
+    Positioner is an attached property that is attached to the top-level child item within a
+    Column, Row, Flow or Grid. It provides properties that allow a child item to determine
+    where it exists within the layout of its parent Column, Row, Flow or Grid.
+
+    For example, below is a \l Grid with 16 child rectangles, as created through a \l Repeater.
+    Each \l Rectangle displays its index in the Grid using \l Positioner.index, and the first
+    item is colored differently by taking \l Positioner.isFirstItem into account:
+
+    \code
+    Grid {
+        Repeater {
+            model: 16
+
+            Rectangle {
+                id: rect
+                width: 30; height: 30
+                border.width: 1
+                color: Positioner.isFirstItem ? "yellow" : "lightsteelblue"
+
+                Text { text: rect.Positioner.index }
+            }
+        }
+    }
+    \endcode
+
+    \image positioner-example.png
 */
 
 QQuickPositionerAttached::QQuickPositionerAttached(QObject *parent) : QObject(parent), m_index(-1), m_isFirstItem(false), m_isLastItem(false)
@@ -411,74 +435,56 @@ void QQuickPositionerAttached::setIsLastItem(bool isLastItem)
 }
 
 /*!
-  \qmlclass Column QQuickColumn
+    \qmlclass Column QQuickColumn
     \inqmlmodule QtQuick 2
-  \ingroup qml-positioning-elements
-  \brief The Column item arranges its children vertically.
-  \inherits Item
-
-  The Column item positions its child items so that they are vertically
-  aligned and not overlapping.
+    \ingroup qml-positioning-elements
+    \brief The Column element positions its children in a column.
+    \inherits Item
 
-  Spacing between items can be added using the \l spacing property.
-  Transitions can be used for cases where items managed by a Column are
-  added or moved. These are stored in the \l add and \l move properties
-  respectively.
+    Column is an element that positions its child items along a single column.
+    It can be used as a convenient way to vertically position a series of items without
+    using \l {Anchor-based Layout in QML}{anchors}.
 
-  See \l{Using QML Positioner and Repeater Items} for more details about this item and other
-  related items.
+    Below is a Column that contains three rectangles of various sizes:
 
-  \section1 Example Usage
+    \snippet doc/src/snippets/declarative/column/vertical-positioner.qml document
 
-  The following example positions differently shaped rectangles using a Column
-  item.
+    The Column automatically positions these items in a vertical formation, like this:
 
-  \image verticalpositioner_example.png
+    \image verticalpositioner_example.png
 
-  \snippet doc/src/snippets/declarative/column/vertical-positioner.qml document
+    If an item within a Column is not \l {Item::}{visible}, or if it has a width or
+    height of 0, the item will not be laid out and it will not be visible within the
+    column. Also, since a Column automatically positions its children vertically, a child
+    item within a Column should not set its \l {Item::y}{y} position or vertically
+    anchor itself using the \l {Item::anchors.top}{top}, \l {Item::anchors.bottom}{bottom},
+    \l {Item::anchors.verticalCenter}{anchors.verticalCenter}, \l {Item::anchors.fill}{fill}
+    or \l {Item::anchors.centerIn}{centerIn} anchors. If you need to perform these actions,
+    consider positioning the items without the use of a Column.
 
-  \section1 Using Transitions
+    Note that items in a Column can use the \l Positioner attached property to access
+    more information about its position within the Column.
 
-  Transitions can be used to animate items that are added to, moved within,
-  or removed from a Column item. The \l add and \l move properties can be set to
-  the transitions that will be applied when items are added to, removed from,
-  or re-positioned within a Column item.
+    For more information on using Column and other related positioner-type elements, see
+    \l{Item Layouts}.
 
-  The use of transitions with positioners is described in more detail in the
-  \l{Using QML Positioner and Repeater Items#Using Transitions}{Using QML
-  Positioner and Repeater Items} document.
 
-  \image verticalpositioner_transition.gif
+    \section1 Using Transitions
 
-  \qml
-  Column {
-      spacing: 2
-      add: Transition {
-          // Define an animation for adding a new item...
-      }
-      move: Transition {
-          // Define an animation for moving items within the column...
-      }
-      // ...
-  }
-  \endqml
+    A Column animate items using specific transitions when items are added to or moved
+    within a Column.
 
-  \section1 Limitations
+    For example, the Column below sets the \l move property to a specific \l Transition:
 
-  Note that the positioner assumes that the x and y positions of its children
-  will not change. If you manually change the x or y properties in script, bind
-  the x or y properties, use anchors on a child of a positioner, or have the
-  height of a child depend on the position of a child, then the
-  positioner may exhibit strange behavior. If you need to perform any of these
-  actions, consider positioning the items without the use of a Column.
+    \snippet doc/src/snippets/declarative/column/column-transitions.qml document
 
-  Items with a width or height of 0 will not be positioned.
+    When the Space key is pressed, the \l {Item::visible}{visible} value of the green
+    \l Rectangle is toggled. As it appears and disappears, the blue \l Rectangle moves within
+    the Column, and the \l move transition is automatically applied to the blue \l Rectangle:
 
-  Positioning is batched and syncronized with painting to reduce the number of
-  calculations needed. This means that positioners may not reposition items immediately
-  when changes occur, but it will have moved by the next frame.
+    \image verticalpositioner_transition.gif
 
-  \sa Row, Grid, Flow, Positioner, {declarative/positioners}{Positioners example}
+    \sa Row, Grid, Flow, Positioner, {declarative/positioners}{Positioners example}
 */
 /*!
     \qmlproperty Transition QtQuick2::Column::add
@@ -490,33 +496,21 @@ void QQuickPositionerAttached::setIsLastItem(bool isLastItem)
 
     For a positioner, adding an item can mean that either the object
     has been created or reparented, and thus is now a child or the
-    positioner, or that the object has had its opacity increased from
-    zero, and thus is now visible.
+    positioner, or that the object has changed its \l visible property
+    from false to true, and thus is now visible.
 
     \sa move
 */
 /*!
     \qmlproperty Transition QtQuick2::Column::move
 
-    This property holds the transition to apply when moving an item
-    within the positioner.  Positioner transitions will only affect
+    This property holds the transition to apply to any item that has moved
+    within the positioner. Positioner transitions will only affect
     the position (x, y) of items.
 
-    This transition can be performed when other items are added or removed
-    from the positioner, or when items resize themselves.
-
-    \image positioner-move.gif
-
-    \qml
-    Column {
-        move: Transition {
-            NumberAnimation {
-                properties: "y"
-                duration: 1000
-            }
-        }
-    }
-    \endqml
+    This transition is applied to items that are displaced as a result of the
+    addition or removal of other items in the positioner, or when items move due to
+    a move operation in a related model, or when items resize themselves.
 
     \sa add, {declarative/positioners}{Positioners example}
 */
@@ -581,53 +575,41 @@ void QQuickColumn::reportConflictingAnchors()
     }
 }
 /*!
-  \qmlclass Row QQuickRow
+    \qmlclass Row QQuickRow
     \inqmlmodule QtQuick 2
-  \ingroup qml-positioning-elements
-  \brief The Row item arranges its children horizontally.
-  \inherits Item
-
-  The Row item positions its child items so that they are horizontally
-  aligned and not overlapping.
-
-  Use \l spacing to set the spacing between items in a Row, and use the
-  \l add and \l move properties to set the transitions that should be applied
-  when items are added to, removed from, or re-positioned within the Row.
-
-  See \l{Using QML Positioner and Repeater Items} for more details about this item and other
-  related items.
-
-  \section1 Example Usage
+    \ingroup qml-positioning-elements
+    \brief The Row element positions its children in a row.
+    \inherits Item
 
-  The following example lays out differently shaped rectangles using a Row.
+    Row is an element that positions its child items along a single row.
+    It can be used as a convenient way to horizontally position a series of items without
+    using \l {Anchor-based Layout in QML}{anchors}.
 
-  \image horizontalpositioner_example.png
+    Below is a Row that contains three rectangles of various sizes:
 
-  \snippet doc/src/snippets/declarative/row/row.qml document
+    \snippet doc/src/snippets/declarative/row/row.qml document
 
-  \section1 Using Transitions
+    The Row automatically positions these items in a horizontal formation, like this:
 
-  Transitions can be used to animate items that are added to, moved within,
-  or removed from a Grid item. The \l add and \l move properties can be set to
-  the transitions that will be applied when items are added to, removed from,
-  or re-positioned within a Row item.
+    \image horizontalpositioner_example.png
 
-  \section1 Limitations
+    If an item within a Row is not \l {Item::}{visible}, or if it has a width or
+    height of 0, the item will not be laid out and it will not be visible within the
+    row. Also, since a Row automatically positions its children horizontally, a child
+    item within a Row should not set its \l {Item::x}{x} position or horizontally
+    anchor itself using the \l {Item::anchors.left}{left}, \l {Item::anchors.right}{right},
+    \l {Item::anchors.horizontalCenter}{anchors.horizontalCenter}, \l {Item::anchors.fill}{fill}
+    or \l {Item::anchors.centerIn}{centerIn} anchors. If you need to perform these actions,
+    consider positioning the items without the use of a Row.
 
-  Note that the positioner assumes that the x and y positions of its children
-  will not change. If you manually change the x or y properties in script, bind
-  the x or y properties, use anchors on a child of a positioner, or have the
-  width of a child depend on the position of a child, then the
-  positioner may exhibit strange behavior. If you need to perform any of these
-  actions, consider positioning the items without the use of a Row.
+    Note that items in a Row can use the \l Positioner attached property to access
+    more information about its position within the Row.
 
-  Items with a width or height of 0 will not be positioned.
+    For more information on using Row and other related positioner-type elements, see
+    \l{Item Layouts}.
 
-  Positioning is batched and syncronized with painting to reduce the number of
-  calculations needed. This means that positioners may not reposition items immediately
-  when changes occur, but it will have moved by the next frame.
 
-  \sa Column, Grid, Flow, Positioner, {declarative/positioners}{Positioners example}
+    \sa Column, Grid, Flow, Positioner, {declarative/positioners}{Positioners example}
 */
 /*!
     \qmlproperty Transition QtQuick2::Row::add
@@ -639,20 +621,21 @@ void QQuickColumn::reportConflictingAnchors()
 
     For a positioner, adding an item can mean that either the object
     has been created or reparented, and thus is now a child or the
-    positioner, or that the object has had its opacity increased from
-    zero, and thus is now visible.
+    positioner, or that the object has changed its \l visible property
+    from false to true, and thus is now visible.
 
     \sa move
 */
 /*!
     \qmlproperty Transition QtQuick2::Row::move
 
-    This property holds the transition to be applied when moving an
-    item within the positioner. Positioner transitions will only affect
+    This property holds the transition to apply to any item that has moved
+    within the positioner. Positioner transitions will only affect
     the position (x, y) of items.
 
-    This transition can be performed when other items are added or removed
-    from the positioner, or when items resize themselves.
+    This transition is applied to items that are displaced as a result of the
+    addition or removal of other items in the positioner, or when items move due to
+    a move operation in a related model, or when items resize themselves.
 
     \qml
     Row {
@@ -720,7 +703,7 @@ void QQuickRow::setLayoutDirection(Qt::LayoutDirection layoutDirection)
 }
 /*!
     \qmlproperty enumeration QtQuick2::Row::effectiveLayoutDirection
-    This property holds the effective layout direction of the row positioner.
+    This property holds the effective layout direction of the row.
 
     When using the attached property \l {LayoutMirroring::enabled}{LayoutMirroring::enabled} for locale layouts,
     the visual layout direction of the row positioner will be mirrored. However, the
@@ -808,62 +791,42 @@ void QQuickRow::reportConflictingAnchors()
 }
 
 /*!
-  \qmlclass Grid QQuickGrid
+    \qmlclass Grid QQuickGrid
     \inqmlmodule QtQuick 2
-  \ingroup qml-positioning-elements
-  \brief The Grid item positions its children in a grid.
-  \inherits Item
-
-  The Grid item positions its child items so that they are
-  aligned in a grid and are not overlapping.
-
-  The grid positioner calculates a grid of rectangular cells of sufficient
-  size to hold all items, placing the items in the cells, from left to right
-  and top to bottom. Each item is positioned in the top-left corner of its
-  cell with position (0, 0).
-
-  A Grid defaults to four columns, and as many rows as are necessary to
-  fit all child items. The number of rows and columns can be constrained
-  by setting the \l rows and \l columns properties.
-
-  Spacing can be added between child items by setting the \l spacing
-  property. The amount of spacing applied will be the same in the
-  horizontal and vertical directions.
-
-  See \l{Using QML Positioner and Repeater Items} for more details about this item and other
-  related items.
+    \ingroup qml-positioning-elements
+    \brief The Grid element positions its children in grid formation.
+    \inherits Item
 
-  \section1 Example Usage
+    Grid is an element that positions its child items in grid formation.
 
-  The following example demonstrates this.
+    A Grid creates a grid of cells that is large enough to hold all of its
+    child items, and places these items in the cells from left to right
+    and top to bottom. Each item is positioned at the top-left corner of its
+    cell with position (0, 0).
 
-  \image gridLayout_example.png
+    A Grid defaults to four columns, and creates as many rows as are necessary to
+    fit all of its child items. The number of rows and columns can be constrained
+    by setting the \l rows and \l columns properties.
 
-  \snippet doc/src/snippets/declarative/grid/grid.qml document
+    For example, below is a Grid that contains five rectangles of various sizes:
 
-  \section1 Using Transitions
+    \snippet doc/src/snippets/declarative/grid/grid.qml document
 
-  Transitions can be used to animate items that are added to, moved within,
-  or removed from a Grid item. The \l add and \l move properties can be set to
-  the transitions that will be applied when items are added to, removed from,
-  or re-positioned within a Grid item.
+    The Grid automatically positions the child items in a grid formation:
 
-  \section1 Limitations
+    \image gridLayout_example.png
 
-  Note that the positioner assumes that the x and y positions of its children
-  will not change. If you manually change the x or y properties in script, bind
-  the x or y properties, use anchors on a child of a positioner, or have the
-  width or height of a child depend on the position of a child, then the
-  positioner may exhibit strange behavior. If you need to perform any of these
-  actions, consider positioning the items without the use of a Grid.
+    If an item within a Column is not \l {Item::}{visible}, or if it has a width or
+    height of 0, the item will not be laid out and it will not be visible within the
+    column. Also, since a Grid automatically positions its children, a child
+    item within a Grid should not set its \l {Item::x}{x} or \l {Item::y}{y} positions
+    or anchor itself with any of the \l {Item::anchors}{anchor} properties.
 
-  Items with a width or height of 0 will not be positioned.
+    For more information on using Grid and other related positioner-type elements, see
+    \l{Item Layouts}.
 
-  Positioning is batched and syncronized with painting to reduce the number of
-  calculations needed. This means that positioners may not reposition items immediately
-  when changes occur, but it will have moved by the next frame.
 
-  \sa Flow, Row, Column, Positioner, {declarative/positioners}{Positioners example}
+    \sa Flow, Row, Column, Positioner, {declarative/positioners}{Positioners example}
 */
 /*!
     \qmlproperty Transition QtQuick2::Grid::add
@@ -875,20 +838,21 @@ void QQuickRow::reportConflictingAnchors()
 
     For a positioner, adding an item can mean that either the object
     has been created or reparented, and thus is now a child or the
-    positioner, or that the object has had its opacity increased from
-    zero, and thus is now visible.
+    positioner, or that the object has changed its \l visible property
+    from false to true, and thus is now visible.
 
     \sa move
 */
 /*!
     \qmlproperty Transition QtQuick2::Grid::move
 
-    This property holds the transition to be applied when moving an
-    item within the positioner. Positioner transitions will only affect
+    This property holds the transition to apply to any item that has moved
+    within the positioner. Positioner transitions will only affect
     the position (x, y) of items.
 
-    This transition can be performed when other items are added or removed
-    from the positioner, or when items resize themselves.
+    This transition is applied to items that are displaced as a result of the
+    addition or removal of other items in the positioner, or when items move due to
+    a move operation in a related model, or when items resize themselves.
 
     \qml
     Grid {
@@ -907,7 +871,8 @@ void QQuickRow::reportConflictingAnchors()
   \qmlproperty int QtQuick2::Grid::spacing
 
   The spacing is the amount in pixels left empty between adjacent
-  items. The default spacing is 0.
+  items. The amount of spacing applied will be the same in the
+  horizontal and vertical directions. The default spacing is 0.
 
   The below example places a Grid containing a red, a blue and a
   green rectangle on a gray background. The area the grid positioner
@@ -1063,7 +1028,7 @@ void QQuickGrid::setLayoutDirection(Qt::LayoutDirection layoutDirection)
 
 /*!
     \qmlproperty enumeration QtQuick2::Grid::effectiveLayoutDirection
-    This property holds the effective layout direction of the grid positioner.
+    This property holds the effective layout direction of the grid.
 
     When using the attached property \l {LayoutMirroring::enabled}{LayoutMirroring::enabled} for locale layouts,
     the visual layout direction of the grid positioner will be mirrored. However, the
@@ -1242,57 +1207,32 @@ void QQuickGrid::reportConflictingAnchors()
 }
 
 /*!
-  \qmlclass Flow QQuickFlow
+    \qmlclass Flow QQuickFlow
     \inqmlmodule QtQuick 2
-  \ingroup qml-positioning-elements
-  \brief The Flow item arranges its children side by side, wrapping as necessary.
-  \inherits Item
-
-  The Flow item positions its child items like words on a page, wrapping them
-  to create rows or columns of items that do not overlap.
-
-  Spacing between items can be added using the \l spacing property.
-  Transitions can be used for cases where items managed by a Column are
-  added or moved. These are stored in the \l add and \l move properties
-  respectively.
-
-  See \l{Using QML Positioner and Repeater Items} for more details about this item and other
-  related items.
-
-  \section1 Example Usage
-
-  The following example positions \l Text items within a parent item using
-  a Flow item.
-
-  \image qml-flow-snippet.png
-
-  \snippet doc/src/snippets/declarative/flow.qml flow item
+    \ingroup qml-positioning-elements
+    \brief The Flow element positions its children side by side, wrapping as necessary.
+    \inherits Item
 
-  \section1 Using Transitions
+    The Flow item positions its child items like words on a page, wrapping them
+    to create rows or columns of items.
 
-  Transitions can be used to animate items that are added to, moved within,
-  or removed from a Flow item. The \l add and \l move properties can be set to
-  the transitions that will be applied when items are added to, removed from,
-  or re-positioned within a Flow item.
+    Below is a Flow that contains various \l Text items:
 
-  The use of transitions with positioners is described in more detail in the
-  \l{Using QML Positioner and Repeater Items#Using Transitions}{Using QML
-  Positioner and Repeater Items} document.
+    \snippet doc/src/snippets/declarative/flow.qml flow item
 
-  \section1 Limitations
+    The Flow item automatically positions the child \l Text items side by
+    side, wrapping as necessary:
 
-  Note that the positioner assumes that the x and y positions of its children
-  will not change. If you manually change the x or y properties in script, bind
-  the x or y properties, use anchors on a child of a positioner, or have the
-  width or height of a child depend on the position of a child, then the
-  positioner may exhibit strange behavior.  If you need to perform any of these
-  actions, consider positioning the items without the use of a Flow.
+    \image qml-flow-snippet.png
 
-  Items with a width or height of 0 will not be positioned.
+    If an item within a Flow is not \l {Item::}{visible}, or if it has a width or
+    height of 0, the item will not be laid out and it will not be visible within the
+    Flow. Also, since a Flow automatically positions its children, a child
+    item within a Flow should not set its \l {Item::x}{x} or \l {Item::y}{y} positions
+    or anchor itself with any of the \l {Item::anchors}{anchor} properties.
 
-  Positioning is batched and syncronized with painting to reduce the number of
-  calculations needed. This means that positioners may not reposition items immediately
-  when changes occur, but it will have moved by the next frame.
+    For more information on using Flow and other related positioner-type elements, see
+    \l{Item Layouts}.
 
   \sa Column, Row, Grid, Positioner, {declarative/positioners}{Positioners example}
 */
@@ -1306,20 +1246,21 @@ void QQuickGrid::reportConflictingAnchors()
 
     For a positioner, adding an item can mean that either the object
     has been created or reparented, and thus is now a child or the
-    positioner, or that the object has had its opacity increased from
-    zero, and thus is now visible.
+    positioner, or that the object has changed its \l visible property
+    from false to true, and thus is now visible.
 
     \sa move
 */
 /*!
     \qmlproperty Transition QtQuick2::Flow::move
 
-    This property holds the transition to be applied when moving an
-    item within the positioner. Positioner transitions will only affect
+    This property holds the transition to apply to any item that has moved
+    within the positioner. Positioner transitions will only affect
     the position (x, y) of items.
 
-    This transition can be performed when other items are added or removed
-    from the positioner, or when items resize themselves.
+    This transition is applied to items that are displaced as a result of the
+    addition or removal of other items in the positioner, or when items move due to
+    a move operation in a related model, or when items resize themselves.
 
     \qml
     Flow {
@@ -1433,7 +1374,7 @@ void QQuickFlow::setLayoutDirection(Qt::LayoutDirection layoutDirection)
 
 /*!
     \qmlproperty enumeration QtQuick2::Flow::effectiveLayoutDirection
-    This property holds the effective layout direction of the flow positioner.
+    This property holds the effective layout direction of the flow.
 
     When using the attached property \l {LayoutMirroring::enabled}{LayoutMirroring::enabled} for locale layouts,
     the visual layout direction of the grid positioner will be mirrored. However, the
-- 
2.7.4