/****************************************************************************
**
** Copyright (C) 2013 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 qtquick-visualcanvas-coordinates.html
\title Concepts - Visual Coordinates in Qt Quick
\brief Description of the concept of visual coordinates in Qt Quick

\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.

*/
