Doc: Explain how shape items are positioned


The graphics view shape items take a geometry argument such as a
rectangle, ellipse, polygon, line, or path. Developers often read
that geometry as the item's position in the scene. They pass scene
coordinates to it and expect the item to move there. The geometry is
in item coordinates, though. Changing it changes where the shape is
drawn relative to the item's origin, and the item itself stays put.
This mismatch leads to items with unexpected offsets, and to
confusion when hit testing, transformations, or rotations don't
behave as expected.

The documentation for the shape setters now states that the geometry
is in item coordinates and points readers to the function that
positions the item in the scene. The rectangle item overview also
shows the common pattern: anchor the shape at the origin and place
the item separately. This should help readers get positioning right
the first time.

Fixes: QTBUG-50448
Pick-to: 6.12
Change-Id: I6dcf3aaf07979534147d31d5637a895eab4c956a
Reviewed-by: Topi Reinio <topi.reinio@qt.io>
commitf8bd6d23f88f4a2485b043bc26d5b537193af4e4
parenta8bccfab066873320e0f763f72fe0de5713a9df2
authorPaul Wicking <paul.wicking@qt.io>
committerPaul Wicking <paul.wicking@qt.io>
commit timeWed, 21 Oct 2026 21:24:34 +0000