Lerking/gtk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Apply review feedback

Browse Source 
Clarify some points in the coordinate overview.
This commit is contained in:
Matthias Clasen
2023-03-25 15:05:28 -04:00
parent 0b3c979719
commit 2e26932925
1 changed files with 21 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
docs/reference/gtk/coordinates.md
View File

@@ -15,11 +15,15 @@ When it comes to rendering, GTK follows the CSS box model as far as practical.
The CSS stylesheet that is in use determines the sizes (and appearance) of the
margin, border and padding areas for each widget. The size of the content area
is determined by GTKs layout algorithm using each widgets measure() and
size_allocate() vfuncs.
is determined by GTKs layout algorithm using each widgets [vfunc@Gtk.Widget.measure]
and [vfunc@Gtk.Widget.size_allocate] vfuncs.
You can learn more about the CSS box model by reading the
[CSS specification](https://www.w3.org/TR/css-box-3/#box-model).
[CSS specification](https://www.w3.org/TR/css-box-3/#box-model) or the
Mozilla [docs](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/The_box_model).
To learn more about where GTK CSS differs from CSS on the web, see the
[CSS overview](css-overview.html).
## Widgets
@@ -33,31 +37,28 @@ The transform to go from one widgets coordinate system to another one can be obt
with [method@Gtk.Widget.compute_transform].
When widget APIs expect positions or areas, they need to be expressed in this coordinate
system, typically called *widget coordinates*. GTK provides a number of APIs to translate
system, typically called **_widget coordinates_**. GTK provides a number of APIs to translate
between different widgets' coordinate systems, such as [method@Gtk.Widget.compute_point]
or [method@Gtk.Widget.compute_bounds].
Another area that is occasionally relevant are the widgets *bounds*, which is the area
Another area that is occasionally relevant are the widgets **_bounds_**, which is the area
that a widgets rendering is typically confined to (technically, widgets can draw outside
of this area, unless clipping is enforced via the [property@Gtk.Widget:overflow] property).
In CSS terms, the bounds of a widget correspond to the border area.
During GTK's layout algorithm, a parent widget needs to assign size and position to its
child widgets, by calling [method@Gtk.Widget.allocate] or one of its variants. The size
that is passed to this function corresponds to the margin area of the child widget in
the CSS box model.
During GTK's layout algorithm, a parent widget needs to measure each visible child and
allocate them at least as much size as measured. These functions take care of respecting
the CSS box model and widget properties such as align and margin. This happens in the
parent's coordinate system.
## Events
Some types of events that are coming from the windowing system have positions associated
with them (e.g. the pointer position). Such positions are expressed in *surface coordinates*
which have their origin at the top left corner of the surface.
Some types of events have positions associated with them (e.g. the pointer position).
Such positions are expressed in **_surface coordinates_**, which have their origin at
the top left corner of the surface.
When interpreting such positions with respect to widgets, you need to keep in mind that
there is an offset between the top left corner of the surface and the top left corner of
the topmost widget (typically either a [class@Gtk.Window] or [class@Gtk.Popover]). This
offset can be obtained with [method@Gtk.Native.get_surface_transform].
This translation is only necessary when dealing with raw events in the form of
[class@Gdk.Event] structs. Event controllers such as [class@Gtk.GestureClick] report
positions in the coordinate system of the widget they are attached to.
Event controllers and gestures report positions in the coordinate system of the widget
they are attached to. But if you are dealing with raw events in the form of [class@Gdk.Event]
struts, you need to translate from surface to widget coordinates, by applying the offset
from the top left corner of the surface to the top left corner of the topmost
widget. This offset can be obtained with [method@Gtk.Native.get_surface_transform].