Visual coordinates documentation

Task-number: QTBUG-26367
Change-Id: I4a782118e96aecfaf7cfa6921afcb6dd1f86d665
Reviewed-by: Chris Adams <christopher.adams@nokia.com>

2 files changed, 52 insertions, 1 deletions

diff --git a/src/quick/doc/images/visual-coordinates-example.png b/src/quick/doc/images/visual-coordinates-example.png
new file mode 100644
index 0000000000..c5ccf5dbfc
--- /dev/null
+++ b/src/quick/doc/images/visual-coordinates-example.png
diff --git a/src/quick/doc/src/concepts/visualcanvas/coordinates.qdoc b/src/quick/doc/src/concepts/visualcanvas/coordinates.qdoc
index bcbf8ae54d..f323a9c9c6 100644
--- a/src/quick/doc/src/concepts/visualcanvas/coordinates.qdoc
+++ b/src/quick/doc/src/concepts/visualcanvas/coordinates.qdoc
@@ -30,6 +30,57 @@
 \title Concepts - Visual Coordinates in Qt Quick
 \brief Description of the concept of visual coordinates in Qt Quick
 
-XXX TODO - Fill with content.
+\section1 Item Coordinates
+The default system of visual coordinates used in Qt Quick is item coordinates. This is a cartesian coordinate system
+with (0,0) at the top left corner of the item. The x-axis grows to the right and the y-axis grows downwards, so that
+the bottom right corner of the item is at coordinates (width, height).
+
+An individual item's position is specified in terms of its parent's coordinate system. This means that reading x,y
+values from non-sibling items may require conversion to convert them into the same coordinate system. Scene
+coordinates are often used as the intermediate coordinate system when this occurs.
+
+\section1 Scene Coordinates
+Scene coordinates are the coordinates where (0,0) corresponds to the top left corner of the window the scene is
+currently being rendered. Scene coordinates are usually the same as the item coordinates of the root item in the
+window.
+
+You can convert from item to scene coordinates using the functions on the item whose coordinate system you are
+interested in. See \l Item::mapFromItem and \l Item::mapToItem for converting to scene coordinates, or another item's
+coordinates.
+
+\section1 Worked Example
+The below QML code creates an arrangment of squares, with dots added for identification of points:
+\code
+Rectangle {
+    width: 200
+    height: 200
+    color: "red"
+
+    Rectangle {
+        x: 100
+        y: 100
+        width: 100
+        height: 100
+        color: "blue"
+
+        Rectangle {
+            width: 50
+            height: 50
+            color: "green"
+        }
+    }
+}
+\endcode
+
+\image visual-coordinates-example.png
+
+In this image the black dot is positioned at (0,0) within the item coordinates of the red rectangle. If the red
+rectangle was the root item of the scene, then the black dot would also be positioned at (0,0) in scene coordinates.
+
+The blue rectangle is positioned at the white dot, (100,100), relative to the red rectangle's top left corner.
+
+The green rectangle has no x,y specified, so its position defaults to (0,0). Because it is at (0,0) in the coordinates of its parent,
+the blue rectangle, it is positioned at the top left corner of that rectangle. This is the same point as the white dot at
+(100,100) in the coordinates of the red rectangle.
 
 */