From 6f93e63d214e4a0d008a0d79c32101ae0da1f4e8 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Wed, 17 Feb 2021 17:41:56 +0000 Subject: [PATCH] docs: Move detached sections into their own content file --- docs/reference/gdk/events.md | 10 +++ docs/reference/gdk/gdk4.toml.in | 6 ++ docs/reference/gdk/general.md | 16 +++++ docs/reference/gdk/keys.md | 113 +++++++++++++++++++++++++++++++ docs/reference/gdk/macos.md | 58 ++++++++++++++++ docs/reference/gdk/pango.md | 93 +++++++++++++++++++++++++ docs/reference/gdk/wayland.md | 48 +++++++++++++ docs/reference/gdk/x11.md | 47 +++++++++++++ gdk/gdk.c | 21 ------ gdk/gdkcursor.c | 29 ++++---- gdk/gdkevents.c | 13 ---- gdk/gdkkeys.c | 111 ------------------------------ gdk/gdkpango.c | 95 -------------------------- gdk/gdkrectangle.c | 17 ++--- gdk/gdkrgba.c | 2 +- gdk/macos/gdkmacosdisplay.c | 34 ---------- gdk/wayland/gdkdisplay-wayland.c | 34 ---------- gdk/x11/gdkmain-x11.c | 33 --------- 18 files changed, 416 insertions(+), 364 deletions(-) create mode 100644 docs/reference/gdk/events.md create mode 100644 docs/reference/gdk/general.md create mode 100644 docs/reference/gdk/keys.md create mode 100644 docs/reference/gdk/macos.md create mode 100644 docs/reference/gdk/pango.md create mode 100644 docs/reference/gdk/wayland.md create mode 100644 docs/reference/gdk/x11.md diff --git a/docs/reference/gdk/events.md b/docs/reference/gdk/events.md new file mode 100644 index 0000000000..9925c1dec7 --- /dev/null +++ b/docs/reference/gdk/events.md @@ -0,0 +1,10 @@ +Title: Events + +## Handling events from the window system + +In GTK applications the events are handled automatically by toplevel +widgets and passed on to the event controllers of appropriate widgets, +so using [class@Gdk.Event] and its related API is rarely needed. + +[class@Gdk.Event] and its derived types are immutable data structures, +created by GTK itself to represent windowing system events. diff --git a/docs/reference/gdk/gdk4.toml.in b/docs/reference/gdk/gdk4.toml.in index aa343b0a22..81040722c9 100644 --- a/docs/reference/gdk/gdk4.toml.in +++ b/docs/reference/gdk/gdk4.toml.in @@ -32,7 +32,13 @@ base_url = "https://gitlab.gnome.org/GNOME/gtk/-/blob/master/" [extra] content_files = [ + "events.md", + "keys.md", "cairo.md", + "pango.md", + "wayland.md", + "x11.md", + "macos.md", ] content_images = [ "images/gtk-logo.svg", diff --git a/docs/reference/gdk/general.md b/docs/reference/gdk/general.md new file mode 100644 index 0000000000..6e8243b6cc --- /dev/null +++ b/docs/reference/gdk/general.md @@ -0,0 +1,16 @@ +Title: Library initialization and versioning + +The GDK and GTK headers annotate deprecated APIs in a way that produces +compiler warnings if these deprecated APIs are used. The warnings +can be turned off by defining the macro `GDK_DISABLE_DEPRECATION_WARNINGS` +before including the `gdk.h` header. + +GDK and GTK also provide support for building applications against defined +subsets of deprecated or new APIs. You can define the macro +`GDK_VERSION_MIN_REQUIRED` to specify up to what version you want to receive +warnings about deprecated APIs; and the macro `GDK_VERSION_MAX_ALLOWED` to +specify the newest version whose API you want to use. If you attempt to use +a function deprecated before the version of GTK specified in +`GDK_VERSION_MIN_REQUIRED`, or a function introduced after the version of +GTK specified in `GDK_VERSION_MAX_ALLOWED`, the compiler will warn you when +building your code. diff --git a/docs/reference/gdk/keys.md b/docs/reference/gdk/keys.md new file mode 100644 index 0000000000..e44d0e13ce --- /dev/null +++ b/docs/reference/gdk/keys.md @@ -0,0 +1,113 @@ +Title: Key Values + +## Functions for manipulating keyboard codes + +Key values are the codes which are sent whenever a key is pressed or released. +They are included in the data contained in a key press or release #GdkEvent. +The complete list of key values can be found in the `gdk/gdkkeysyms.h` header +file. + +Key values are regularly updated from the upstream X.org X11 implementation, +so new values are added regularly. They will be prefixed with GDK_KEY_ rather +than XF86XK_ or XK_ (for older symbols). + +Key values can be converted into a string representation using +gdk_keyval_name(). The reverse function, converting a string to a key value, +is provided by gdk_keyval_from_name(). + +The case of key values can be determined using gdk_keyval_is_upper() and +gdk_keyval_is_lower(). Key values can be converted to upper or lower case +using gdk_keyval_to_upper() and gdk_keyval_to_lower(). + +When it makes sense, key values can be converted to and from +Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval(). + +## Key groups + +At the lowest level, physical keys on the keyboard are represented by +numeric keycodes, and GDK knows how to translate these keycodes into +key values according to the configured keyboard layout and the current +state of the keyboard. In the GDK api, the mapping from keycodes to key +values is available via [`method@Gdk.Display.map_keycode`], and the reverse +mapping is available via [`method@Gdk.Display.map_keyval`]. The results of +these functions are returned in [struct@Gdk.KeymapKey] structures. + +You can think of a [struct@Gdk.KeymapKey] as a representation of a symbol +printed on a physical keyboard key. That is, it contains three pieces of +information: + + 1. first, it contains the hardware keycode; this is an identifying number + for a physical key + 1. second, it contains the “level” of the key. The level indicates which + symbol on the key will be used, in a vertical direction. So on a standard + US keyboard, the key with the number “1“ on it also has the exclamation + point (”!”) character on it. The level indicates whether to use the “1” + or the “!” symbol. The letter keys are considered to have a lowercase + letter at level 0, and an uppercase letter at level 1, though normally + only the uppercase letter is printed on the key + 1. third, the #GdkKeymapKey contains a group; groups are not used on + standard US keyboards, but are used in many other countries. On a + keyboard with groups, there can be 3 or 4 symbols printed on a single + key. The group indicates movement in a horizontal direction. Usually + groups are used for two different languages. In group 0, a key might + have two English characters, and in group 1 it might have two Hebrew + characters. The Hebrew characters will be printed on the key next to + the English characters. + +When GDK creates a key event in order to deliver a key press or release, +it first converts the current keyboard state into an effective group and +level. This is done via a set of rules that varies widely according to +type of keyboard and user configuration. The input to this translation +consists of the hardware keycode pressed, the active modifiers, and the +active group. It then applies the appropriate rules, and returns the +group/level to be used to index the keymap, along with the modifiers +which did not affect the group and level. i.e. it returns “unconsumed +modifiers.” The keyboard group may differ from the effective group used +for lookups because some keys don't have multiple groups - e.g. the +Enter key is always in group 0 regardless of keyboard state. + +The results of the translation, including the keyval, are all included +in the key event and can be obtained via [class@Gdk.KeyEvent] getters. + +### Consumed modifiers + +The `consumed_modifiers` in a key event are modifiers that should be masked +out from @state when comparing this key press to a hot key. For instance, +on a US keyboard, the `plus` symbol is shifted, so when comparing a key +press to a `plus` accelerator `` should be masked out. + +```c +// We want to ignore irrelevant modifiers like ScrollLock +#define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_ALT_MASK) +state = gdk_event_get_modifier_state (event); +gdk_keymap_translate_keyboard_state (keymap, + gdk_key_event_get_keycode (event), + state, + gdk_key_event_get_group (event), + &keyval, NULL, NULL, &consumed); +if (keyval == GDK_PLUS && + (state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK) + // Control was pressed +``` + +An older interpretation of `consumed_modifiers` was that it contained +all modifiers that might affect the translation of the key; +this allowed accelerators to be stored with irrelevant consumed +modifiers, by doing: + +```c +// XXX Don’t do this XXX +if (keyval == accel_keyval && + (state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed)) + // Accelerator was pressed +``` + +However, this did not work if multi-modifier combinations were +used in the keymap, since, for instance, `` would be +masked out even if only `` was used in +the keymap. To support this usage as well as well as possible, all single +modifier combinations that could affect the key for any combination +of modifiers will be returned in `consumed_modifiers`; multi-modifier +combinations are returned only when actually found in `state`. When +you store accelerators, you should always store them with consumed +modifiers removed. Store `plus`, not `plus`. diff --git a/docs/reference/gdk/macos.md b/docs/reference/gdk/macos.md new file mode 100644 index 0000000000..1a0429be9d --- /dev/null +++ b/docs/reference/gdk/macos.md @@ -0,0 +1,58 @@ +Title: macOS Interaction + +## macOS backend-specific functions + +The functions in this section are specific to the GDK macOS backend. +To use them, you need to include the `` header and +use the macOS-specific pkg-config `gtk4-macos` file to build your +application. + +## Checking for the macOS backend + +GDK can be built with support for multiple backends, which means you will +need to perform both compile time *and* run time checks if you wish to call +backend-specific API; for instance, the code sample below will guard the +calls to different backends, and error out on unsupported windowing systems: + +```c +#ifdef GDK_WINDOWING_MACOS +#include +#endif +#ifdef GDK_WINDOWING_WAYLAND +#include +#endif +#ifdef GDK_WINDOWING_X11 +#include +#endif + +#ifdef GDK_WINDOWING_MACOS + if (GDK_IS_MACOS_DISPLAY (display)) + { + // make macOS-specific calls here + } + else +#endif +#ifdef GDK_WINDOWING_WAYLAND + if (GTK_IS_WAYLAND_DISPLAY (display)) + { + // make Wayland-specific calls here + } + else +#endif +#ifdef GDK_WINDOWING_X11 + if (GDK_IS_X11_DISPLAY (display)) + { + // make X11-specific calls here + } + else +#endif + g_error ("Unsupported GDK backend"); +``` + +The compile time check is performed by using the `GDK_WINDOWING_*` +pre-processor symbols; there is one defined for each windowing system +backend built into GDK. For Wayland, the symbol is `GDK_WINDOWING_MACOS`. + +The run time check is performed by looking at the type of the +[class@Gdk.Display] object. For Wayland, the display objects will be of type +`GdkMacosDisplay`. diff --git a/docs/reference/gdk/pango.md b/docs/reference/gdk/pango.md new file mode 100644 index 0000000000..c439530156 --- /dev/null +++ b/docs/reference/gdk/pango.md @@ -0,0 +1,93 @@ + Title: Pango Interaction + +Pango is the text layout system used by GDK and GTK. The functions +and types in this section are used to obtain clip regions for +`PangoLayout`s, and to get `PangoContext`s that can be used with +GDK. + +## Using Pango in GDK + +Creating a `PangoLayout` object is the first step in rendering text, +and requires getting a handle to a `PangoContext`. For GTK programs, +you’ll usually want to use `gtk_widget_get_pango_context()`, or +`gtk_widget_create_pango_layout()`. Once you have a `PangoLayout`, +you can set the text and attributes of it with Pango functions like +`pango_layout_set_text()` and get its size with `pango_layout_get_size()`. + +*Note*: Pango uses a fixed point system internally, so converting +between Pango units and pixels using `PANGO_SCALE` or the `PANGO_PIXELS()` +macro. + +Rendering a Pango layout is done most simply with `pango_cairo_show_layout()`; +you can also draw pieces of the layout with `pango_cairo_show_layout_line()`. + +### Draw transformed text with Pango and cairo + +```c +#define RADIUS 100 +#define N_WORDS 10 +#define FONT "Sans Bold 18" + +PangoContext *context; +PangoLayout *layout; +PangoFontDescription *desc; + +double radius; +int width, height; +int i; + +// Set up a transformation matrix so that the user space coordinates for +// where we are drawing are [-RADIUS, RADIUS], [-RADIUS, RADIUS] +// We first center, then change the scale + +width = gdk_surface_get_width (surface); +height = gdk_surface_get_height (surface); +radius = MIN (width, height) / 2.; + +cairo_translate (cr, + radius + (width - 2 * radius) / 2, + radius + (height - 2 * radius) / 2); + cairo_scale (cr, radius / RADIUS, radius / RADIUS); + +// Create a PangoLayout, set the font and text +context = gdk_pango_context_get_for_display (display); +layout = pango_layout_new (context); +pango_layout_set_text (layout, "Text", -1); +desc = pango_font_description_from_string (FONT); +pango_layout_set_font_description (layout, desc); +pango_font_description_free (desc); + +// Draw the layout N_WORDS times in a circle +for (i = 0; i < N_WORDS; i++) + { + double red, green, blue; + double angle = 2 * G_PI * i / n_words; + + cairo_save (cr); + + // Gradient from red at angle == 60 to blue at angle == 300 + red = (1 + cos (angle - 60)) / 2; + green = 0; + blue = 1 - red; + + cairo_set_source_rgb (cr, red, green, blue); + cairo_rotate (cr, angle); + + // Inform Pango to re-layout the text with the new transformation matrix + pango_cairo_update_layout (cr, layout); + + pango_layout_get_size (layout, &width, &height); + + cairo_move_to (cr, - width / 2 / PANGO_SCALE, - DEFAULT_TEXT_RADIUS); + pango_cairo_show_layout (cr, layout); + + cairo_restore (cr); + } + +g_object_unref (layout); +g_object_unref (context); +``` + +The example code above will yield the following result: + +![](rotated-text.png) diff --git a/docs/reference/gdk/wayland.md b/docs/reference/gdk/wayland.md new file mode 100644 index 0000000000..040e96a4e9 --- /dev/null +++ b/docs/reference/gdk/wayland.md @@ -0,0 +1,48 @@ +Title: Wayland Interaction + +## Wayland backend-specific functions + +The functions in this section are specific to the GDK Wayland backend. +To use them, you need to include the `` header and +use the Wayland-specific pkg-config `gtk4-wayland` file to build your +application. + +## Checking for the Wayland backend + +GDK can be built with support for multiple backends, which means you will +need to perform both compile time *and* run time checks if you wish to call +backend-specific API; for instance, the code sample below will guard the +calls to different backends, and error out on unsupported windowing systems: + +```c +#ifdef GDK_WINDOWING_WAYLAND +#include +#endif +#ifdef GDK_WINDOWING_X11 +#include +#endif + +#ifdef GDK_WINDOWING_WAYLAND + if (GTK_IS_WAYLAND_DISPLAY (display)) + { + // make Wayland-specific calls here + } + else +#endif +#ifdef GDK_WINDOWING_X11 + if (GDK_IS_X11_DISPLAY (display)) + { + // make X11-specific calls here + } + else +#endif + g_error ("Unsupported GDK backend"); +``` + +The compile time check is performed by using the `GDK_WINDOWING_*` +pre-processor symbols; there is one defined for each windowing system +backend built into GDK. For Wayland, the symbol is `GDK_WINDOWING_WAYLAND`. + +The run time check is performed by looking at the type of the +[class@Gdk.Display] object. For Wayland, the display objects will be of type +`GdkWaylandDisplay`. diff --git a/docs/reference/gdk/x11.md b/docs/reference/gdk/x11.md new file mode 100644 index 0000000000..6602e24b82 --- /dev/null +++ b/docs/reference/gdk/x11.md @@ -0,0 +1,47 @@ +Title: X Window System Interaction + +## X backend-specific functions + +The functions in this section are specific to the GDK X11 backend. +To use them, you need to include the `` header and use +the X11-specific pkg-config file `gtk4-x11` to build your application. + +## Checking for the X11 backend + +GDK can be built with support for multiple backends, which means you will +need to perform both compile time *and* run time checks if you wish to call +backend-specific API; for instance, the code sample below will guard the +calls to different backends, and error out on unsupported windowing systems: + +```c +#ifdef GDK_WINDOWING_X11 +#include +#endif +#ifdef GDK_WINDOWING_WAYLAND +#include +#endif + +#ifdef GDK_WINDOWING_X11 + if (GDK_IS_X11_DISPLAY (display)) + { + // make X11-specific calls here + } + else +#endif +#ifdef GDK_WINDOWING_WAYLAND + if (GTK_IS_WAYLAND_DISPLAY (display)) + { + // make Wayland-specific calls here + } + else +#endif + g_error ("Unsupported GDK backend"); +``` + +The compile time check is performed by using the `GDK_WINDOWING_*` +pre-processor symbols; there is one defined for each windowing system +backend built into GDK. For X11, the symbol is `GDK_WINDOWING_X11`. + +The run time check is performed by looking at the type of the +[class@Gdk.Display] object. For X11, the display objects will be of type +`GdkX11Display`. diff --git a/gdk/gdk.c b/gdk/gdk.c index a0938af58a..5cd0e1922d 100644 --- a/gdk/gdk.c +++ b/gdk/gdk.c @@ -47,27 +47,6 @@ #include -/** - * SECTION:general - * @Short_description: Library initialization and versioning - * @Title: General - * - * This section describes miscellaneous macros and utility functions - * related to library versioning, as well as deprecation facilities. - * - * The GDK and GTK headers annotate deprecated APIs in a way that produces - * compiler warnings if these deprecated APIs are used. The warnings - * can be turned off by defining the macro %GDK_DISABLE_DEPRECATION_WARNINGS - * before including the glib.h header. - * - * GDK and GTK also provide support for building applications against - * defined subsets of deprecated or new APIs. Define the macro - * %GDK_VERSION_MIN_REQUIRED to specify up to what version - * you want to receive warnings about deprecated APIs. Define the - * macro %GDK_VERSION_MAX_ALLOWED to specify the newest version - * whose API you want to use. - */ - /** * GDK_WINDOWING_X11: * diff --git a/gdk/gdkcursor.c b/gdk/gdkcursor.c index a0d5bc276d..ebb87c5c7b 100644 --- a/gdk/gdkcursor.c +++ b/gdk/gdkcursor.c @@ -37,37 +37,38 @@ #include /** - * SECTION:cursors + * SECTION:gdkcursor * @Short_description: Named and texture cursors * @Title: Cursors * - * These functions are used to create and destroy cursors. Cursors - * are immutable objects, so once you created them, there is no way - * to modify them later. Create a new cursor when you want to change - * something about it. + * `GdkCursor` is used to create and destroy cursors. Cursors are immutable + * objects, so once you created them, there is no way to modify them later. + * You should create a new cursor when you want to change something about + * it. * - * Cursors by themselves are not very interesting, they must be - * bound to a window for users to see them. This is done with - * gdk_surface_set_cursor() or gdk_surface_set_device_cursor(). - * Applications will typically use higher-level GTK functions such - * as gtk_widget_set_cursor() instead. + * Cursors by themselves are not very interesting: they must be bound to a + * window for users to see them. This is done with [method@Gdk.Surface.set_cursor] + * or [method@Gdk.Surface.set_device_cursor]. Applications will typically + * use higher-level GTK functions such as `gtk_widget_set_cursor()` instead. * - * Cursors are not bound to a given #GdkDisplay, so they can be shared. + * Cursors are not bound to a given [class@Gdk.Display], so they can be shared. * However, the appearance of cursors may vary when used on different * platforms. * + * ## Named and texture cursors + * * There are multiple ways to create cursors. The platform's own cursors - * can be created with gdk_cursor_new_from_name(). That function lists + * can be created with [ctor@Gdk.Cursor.new_from_name]. That function lists * the commonly available names that are shared with the CSS specification. * Other names may be available, depending on the platform in use. On some * platforms, what images are used for named cursors may be influenced by * the cursor theme. * - * Another option to create a cursor is to use gdk_cursor_new_from_texture() + * Another option to create a cursor is to use [ctor@Gdk.Cursor.new_from_texture] * and provide an image to use for the cursor. * * To ease work with unsupported cursors, a fallback cursor can be provided. - * If a #GdkSurface cannot use a cursor because of the reasons mentioned above, + * If a [class@Gdk.Surface] cannot use a cursor because of the reasons mentioned above, * it will try the fallback cursor. Fallback cursors can themselves have fallback * cursors again, so it is possible to provide a chain of progressively easier * to support cursors. If none of the provided cursors can be supported, the diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c index 2ce34f80ec..43692c4f95 100644 --- a/gdk/gdkevents.c +++ b/gdk/gdkevents.c @@ -38,19 +38,6 @@ #include #include -/** - * SECTION:events - * @Short_description: Functions for handling events from the window system - * @Title: Events - * - * This section describes functions dealing with events from the window - * system. - * - * In GTK applications the events are handled automatically by toplevel - * widgets and passed on to the event controllers of appropriate widgets, - * so these functions are rarely needed. - */ - /** * GdkEvent: (ref-func gdk_event_ref) (unref-func gdk_event_unref) * diff --git a/gdk/gdkkeys.c b/gdk/gdkkeys.c index 0c74dd64f4..f25647f74f 100644 --- a/gdk/gdkkeys.c +++ b/gdk/gdkkeys.c @@ -29,117 +29,6 @@ #include "gdkdisplay.h" #include "gdkdisplaymanagerprivate.h" - -/** - * SECTION:keys - * @Short_description: Functions for manipulating keyboard codes - * @Title: Key Values - * - * Key values are the codes which are sent whenever a key is pressed or released. - * They are included in the data contained in a key press or release #GdkEvent. - * The complete list of key values can be found in the `gdk/gdkkeysyms.h` header - * file. - * - * Key values are regularly updated from the upstream X.org X11 implementation, - * so new values are added regularly. They will be prefixed with GDK_KEY_ rather - * than XF86XK_ or XK_ (for older symbols). - * - * Key values can be converted into a string representation using - * gdk_keyval_name(). The reverse function, converting a string to a key value, - * is provided by gdk_keyval_from_name(). - * - * The case of key values can be determined using gdk_keyval_is_upper() and - * gdk_keyval_is_lower(). Key values can be converted to upper or lower case - * using gdk_keyval_to_upper() and gdk_keyval_to_lower(). - * - * When it makes sense, key values can be converted to and from - * Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval(). - * - * # Groups # {#key-group-explanation} - * - * At the lowest level, physical keys on the keyboard are represented by - * numeric keycodes, and GDK knows how to translate these keycodes into - * key values according to the configured keyboard layout and the current - * state of the keyboard. In the GDK api, the mapping from keycodes to key - * values is available via gdk_display_map_keycode(), and the reverse mapping - * is available via gdk_display_map_keyval(). The results of these functions - * are returned in #GdkKeymapKey structs. - * - * You can think of a #GdkKeymapKey as a representation of a symbol printed on - * a physical keyboard key. That is, it contains three pieces of information. - * First, it contains the hardware keycode; this is an identifying number for - * a physical key. Second, it contains the “level” of the key. The level indicates - * which symbol on the key will be used, in a vertical direction. So on a standard - * US keyboard, the key with the number “1“ on it also has the exclamation point - * (”!”) character on it. The level indicates whether to use the “1” or the “!” - * symbol. The letter keys are considered to have a lowercase letter at level 0, - * and an uppercase letter at level 1, though normally only the uppercase letter - * is printed on the key. Third, the #GdkKeymapKey contains a group; groups are - * not used on standard US keyboards, but are used in many other countries. On a - * keyboard with groups, there can be 3 or 4 symbols printed on a single key. - * The group indicates movement in a horizontal direction. Usually groups are - * used for two different languages. In group 0, a key might have two English - * characters, and in group 1 it might have two Hebrew characters. The Hebrew - * characters will be printed on the key next to the English characters. - * - * When GDK creates a key event in order to deliver a key press or release, - * it first converts the current keyboard state into an effective group and - * level. This is done via a set of rules that varies widely according to - * type of keyboard and user configuration. The input to this translation - * consists of the hardware keycode pressed, the active modifiers, and the - * active group. It then applies the appropriate rules, and returns the - * group/level to be used to index the keymap, along with the modifiers - * which did not affect the group and level. i.e. it returns “unconsumed - * modifiers.” The keyboard group may differ from the effective group used - * for lookups because some keys don't have multiple groups - e.g. the Enter - * key is always in group 0 regardless of keyboard state. - * - * The results of the translation, including the keyval, are all included - * in the key event and can be obtained via #GdkEvent getters. - * - * # Consumed modifiers - * - * The @consumed_modifiers in a key event are modifiers that should be masked - * out from @state when comparing this key press to a hot key. For instance, - * on a US keyboard, the `plus` symbol is shifted, so when comparing a key - * press to a `plus` accelerator `` should be masked out. - * - * |[ - * // We want to ignore irrelevant modifiers like ScrollLock - * #define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_ALT_MASK) - * state = gdk_event_get_modifier_state (event); - * gdk_keymap_translate_keyboard_state (keymap, - * gdk_key_event_get_keycode (event), - * state, - * gdk_key_event_get_group (event), - * &keyval, NULL, NULL, &consumed); - * if (keyval == GDK_PLUS && - * (state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK) - * // Control was pressed - * ]| - * - * An older interpretation @consumed_modifiers was that it contained - * all modifiers that might affect the translation of the key; - * this allowed accelerators to be stored with irrelevant consumed - * modifiers, by doing: - * |[ - * // XXX Don’t do this XXX - * if (keyval == accel_keyval && - * (state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed)) - * // Accelerator was pressed - * ]| - * - * However, this did not work if multi-modifier combinations were - * used in the keymap, since, for instance, `` would be - * masked out even if only `` was used in the keymap. - * To support this usage as well as well as possible, all single - * modifier combinations that could affect the key for any combination - * of modifiers will be returned in @consumed_modifiers; multi-modifier - * combinations are returned only when actually found in @state. When - * you store accelerators, you should always store them with consumed - * modifiers removed. Store `plus`, not `plus`. - */ - enum { PROP_0, PROP_DISPLAY, diff --git a/gdk/gdkpango.c b/gdk/gdkpango.c index e050b985c6..5c25b3521b 100644 --- a/gdk/gdkpango.c +++ b/gdk/gdkpango.c @@ -25,101 +25,6 @@ #include -/** - * SECTION:pango_interaction - * @Short_description: Using Pango in GDK - * @Title: Pango Interaction - * - * Pango is the text layout system used by GDK and GTK. The functions - * and types in this section are used to obtain clip regions for - * #PangoLayouts, and to get #PangoContexts that can be used with - * GDK. - * - * Creating a #PangoLayout object is the first step in rendering text, - * and requires getting a handle to a #PangoContext. For GTK programs, - * you’ll usually want to use gtk_widget_get_pango_context(), or - * gtk_widget_create_pango_layout(). Once you have a #PangoLayout, - * you can set the text and attributes of it with Pango functions like - * pango_layout_set_text() and get its size with pango_layout_get_size(). - * (Note that Pango uses a fixed point system internally, so converting - * between Pango units and pixels using [PANGO_SCALE][PANGO-SCALE-CAPS] - * or the PANGO_PIXELS() macro.) - * - * Rendering a Pango layout is done most simply with pango_cairo_show_layout(); - * you can also draw pieces of the layout with pango_cairo_show_layout_line(). - * - * ## Draw transformed text with Pango and cairo ## {#rotated-example} - * - * |[ - * #define RADIUS 100 - * #define N_WORDS 10 - * #define FONT "Sans Bold 18" - * - * PangoContext *context; - * PangoLayout *layout; - * PangoFontDescription *desc; - * - * double radius; - * int width, height; - * int i; - * - * // Set up a transformation matrix so that the user space coordinates for - * // where we are drawing are [-RADIUS, RADIUS], [-RADIUS, RADIUS] - * // We first center, then change the scale - * - * width = gdk_surface_get_width (surface); - * height = gdk_surface_get_height (surface); - * radius = MIN (width, height) / 2.; - * - * cairo_translate (cr, - * radius + (width - 2 * radius) / 2, - * radius + (height - 2 * radius) / 2); - * cairo_scale (cr, radius / RADIUS, radius / RADIUS); - * - * // Create a PangoLayout, set the font and text - * context = gdk_pango_context_get_for_display (display); - * layout = pango_layout_new (context); - * pango_layout_set_text (layout, "Text", -1); - * desc = pango_font_description_from_string (FONT); - * pango_layout_set_font_description (layout, desc); - * pango_font_description_free (desc); - * - * // Draw the layout N_WORDS times in a circle - * for (i = 0; i < N_WORDS; i++) - * { - * double red, green, blue; - * double angle = 2 * G_PI * i / n_words; - * - * cairo_save (cr); - * - * // Gradient from red at angle == 60 to blue at angle == 300 - * red = (1 + cos (angle - 60)) / 2; - * green = 0; - * blue = 1 - red; - * - * cairo_set_source_rgb (cr, red, green, blue); - * cairo_rotate (cr, angle); - * - * // Inform Pango to re-layout the text with the new transformation matrix - * pango_cairo_update_layout (cr, layout); - * - * pango_layout_get_size (layout, &width, &height); - * - * cairo_move_to (cr, - width / 2 / PANGO_SCALE, - DEFAULT_TEXT_RADIUS); - * pango_cairo_show_layout (cr, layout); - * - * cairo_restore (cr); - * } - * - * g_object_unref (layout); - * g_object_unref (context); - * ]| - * - * ## Output of the [example][rotated-example] above. - * - * ![](rotated-text.png) - */ - /* Get a clip region to draw only part of a layout. index_ranges * contains alternating range starts/stops. The region is the * region which contains the given ranges, i.e. if you draw with the diff --git a/gdk/gdkrectangle.c b/gdk/gdkrectangle.c index 8043716044..83b77429cf 100644 --- a/gdk/gdkrectangle.c +++ b/gdk/gdkrectangle.c @@ -29,23 +29,24 @@ /** - * SECTION:regions + * SECTION:gdkregion * @Short_description: Simple graphical data type * @Title: GdkRectangle * - * GDK provides a #GdkRectangle data type for representing rectangles. - * Together with Cairo’s #cairo_region_t data type, these are the central + * GDK provides a `GdkRectangle` data type for representing rectangles. + * Together with Cairo’s `cairo_region_t` data type, these are the central * types for representing sets of pixels. * * A #GdkRectangle represents the position and size of a rectangle. + * * The intersection of two rectangles can be computed with - * gdk_rectangle_intersect(). To find the union of two rectangles use - * gdk_rectangle_union(). + * [method@Gdk.Rectangle.intersect]; to find the union of two rectangles use + * [method@Gdk.Rectangle.union]. * - * #cairo_region_t is usually used for managing clipping of graphical - * operations. + * The `cairo_region_t` type provided by Cairo is usually used for managing + * non-rectangular clipping of graphical operations. * - * The graphene library has a number of other data types for regions and + * The Graphene library has a number of other data types for regions and * volumes in 2D and 3D. */ diff --git a/gdk/gdkrgba.c b/gdk/gdkrgba.c index 1de2bd45a9..a2525591c9 100644 --- a/gdk/gdkrgba.c +++ b/gdk/gdkrgba.c @@ -31,7 +31,7 @@ #include /** - * SECTION:rgba_colors + * SECTION:gdkrgba * @Title: GdkRGBA * @Short_description: RGBA colors * diff --git a/gdk/macos/gdkmacosdisplay.c b/gdk/macos/gdkmacosdisplay.c index ea07215794..ed15a49bf2 100644 --- a/gdk/macos/gdkmacosdisplay.c +++ b/gdk/macos/gdkmacosdisplay.c @@ -38,40 +38,6 @@ #include "gdkmacossurface-private.h" #include "gdkmacosutils-private.h" -/** - * SECTION:macos_interaction - * @Short_description: macOS backend-specific functions - * @Title: macOS Interaction - * @Include: gdk/macos/gdkmacos.h - * - * The functions in this section are specific to the GDK macOS backend. - * To use them, you need to include the `` header and - * use the macOS-specific pkg-config `gtk4-macos` file to build your - * application. - * - * To make your code compile with other GDK backends, guard backend-specific - * calls by an ifdef as follows. Since GDK may be built with multiple - * backends, you should also check for the backend that is in use (e.g. by - * using the GDK_IS_MACOS_DISPLAY() macro). - * |[ - * #ifdef GDK_WINDOWING_MACOS - * if (GDK_IS_MACOS_DISPLAY (display)) - * { - * // make macOS-specific calls here - * } - * else - * #endif - * #ifdef GDK_WINDOWING_X11 - * if (GDK_IS_X11_DISPLAY (display)) - * { - * // make X11-specific calls here - * } - * else - * #endif - * g_error ("Unsupported GDK backend"); - * ]| - */ - G_DEFINE_TYPE (GdkMacosDisplay, gdk_macos_display, GDK_TYPE_DISPLAY) #define EVENT_MAP_MAX_SIZE 10 diff --git a/gdk/wayland/gdkdisplay-wayland.c b/gdk/wayland/gdkdisplay-wayland.c index 9448beda2d..673c9d3478 100644 --- a/gdk/wayland/gdkdisplay-wayland.c +++ b/gdk/wayland/gdkdisplay-wayland.c @@ -58,40 +58,6 @@ #include "gdk/gdk-private.h" -/** - * SECTION:wayland_interaction - * @Short_description: Wayland backend-specific functions - * @Title: Wayland Interaction - * @Include: gdk/wayland/gdkwayland.h - * - * The functions in this section are specific to the GDK Wayland backend. - * To use them, you need to include the `` header and - * use the Wayland-specific pkg-config `gtk4-wayland` file to build your - * application. - * - * To make your code compile with other GDK backends, guard backend-specific - * calls by an ifdef as follows. Since GDK may be built with multiple - * backends, you should also check for the backend that is in use (e.g. by - * using the GDK_IS_WAYLAND_DISPLAY() macro). - * |[ - * #ifdef GDK_WINDOWING_WAYLAND - * if (GDK_IS_WAYLAND_DISPLAY (display)) - * { - * // make Wayland-specific calls here - * } - * else - * #endif - * #ifdef GDK_WINDOWING_X11 - * if (GDK_IS_X11_DISPLAY (display)) - * { - * // make X11-specific calls here - * } - * else - * #endif - * g_error ("Unsupported GDK backend"); - * ]| - */ - #define MIN_SYSTEM_BELL_DELAY_MS 20 #define GTK_SHELL1_VERSION 4 diff --git a/gdk/x11/gdkmain-x11.c b/gdk/x11/gdkmain-x11.c index 7c5fbf2763..8fc8253295 100644 --- a/gdk/x11/gdkmain-x11.c +++ b/gdk/x11/gdkmain-x11.c @@ -46,39 +46,6 @@ #include #endif -/** - * SECTION:x_interaction - * @Short_description: X backend-specific functions - * @Title: X Window System Interaction - * @Include: gdk/x11/gdkx.h - * - * The functions in this section are specific to the GDK X11 backend. - * To use them, you need to include the `` header and use - * the X11-specific pkg-config file `gtk4-x11` to build your application. - * - * To make your code compile with other GDK backends, guard backend-specific - * calls by an ifdef as follows. Since GDK may be built with multiple - * backends, you should also check for the backend that is in use (e.g. by - * using the GDK_IS_X11_DISPLAY() macro). - * |[ - * #ifdef GDK_WINDOWING_X11 - * if (GDK_IS_X11_DISPLAY (display)) - * { - * // make X11-specific calls here - * } - * else - * #endif - * #ifdef GDK_WINDOWING_MACOS - * if (GDK_IS_MACOS_DISPLAY (display)) - * { - * // make MacOS-specific calls here - * } - * else - * #endif - * g_error ("Unsupported GDK backend"); - * ]| - */ - /* non-GDK previous error handler */ typedef int (*GdkXErrorHandler) (Display *, XErrorEvent *); static GdkXErrorHandler _gdk_old_error_handler;