View: provide the transform between different coordinate spaces

There's currently no way for an application to convert between view and
drawing coordinates with a drawing states stack without keeping track of
all the transformations itself, which is not very convenient for helper
or library functions.

Handle other spaces too, for good measure.

Change-Id: Ic8404a1c111e273fff1eebf2f9f59f58246b796c
Reviewed-on: https://review.haiku-os.org/c/haiku/+/5775
Tested-by: Commit checker robot <[email protected]>
Reviewed-by: waddlesplash <[email protected]>

docs/user/interface/View.dox

@@ -272,6 +272,74 @@
 */
 
 
+// coordinate spaces
+
+
+/*!
+	\typedef coordinate_space
+	\brief A coordinate or drawing space.
+	\see \ref coordinatespaces
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var B_CURRENT_STATE_COORDINATES
+	\brief The current drawing space.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var B_PREVIOUS_STATE_COORDINATES
+	\brief The drawing space of the parent state in the stack.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var B_VIEW_COORDINATES
+	\brief The base coordinate space of the view.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var B_PARENT_VIEW_DRAW_COORDINATES
+	\brief The current drawing space of the parent view.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var B_PARENT_VIEW_COORDINATES
+	\brief The base coordinate space of the parent view.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var B_WINDOW_COORDINATES
+	\brief The coordinate space of the owning window.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var B_SCREEN_COORDINATES
+	\brief The coordinate space of the screen.
+
+	\since Haiku R1
+*/
+
+
 // view flags
 
 
@@ -1903,6 +1971,27 @@ SetViewColor(Parent()->ViewColor());
 */
 
 
+/*!
+	\fn BAffineTransform BView::TransformTo(coordinate_space basis) const
+	\brief Return the BAffineTransform to convert from the current drawing
+		space to \a basis.
+
+	\c B_PREVIOUS_STATE_COORDINATES is equivalent to
+		\c B_CURRENT_STATE_COORDINATES when there is no parent state.
+
+	\c B_PARENT_VIEW_DRAW_COORDINATES and \c B_PARENT_VIEW_COORDINATES are
+		equivalent to \c B_WINDOW_COORDINATES when used on a root view.
+
+	\c B_WINDOW_COORDINATES works as \c B_SCREEN_COORDINATES for unattached
+		views.
+
+	\sa Transform()
+	\sa \ref coordinatespaces
+
+	\since Haiku R1
+*/
+
+
 /*!
 	\fn void BView::TranslateBy(double x, double y)
 	\brief Translate the current view by coordinates.

docs/user/interface/_interface_intro.dox

@@ -66,7 +66,5 @@
 	All drawing operations in a BView use coordinates specified in the drawing space.
 	However, the update rect passed to the Draw method (or passed to the Invalidate
 	method) is in the BView base coordinate space. Conversion between the two can
-	be done using the affine transform returned by BView::Transform, or in case the
-	legacy transformation functions are used, by applying the scale and origin returned
-	by the Scale() and Origin() functions.
+	be done using the affine transform returned by BView::TransformTo.
 */