coordinates.qdoc

Go to the documentation of this file.

// Copyright (C) 2017 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\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.
 
*/