From 63ed2a13bfd9a531d93bad81ddcc28ad822263b3 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 25 Mar 2023 12:10:58 -0400 Subject: [PATCH] docs: Add a section about coordinate systems --- docs/reference/gtk/coordinates.md | 63 +++++++++++++++++++++++++++++++ docs/reference/gtk/gtk4.toml.in | 1 + docs/reference/gtk/meson.build | 1 + 3 files changed, 65 insertions(+) create mode 100644 docs/reference/gtk/coordinates.md diff --git a/docs/reference/gtk/coordinates.md b/docs/reference/gtk/coordinates.md new file mode 100644 index 0000000000..ac6f209f58 --- /dev/null +++ b/docs/reference/gtk/coordinates.md @@ -0,0 +1,63 @@ +Title: Coordinate systems +Slug: gtk-coordinates + +## Coordinate systems in GTK + +Every widget in a window has its own coordinate system that it uses to place its +child widgets and to interpret events. Most of the time, this fact can be safely +ignored. The section will explain the details for the few cases when it is important. + +## The box model + +When it comes to rendering, GTK follows the CSS box model as far as practical. + +![](https://www.w3.org/TR/css-box-3/images/box.png) + +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. + +You can learn more about the CSS box model by reading the +[CSS specification](https://www.w3.org/TR/css-box-3/#box-model). + +## Widgets + +The content area in the CSS box model is the region that the widget considers its own. + +The origin of the widgets coordinate system is the top left corner of the content area, +and its size is the widgets size. The size can be queried with [method@Gtk.Widget.get_width] +and [method@Gtk.Widget.get_height]. GTK allows general transformations to position +widgets (although most of the time, the transformation will be a simple translation). +The transform to go from one widgets coordinate system to another one can be obtained +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 +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 +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. + +## 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. + +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. diff --git a/docs/reference/gtk/gtk4.toml.in b/docs/reference/gtk/gtk4.toml.in index edca1dfb64..477c618f76 100644 --- a/docs/reference/gtk/gtk4.toml.in +++ b/docs/reference/gtk/gtk4.toml.in @@ -68,6 +68,7 @@ content_files = [ "input-handling.md", "drag-and-drop.md", "drawing-model.md", + "coordinates.md", "css-overview.md", "css-properties.md", "section-accessibility.md", diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build index 15466ef924..0954a1b33f 100644 --- a/docs/reference/gtk/meson.build +++ b/docs/reference/gtk/meson.build @@ -17,6 +17,7 @@ expand_content_md_files = [ 'actions.md', 'input-handling.md', 'drawing-model.md', + 'coordinates.md', 'css-overview.md', 'css-properties.md', 'section-accessibility.md', -- 2.30.2