diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 300cb865a1f54f3db8adfc660d62ee2da154431f..aaf0c27d7f72e3e88cf5fc342824a5543c0a859c 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -26,7 +26,7 @@ variables: MESON_TEST_TIMEOUT_MULTIPLIER: 3 FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/gtk/fedora:v28" FLATPAK_IMAGE: "registry.gitlab.gnome.org/gnome/gnome-runtime-images/gnome:master" - DOCS_IMAGE: "registry.gitlab.gnome.org/gnome/gtk/fedora-docs:v25" + DOCS_IMAGE: "registry.gitlab.gnome.org/gnome/gtk/fedora-docs:v26" .only-default: only: @@ -290,11 +290,13 @@ reference: EXTRA_MESON_FLAGS: "--buildtype=release" script: - meson ${COMMON_MESON_FLAGS} ${EXTRA_MESON_FLAGS} -Dgtk_doc=true _build - - ninja -C _build gdk4-doc gsk4-doc gtk4-doc + - meson compile -C _build - mkdir -p _reference/ - - mv _build/docs/reference/gdk/html/ _reference/gdk/ - - mv _build/docs/reference/gsk/html/ _reference/gsk/ - - mv _build/docs/reference/gtk/html/ _reference/gtk/ + - mv _build/docs/reference/gdk/gdk4/ _reference/gdk4/ + - mv _build/docs/reference/gdk/gdk4-x11/ _reference/gdk4-x11/ + - mv _build/docs/reference/gdk/gdk4-wayland/ _reference/gdk4-wayland/ + - mv _build/docs/reference/gsk/gsk4/ _reference/gsk4/ + - mv _build/docs/reference/gtk/gtk4/ _reference/gtk4/ artifacts: paths: - _reference diff --git a/.gitlab-ci/README.md b/.gitlab-ci/README.md index e7b063144f93f6b0bbe3804deb71fa936fae5421..162a1a88df6d24821199e8da9efe000a0574fc1b 100644 --- a/.gitlab-ci/README.md +++ b/.gitlab-ci/README.md @@ -17,8 +17,8 @@ branch, as well as their available versions. ### Checklist for Updating a CI image - [ ] Update the `${image}.Dockerfile` file with the dependencies - - [ ] Run `./run-docker.sh build --base ${image} --base-version ${number}` - - [ ] Run `./run-docker.sh push --base ${image} --base-version ${number}` + - [ ] Run `./run-docker.sh build --base ${image} --version ${number}` + - [ ] Run `./run-docker.sh push --base ${image} --version ${number}` once the Docker image is built; you may need to log in by using `docker login` or `podman login` - [ ] Update the `image` keys in the `.gitlab-ci.yml` file with the new @@ -30,8 +30,8 @@ branch, as well as their available versions. - [ ] Write a new `${image}.Dockerfile` with the instructions to set up a build environment - [ ] Add the `pip3 install meson` incantation - - [ ] Run `./run-docker.sh build --base ${image} --base-version ${number}` - - [ ] Run `./run-docker.sh push --base ${image} --base-version ${number}` + - [ ] Run `./run-docker.sh build --base ${image} --version ${number}` + - [ ] Run `./run-docker.sh push --base ${image} --version ${number}` - [ ] Add the new job to `.gitlab-ci.yml` referencing the image - [ ] Open a merge request with your changes and let it run diff --git a/.gitlab-ci/fedora-docs.Dockerfile b/.gitlab-ci/fedora-docs.Dockerfile index d2e8c5ad40437633a33f8886fb50533009129227..d9c9b44ea23e9f2c41b45fe75b20286d90995c04 100644 --- a/.gitlab-ci/fedora-docs.Dockerfile +++ b/.gitlab-ci/fedora-docs.Dockerfile @@ -1,6 +1,11 @@ -FROM registry.gitlab.gnome.org/gnome/gtk/fedora-base:v25 +FROM registry.gitlab.gnome.org/gnome/gtk/fedora-base:v28 -RUN dnf -y install pandoc +RUN dnf -y install \ + python3-jinja2 \ + python3-markdown \ + python3-pygments \ + python3-toml \ + python3-typogrify ARG HOST_USER_ID=5555 ENV HOST_USER_ID ${HOST_USER_ID} diff --git a/.gitlab-ci/run-docker.sh b/.gitlab-ci/run-docker.sh index a992f9f60a11a01bd3fa5f61e5e25d379dce5e59..c911e6afe180a306c01bc99b4bc5c25d51b9e0f2 100755 --- a/.gitlab-ci/run-docker.sh +++ b/.gitlab-ci/run-docker.sh @@ -32,7 +32,7 @@ while (($# > 0)); do list) list=1;; help) print_help=1;; --base|-b) read_arg base "$@" || shift;; - --base-version) read_arg base_version "$@" || shift;; + --version|-v) read_arg base_version "$@" || shift;; --no-login) no_login=1;; *) echo -e "\e[1;31mERROR\e[0m: Unknown option '$1'"; exit 1;; esac diff --git a/docs/CODING-STYLE.md b/docs/CODING-STYLE.md index 11d105edd961f1efc7a0c1fb082604882dd73777..d48df10f6f7708c12944eafd04221a3c0eb1da75 100644 --- a/docs/CODING-STYLE.md +++ b/docs/CODING-STYLE.md @@ -696,27 +696,29 @@ Public macros should not be used unless they evaluate to a constant. ### Symbol visibility Any symbol that is not explicitly annotated using a `GDK_AVAILABLE_IN_*` -macro is considered internal, and not exported in the shared library. +or `GDK_DEPRECATED_IN_*` macro is considered internal, and not exported +in the shared library. Never export variables as public API, since this is cumbersome on some platforms. It is always preferable to add getters and setters instead. Non-exported functions that are needed in more than one source file -should be declared in a private header file. +should be declared in a private header file with a name that ends in +`private.h`. Non-exported functions that are only needed in one source file should be declared static. ### Documentation -All public APIs must have gtk-doc comments. For functions, these should +All public APIs must have doc comments. For functions, these should be placed in the source file, directly above the function. ```c /* valid */ /** * gtk_get_flow: - * @widget: a #GtkWidget + * @widget: a `GtkWidget` * * Gets the flow of a widget. * @@ -736,29 +738,34 @@ be placed in the source file, directly above the function. Doc comments for macros, function types, class structs, etc should be placed next to the definitions, typically in headers. -Section introductions should be placed in the source file they describe, -after the license header: +The main content of the doc comments uses markdown, which can include +inline formatting, sections, tables, images, links. For links to +symbols/classes/etc, we use a markdown extension syntax like this: + +[class@Gtk.Widget], [method@Gtk.ListView.get_factory],... + +Every doc comment should start with a single-sentence paragraph that +can serve as a summary of sorts (it will often be placed next to a +link pointing to the full documentation for the symbol/class/etc). +The summary should not include links. + +Long-form documentation for classes should be included in the doc +comment for the struct, typically at the top of the source file, +after the license header and includes: ```c - /* valid */ /** - * SECTION:gtksizerequest - * @Short_Description: Height-for-width geometry management - * @Title: GtkSizeRequest + * GtkSizeRequest: + * + * The GtkSizeRequest interface is GTK's height-for-width geometry + * geometry management system. + * + * # Geometry management * - * The GtkSizeRequest interface is GTK's height-for-width (and - * width-for-height) geometry management system. * ... */ ``` -To properly document a new function, macro, function type or struct, -it needs to be listed in the `sections.txt` file. - -To properly document a new class, it needs to be given its own section -in the sections.txt, needs to be included in the `docs.xml` file, and the -`get_type` function needs to listed in the `.types` file. - For more information on the documentation style and contribution guidelines, please [follow the corresponding contribution guide](./reference/README.md). diff --git a/docs/reference/README.md b/docs/reference/README.md index 94ea3896972d634bcf7e50dd1060441e19424db0..6594f58f366fe54e80a82a6a5f5fcb32fc9ac857 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -6,40 +6,41 @@ The GTK documentation is divided in two major components: source code - static pages that provide an overview of specific sections of the API -In both cases, the contents are parsed, converted into DocBook format, and -cross-linked in order to match types, functions, signals, and properties. -From the DocBook output, we generate HTML, which can be used to read the -documentation both offline and online. +In both cases, the contents are parsed as markdown and cross-linked in order +to match types, functions, signals, and properties. Ultimatively, we generate +HTML, which can be used to read the documentation both offline and online. -In both cases, contributing to the GTK documentation requires modifying -files tracked in the source control repository, and follows the same steps -as any other code contribution as outlined in the GTK [contribution -guide][contributing]. Please, refer to that document for any further -question on the mechanics of contributing to GTK. +Contributing to the GTK documentation requires modifying files tracked in the +source control repository, and follows the same steps as any other code +contribution as outlined in the GTK [contribution guide][contributing]. +Please, refer to that document for any further question on the mechanics +of contributing to GTK. -GTK uses [gtk-doc][gtkdoc] to generate its documentation. Please, visit the -gtk-doc website to read the project's documentation. +GTK uses [gi-docgen][gidocgen] to generate its documentation. Please, visit +the gi-docgen website to read the project's documentation. [contributing]: ../../CONTRIBUTING.md -[gtkdoc]: https://wiki.gnome.org/DocumentationProject/GtkDoc +[gi-docgen]: https://gitlab.gnome.org/ebassi/gi-docgen ## Contributing to the API reference Whenever you need to add or modify the documentation of a type or a -function, you will need to edit a `gtk-doc` comment stanza, typically right +function, you will need to edit a comment stanza, typically right above the type or function declaration. For instance: ```c /** * gtk_foo_set_bar: - * @self: a #GtkFoo - * @bar: a #GtkBar + * @self: a foo widget + * @bar: (nullable): the bar to set * - * Sets the given #GtkBar instance on a #GtkFoo widget. + * Sets the given `GtkBar` instance on a foo widget. + * + * Returns: `TRUE` if the bar was set */ -void +gboolean gtk_foo_set_bar (GtkFoo *self, - GtkBar *bar) + GtkBar *bar) { ... ``` @@ -51,31 +52,14 @@ Or, for types: * GtkFoo: * * A foo widget instance. - * - * The contents of this structure are private and should never - * be accessed directly. */ struct _GtkFoo { + /*< private >*/ GtkWidget parent_instance; }; ``` -Each public function and type in the GTK API reference must be listed in the -`sections.txt` file for the specific namespace to which it belongs: GDK, -GSK, or GTK. For instance, if you add a function named `gtk_foo_set_bar()`, -you will need to: - - 1. open `docs/reference/gtk/gtk4-sections.txt` - 1. find the section that lists the symbols of the `GtkFoo` type - 1. add `gtk_foo_set_bar` to the list - -New classes require: - - 1. a new section in the `sections.txt` file - 1. the `get_type` function added to the `.types` file - 1. an `xinclude` element in the `docs.xml` file - The GTK documentation also contains a number of 'freestanding' chapters for which the source is in .md files in docs/reference/gtk. @@ -90,49 +74,61 @@ unrelated reasons. ### Syntax -The input syntax for GTK documentation is markdown, in a flavor that is -similar to what you see on gitlab or github. The markdown support for -fragments that are extracted from sources is more limited than for +The input syntax for GTK documentation is Markdown, in a flavor that is +similar to what you see on GitLab or GitHub. The markdown support for +fragments that are extracted from sources is identical to the one for freestanding chapters. As an exception, man pages for tools are currently maintained in docbook, since the conversion from markdown to docbook is losing too much of the expected formatting. In addition to typical markdown formatting such as \*emphasis\* or \_italics\_, -gtk-doc supports a few abbreviations for cross-references and formatting: +the GTK documentation supports additional link formats, like: -`#ClassName` +`[class@Namespace.ClassName]` : Creates a link to the docs for a class -`function()` - : Creates a link to the docs for a function +`[method@Namespace.Method.name]` + : Creates a link to the docs for a method in a class -`%constant` - : Generates suitable markup for enum values or constants +`[func@Namespace.function]` + : Creates a link to the docs for a global function -### Sections +For more information on the available link formats, see the gi-docgen +documentation. - - The "section" of each type must contain a name, to be referenced in the - `sections.txt` file; a title; and a short description. For instance: +Every doc comment should start with a single-sentence paragraph that +can serve as a summary of sorts (it will often be placed next to a +link pointing to the full documentation for the symbol/class/etc). +The summary should not include links. -```c -/** - * SECTION:gtkshortcut - * @Title: GtkShortcut - * @Short_desc: A key shortcut - * - * ... -``` +### Introspection annotations - For classes, the title should be the name of the class. While it's - possible to add section titles directly to the `sections.txt` file, this - is considered deprecated, and should not be done for newly written code. - - For classes, the long description should contain an overview of the type; - what it does; typical use cases; and idiomatic examples of its use. - - For widget classes, the long description of a section should also contain: - - special XML elements and attributes parsed by the class, in case of a - custom GtkBuildable implementation - - the CSS element name to be used by selectors - - the CSS selector hierarchy for children, in case of a composite widget +The purpose of the annotations for function arguments, properties, signals, +etc., is to describe the API in a machine readable way. The annotations +are consumed by language bindings and by the documentation tools. + +For more information about the annotations used by GTK, you should refer to +the [GObject Introspection documentation][gi-annotations]. + +[gi-annotations]: https://gi.readthedocs.io/en/latest/annotations/giannotations.html + +### Type description + +Each type should be annotated with a description of what the type does. + +For classes, the description should contain an overview of the type; +what it does; typical use cases; and idiomatic examples of its use. + +For widget classes, the description should also contain: + + - special XML elements and attributes parsed by the class, in case of a + custom GtkBuildable implementation + - the CSS element name to be used by selectors + - the CSS selector hierarchy for children, in case of a composite widget + - the accessible role of the class + +Each section in a type description can have a heading; it's preferred to use +second and third level headings only. ### Functions @@ -155,17 +151,26 @@ Checks whether the widget is set to be visible or not. - Methods are special functions whose first argument is always the instance of a certain class. The instance argument for newly written code should be called `self`. - - If a method is a setter or a getter for an object property, link the - property in the methods's description. + - If a method is a setter or a getter for an object property, you should + add an `(attributes org.gtk.Method.set_property=property-name)` or a + an `(attributes org.gtk.Method.get_property=property-name)` annotation + to the method's identifier - If a method changes one or more properties as side effect, link those properties in the method's description - - If a method is a signal emitter, link the signal in the method's - description. + - If a method is a signal emitter, you should use the + `(attributes org.gtk.Method.signal=signal-name)` annotation in + the method's identifier + +### Arguments and return values + + - Arguments should be descriptive, but short + - There is no need to mention the type of the argument + - Always annotate nullability, direction, and ownership transfer ### Signals - While GObject can introspect argument and return types for signals, - you should *always* document them with an explicit gtk-doc stanza. + you should *always* document them with an explicit documentation stanza. - The syntax for signal stanzas is similar to functions: ```c @@ -181,12 +186,15 @@ Checks whether the widget is set to be visible or not. - While GObject properties contain text that can be extracted programmatically in order to build their documentation, you should - *always* document them with an explicit gtk-doc stanza. The text + *always* document them with an explicit documentation stanza. The text associated to the property is short and meant to be used when programmatically building user interfaces, and not for documentation purposes. - Always note if setting a property has side effects, like causing another property to change state. + - If the property has public accessors you should annotate it with + the `(attributes org.gtk.Property.set=setter_function)` and + `(attributes org.gtk.Property.get=getter_function)` attributes - The syntax for property documentation is: ```c @@ -198,8 +206,9 @@ Checks whether the widget is set to be visible or not. ### Actions - - Actions are new in GTK 4, and gtk-doc had to learn a new syntax - to document them: + - Actions are new in GTK 4, and describe an action associated to + a widget class + - The syntax for action documentation is: ``` /**c diff --git a/docs/reference/gdk/cairo.md b/docs/reference/gdk/cairo.md new file mode 100644 index 0000000000000000000000000000000000000000..f7d3c969b4369dd5017986856ae29c924c4667a3 --- /dev/null +++ b/docs/reference/gdk/cairo.md @@ -0,0 +1,18 @@ +---- +Title: Cairo interaction +---- + +## Functions to support using cairo + +[Cairo](http://cairographics.org) is a graphics library that supports vector +graphics and image compositing that can be used with GTK. + +GDK does not wrap the Cairo API; instead it allows to create Cairo +drawing contexts which can be used to draw on [class@Gdk.Surface]s. + +Additional functions allow use [struct@Gdk.Rectangle]s with Cairo +and to use [struct@Gdk.RGBA], `GdkPixbuf`, and [class@Gdk.Surface] +instances as sources for drawing operations. + +For more information on Cairo, please see the +[Cairo API reference](https://www.cairographics.org/manual/). diff --git a/docs/reference/gdk/gdk4-docs.xml b/docs/reference/gdk/gdk4-docs.xml deleted file mode 100644 index d63c7e346c6fc6a0e9d706fa51060b8184e99a7c..0000000000000000000000000000000000000000 --- a/docs/reference/gdk/gdk4-docs.xml +++ /dev/null @@ -1,89 +0,0 @@ - - - -]> - - - GDK 4 Reference Manual - - This document is for the GDK 4 library, version &version;. - The latest versions can be found online at - https://developer.gnome.org/gdk4/. - If you are looking for the older GDK 3 series of libraries, - see https://developer.gnome.org/gdk3/. - - - - - API Reference - - - - - -
- -
- - - - - - - - -
- - -
- -
- -
- -
- -
- -
- - - -
- - - - - - - - - - - - - - GDK Platform Support - - - - - - - Index of all symbols - - - - Index of new symbols in 4.2 - - - - Index of deprecated symbols - - - - - - diff --git a/docs/reference/gdk/gdk4-overrides.txt b/docs/reference/gdk/gdk4-overrides.txt deleted file mode 100644 index 5dab67c7c97673ccc31e4b1bc6faa76cc04b20d6..0000000000000000000000000000000000000000 --- a/docs/reference/gdk/gdk4-overrides.txt +++ /dev/null @@ -1,25 +0,0 @@ - - -GDK_WINDOWING_X11 -#define GDK_WINDOWING_X11 - - - -GDK_WINDOWING_WIN32 -#define GDK_WINDOWING_WIN32 - - - -GDK_WINDOWING_MACOS -#define GDK_WINDOWING_MACOS - - - -GDK_WINDOWING_WAYLAND -#define GDK_WINDOWING_WAYLAND - - - -GDK_DISABLE_DEPRECATION_WARNINGS -#define GDK_DISABLE_DEPRECATION_WARNINGS - diff --git a/docs/reference/gdk/gdk4-sections.txt b/docs/reference/gdk/gdk4-sections.txt deleted file mode 100644 index 5d0cd8a11a7e9adf1fa02dafe204bc09702edd70..0000000000000000000000000000000000000000 --- a/docs/reference/gdk/gdk4-sections.txt +++ /dev/null @@ -1,1350 +0,0 @@ -gdk/gdk.h - -
-General -general - - -GDK_WINDOWING_X11 -GDK_WINDOWING_WIN32 -GDK_WINDOWING_MACOS -GDK_WINDOWING_WAYLAND - - -GDK_MAJOR_VERSION -GDK_MICRO_VERSION -GDK_MINOR_VERSION - - -GDK_VERSION_4_0 -GDK_VERSION_MIN_REQUIRED -GDK_VERSION_MAX_ALLOWED -GDK_DISABLE_DEPRECATION_WARNINGS - - -GDK_TYPE_GRAB_STATUS - - -GDK_TYPE_STATUS -GdkStatus -GDKVAR -GDK_EXTERN_VAR -_GDK_EXTERN -GDK_DECLARE_INTERNAL_TYPE -gdk_axis_use_get_type -gdk_byte_order_get_type -gdk_crossing_mode_get_type -gdk_cursor_type_get_type -gdk_drag_action_get_type -gdk_drag_protocol_get_type -gdk_event_mask_get_type -gdk_event_type_get_type -gdk_extension_mode_get_type -gdk_filter_return_get_type -gdk_grab_ownership_get_type -gdk_grab_status_get_type -gdk_gravity_get_type -gdk_input_mode_get_type -gdk_input_source_get_type -gdk_modifier_intent_get_type -gdk_modifier_type_get_type -gdk_notify_type_get_type -gdk_prop_mode_get_type -gdk_scroll_direction_get_type -gdk_setting_action_get_type -gdk_status_get_type -gdk_visibility_state_get_type -gdk_surface_attributes_type_get_type -gdk_surface_edge_get_type -gdk_surface_hints_get_type -gdk_surface_state_get_type -gdk_surface_type_get_type -gdk_surface_type_hint_get_type -gdk_wm_decoration_get_type -gdk_wm_function_get_type -GDK_AVAILABLE_IN_4_0 -GDK_AVAILABLE_IN_ALL -GDK_UNAVAILABLE -GDK_DEPRECATED -GDK_DEPRECATED_FOR -GDK_DEPRECATED_IN_4_0 -GDK_DEPRECATED_IN_4_0_FOR -GDK_VERSION_CUR_STABLE -GDK_VERSION_PREV_STABLE -
- -
-gdkdisplay -GdkDisplay -GdkDisplay -gdk_display_open -gdk_display_get_default -gdk_display_get_name -gdk_display_device_is_grabbed -gdk_display_beep -gdk_display_sync -gdk_display_flush -gdk_display_close -gdk_display_is_closed -gdk_display_is_rgba -gdk_display_is_composited -gdk_display_supports_input_shapes -gdk_display_get_app_launch_context -gdk_display_notify_startup_complete -gdk_display_get_default_seat -gdk_display_list_seats -gdk_display_get_monitors -gdk_display_get_monitor_at_surface -gdk_display_get_clipboard -gdk_display_get_primary_clipboard -gdk_display_get_setting -gdk_display_get_startup_notification_id - - -gdk_display_put_event - - -gdk_display_map_keyval -gdk_display_map_keycode -gdk_display_translate_key - - -GDK_DISPLAY -GDK_DISPLAY_OBJECT -GDK_IS_DISPLAY -GDK_TYPE_DISPLAY -GDK_DISPLAY_CLASS -GDK_IS_DISPLAY_CLASS -GDK_DISPLAY_GET_CLASS - - -gdk_display_get_type -GdkDisplayClass -
- -
-gdkdisplaymanager -GdkDisplayManager -GdkDisplayManager -gdk_display_manager_get -gdk_display_manager_get_default_display -gdk_display_manager_set_default_display -gdk_display_manager_list_displays -gdk_display_manager_open_display - - -gdk_set_allowed_backends - - -GDK_DISPLAY_MANAGER -GDK_DISPLAY_MANAGER_CLASS -GDK_DISPLAY_MANAGER_GET_CLASS -GDK_IS_DISPLAY_MANAGER_CLASS -GDK_IS_DISPLAY_MANAGER -GDK_TYPE_DISPLAY_MANAGER -GdkDisplayManagerClass -gdk_display_manager_get_type -
- -
-Pixbufs -pixbufs -gdk_pixbuf_get_from_surface -gdk_pixbuf_get_from_texture -
- -
-RGBA Colors -rgba_colors -GdkRGBA -gdk_rgba_copy -gdk_rgba_free -gdk_rgba_is_clear -gdk_rgba_is_opaque -gdk_rgba_parse -gdk_rgba_equal -gdk_rgba_hash -gdk_rgba_to_string - - -GDK_TYPE_RGBA - - -gdk_rgba_get_type -
- -
-GdkSurface -gdksurface -GdkSurface -GdkGravity -gdk_surface_new_toplevel -gdk_surface_new_popup -gdk_surface_destroy -gdk_surface_is_destroyed -gdk_surface_get_display -gdk_surface_hide -gdk_surface_get_mapped -gdk_surface_translate_coordinates -gdk_surface_beep -gdk_surface_get_scale_factor -gdk_surface_set_opaque_region -gdk_surface_create_gl_context -gdk_surface_create_vulkan_context -gdk_surface_create_cairo_context - - -gdk_surface_queue_render -gdk_surface_get_frame_clock -gdk_surface_request_layout - - -gdk_surface_set_cursor -gdk_surface_get_cursor -gdk_surface_set_input_region -gdk_surface_get_width -gdk_surface_get_height -gdk_surface_get_device_position -GdkModifierType -GDK_MODIFIER_MASK - - -gdk_surface_get_device_cursor -gdk_surface_set_device_cursor - - -GDK_SURFACE -GDK_SURFACE_GET_CLASS -GDK_TYPE_SURFACE -GDK_IS_SURFACE -GDK_SURFACE_CLASS -GDK_IS_SURFACE_CLASS -GDK_TYPE_FILTER_RETURN -GDK_TYPE_GRAVITY -GDK_TYPE_MODIFIER_TYPE -GDK_TYPE_SURFACE_ATTRIBUTES_TYPE -GDK_TYPE_SURFACE_EDGE -GDK_TYPE_SURFACE_HINTS -GDK_TYPE_SURFACE_TYPE -GDK_TYPE_SURFACE_TYPE_HINT -GDK_TYPE_WM_DECORATION -GDK_TYPE_WM_FUNCTION -GDK_TYPE_TOPLEVEL_STATE - - -gdk_surface_get_type -gdk_surface_window_class_get_type -GdkSurfaceClass -GdkSurfaceImpl -GdkSurfaceImplClass -GdkSurfaceRedirect -gdk_surface_impl_get_type -gdk_fullscreen_mode_get_type -
- -
-gdkcontentformats -Content Formats -gdk_intern_mime_type - - -GdkContentFormats -gdk_content_formats_new -gdk_content_formats_new_for_gtype -gdk_content_formats_ref -gdk_content_formats_unref -gdk_content_formats_print -gdk_content_formats_to_string -gdk_content_formats_get_gtypes -gdk_content_formats_get_mime_types -gdk_content_formats_union -gdk_content_formats_match -gdk_content_formats_match_gtype -gdk_content_formats_match_mime_type -gdk_content_formats_contain_gtype -gdk_content_formats_contain_mime_type - - -gdk_content_formats_union_serialize_gtypes -gdk_content_formats_union_deserialize_gtypes -gdk_content_formats_union_serialize_mime_types -gdk_content_formats_union_deserialize_mime_types - - -GdkContentFormatsBuilder -gdk_content_formats_builder_new -gdk_content_formats_builder_free_to_formats -gdk_content_formats_builder_add_formats -gdk_content_formats_builder_add_gtype -gdk_content_formats_builder_add_mime_type - - -gdk_content_formats_builder_ref -gdk_content_formats_builder_unref -gdk_content_formats_builder_to_formats - - -GDK_TYPE_FILE_LIST -gdk_file_list_get_type -gdk_content_formats_get_type -gdk_content_formats_builder_get_type -
- -
-Pango Interaction -pango_interaction -gdk_pango_layout_get_clip_region -gdk_pango_layout_line_get_clip_region -
- -
-Cairo Interaction -cairo_interaction -gdk_surface_create_similar_surface -gdk_cairo_set_source_rgba -gdk_cairo_set_source_pixbuf -gdk_cairo_rectangle -gdk_cairo_region -gdk_cairo_region_create_from_surface -gdk_cairo_draw_from_gl -
- -
-Rectangles and Regions -regions -GdkRectangle -gdk_rectangle_intersect -gdk_rectangle_union -gdk_rectangle_equal -gdk_rectangle_contains_point - - -gdk_rectangle_get_type -
- -
-Keyboard Handling -keys -gdk_keyval_name -gdk_keyval_from_name -gdk_keyval_convert_case -gdk_keyval_to_upper -gdk_keyval_to_lower -gdk_keyval_is_upper -gdk_keyval_is_lower -gdk_keyval_to_unicode -gdk_unicode_to_keyval - -
- -
-GdkDevice -gdkdevice -GdkDevice -GdkInputSource -GdkAxisUse -GdkAxisFlags -GdkDeviceTool -GdkDeviceToolType - - -gdk_device_get_name -gdk_device_get_vendor_id -gdk_device_get_product_id -gdk_device_get_source -gdk_device_get_display -gdk_device_get_has_cursor -gdk_device_get_seat -gdk_device_get_num_touches -gdk_device_get_device_tool -gdk_device_get_caps_lock_state -gdk_device_get_direction -gdk_device_get_modifier_state -gdk_device_get_num_lock_state -gdk_device_get_scroll_lock_state -gdk_device_has_bidi_layouts - - -gdk_device_get_surface_at_position -GdkTimeCoord - - -gdk_device_tool_get_serial -gdk_device_tool_get_tool_type -gdk_device_tool_get_hardware_id -gdk_device_tool_get_axes - - -GDK_TYPE_AXIS_FLAGS -GDK_TYPE_AXIS_USE -GDK_TYPE_EXTENSION_MODE -GDK_TYPE_INPUT_MODE -GDK_TYPE_INPUT_SOURCE -GDK_TYPE_DEVICE_TYPE -GDK_TYPE_GRAB_OWNERSHIP -GDK_DEVICE -GDK_DEVICE_CLASS -GDK_DEVICE_GET_CLASS -GDK_IS_DEVICE -GDK_IS_DEVICE_CLASS -GDK_TYPE_DEVICE -GDK_DEVICE_TOOL -GDK_IS_DEVICE_TOOL - - -GdkDeviceClass -gdk_device_get_type -gdk_device_type_get_type -gdk_device_tool_get_type -gdk_device_tool_new -GDK_MAX_TIMECOORD_AXES -
- -
-GdkDevicePad -gdkdevicepad -GdkDevicePad -GdkDevicePadFeature -gdk_device_pad_get_n_groups -gdk_device_pad_get_group_n_modes -gdk_device_pad_get_n_features -gdk_device_pad_get_feature_group - - -GDK_TYPE_DEVICE_PAD -GDK_DEVICE_PAD -GDK_IS_DEVICE_PAD -GDK_DEVICE_PAD_GET_IFACE - - -gdk_device_pad_get_type -
- -
-GdkSeat -gdkseat -GdkSeat -GdkSeatCapabilities -gdk_seat_get_display -gdk_seat_get_capabilities -gdk_seat_get_pointer -gdk_seat_get_keyboard -gdk_seat_get_devices -gdk_seat_get_tools - - -GDK_SEAT -GDK_IS_SEAT -GDK_TYPE_SEAT -GDK_TYPE_SEAT_CAPABILITIES - - -gdk_seat_get_type -gdk_seat_capabilities_get_type -
- -
-Events -events -GdkEvent -GdkEventType -GdkKeymapKey -GdkKeyMatch -GdkTouchpadGesturePhase -GdkScrollDirection -GdkCrossingMode -GdkNotifyType -GDK_CURRENT_TIME -GDK_PRIORITY_EVENTS -GDK_PRIORITY_REDRAW -GDK_EVENT_PROPAGATE -GDK_EVENT_STOP -GDK_BUTTON_PRIMARY -GDK_BUTTON_MIDDLE -GDK_BUTTON_SECONDARY - - -gdk_event_ref -gdk_event_unref - - -gdk_event_get_event_type -gdk_event_get_surface -gdk_event_get_device -gdk_event_get_device_tool -gdk_event_get_time -gdk_event_get_display -gdk_event_get_seat -GdkEventSequence -gdk_event_get_event_sequence -gdk_event_get_modifier_state -gdk_event_get_position -gdk_event_get_axes -gdk_event_get_axis -gdk_event_get_history -gdk_event_get_pointer_emulated -gdk_event_triggers_context_menu -GdkButtonEvent -gdk_button_event_get_button -GdkScrollEvent -gdk_scroll_event_get_direction -gdk_scroll_event_get_deltas -gdk_scroll_event_is_stop -GdkMotionEvent -GdkKeyEvent -gdk_key_event_get_keyval -gdk_key_event_get_keycode -gdk_key_event_get_consumed_modifiers -gdk_key_event_get_layout -gdk_key_event_get_level -gdk_key_event_is_modifier -gdk_key_event_matches -gdk_key_event_get_match -GdkFocusEvent -gdk_focus_event_get_in -gdk_touch_event_get_emulating_pointer -GdkCrossingEvent -gdk_crossing_event_get_mode -gdk_crossing_event_get_detail -gdk_crossing_event_get_focus -GdkGrabBrokenEvent -gdk_grab_broken_event_get_grab_surface -gdk_grab_broken_event_get_implicit -GdkDeleteEvent -GdkDNDEvent -gdk_dnd_event_get_drop -GdkTouchEvent -GdkTouchpadEvent -gdk_touchpad_event_get_gesture_phase -gdk_touchpad_event_get_n_fingers -gdk_touchpad_event_get_deltas -gdk_touchpad_event_get_pinch_angle_delta -gdk_touchpad_event_get_pinch_scale -GdkPadEvent -gdk_pad_event_get_axis_value -gdk_pad_event_get_button -gdk_pad_event_get_group_mode -GdkProximityEvent - - -gdk_events_get_angle -gdk_events_get_center -gdk_events_get_distance - - -GDK_EVENT -GDK_TYPE_EVENT -GDK_TYPE_EVENT_MASK -GDK_TYPE_EVENT_TYPE -GDK_TYPE_CROSSING_MODE -GDK_TYPE_SCROLL_DIRECTION -GDK_TYPE_NOTIFY_TYPE -GDK_IS_EVENT -GDK_IS_EVENT_TYPE -GDK_TYPE_BUTTON_EVENT -GDK_TYPE_CROSSING_EVENT -GDK_TYPE_DELETE_EVENT -GDK_TYPE_DND_EVENT -GDK_TYPE_FOCUS_EVENT -GDK_TYPE_GRAB_BROKEN_EVENT -GDK_TYPE_KEY_EVENT -GDK_TYPE_MOTION_EVENT -GDK_TYPE_PAD_EVENT -GDK_TYPE_PROXIMITY_EVENT -GDK_TYPE_SCROLL_EVENT -GDK_TYPE_TOUCH_EVENT -GDK_TYPE_TOUCHPAD_EVENT - -gdk_event_get_type -gdk_event_sequence_get_type -gdk_button_event_get_type -gdk_crossing_event_get_type -gdk_delete_event_get_type -gdk_dnd_event_get_type -gdk_focus_event_get_type -gdk_grab_broken_event_get_type -gdk_key_event_get_type -gdk_motion_event_get_type -gdk_pad_event_get_type -gdk_proximity_event_get_type -gdk_scroll_event_get_type -gdk_touch_event_get_type -gdk_touchpad_event_get_type -
- -
-gdkpaintable -GdkPaintable -GdkPaintable -GdkPaintableInterface -GdkPaintableFlags -gdk_paintable_get_current_image -gdk_paintable_snapshot -gdk_paintable_get_flags -gdk_paintable_get_intrinsic_width -gdk_paintable_get_intrinsic_height -gdk_paintable_get_intrinsic_aspect_ratio -gdk_paintable_compute_concrete_size - - -gdk_paintable_invalidate_contents -gdk_paintable_invalidate_size -gdk_paintable_new_empty - - -GdkSnapshot - - -GDK_SNAPSHOT -GDK_TYPE_PAINTABLE -GDK_TYPE_SNAPSHOT -GDK_IS_SNAPSHOT - - -GdkSnapshotClass -gdk_paintable_get_type -gdk_snapshot_get_type -
- - -
-gdkpopuplayout -GdkPopupLayout -GdkPopupLayout -GdkAnchorHints -gdk_popup_layout_new -gdk_popup_layout_ref -gdk_popup_layout_unref -gdk_popup_layout_copy -gdk_popup_layout_equal -gdk_popup_layout_set_anchor_rect -gdk_popup_layout_get_anchor_rect -gdk_popup_layout_set_rect_anchor -gdk_popup_layout_get_rect_anchor -gdk_popup_layout_set_surface_anchor -gdk_popup_layout_get_surface_anchor -gdk_popup_layout_set_anchor_hints -gdk_popup_layout_get_anchor_hints -gdk_popup_layout_set_offset -gdk_popup_layout_get_offset -gdk_popup_layout_set_shadow_width -gdk_popup_layout_get_shadow_width - -GDK_TYPE_POPUP_LAYOUT -gdk_popup_layout_get_type -
- -
-gdkpopup -GdkPopup -GdkPopup -gdk_popup_present -gdk_popup_get_surface_anchor -gdk_popup_get_rect_anchor -gdk_popup_get_parent -gdk_popup_get_position_x -gdk_popup_get_position_y -gdk_popup_get_autohide - -GDK_TYPE_POPUP -
- -
-gdktoplevellayout -GdkToplevelLayout -GdkToplevelLayout -gdk_toplevel_layout_new -gdk_toplevel_layout_ref -gdk_toplevel_layout_unref -gdk_toplevel_layout_copy -gdk_toplevel_layout_equal -gdk_toplevel_layout_set_maximized -gdk_toplevel_layout_get_maximized -gdk_toplevel_layout_set_fullscreen -gdk_toplevel_layout_get_fullscreen -gdk_toplevel_layout_get_fullscreen_monitor -gdk_toplevel_layout_set_resizable -gdk_toplevel_layout_get_resizable - -GDK_TYPE_TOPLEVEL_LAYOUT -gdk_toplevel_layout_get_type -
- -
-gdktoplevelsize -GdkToplevelSize -GdkToplevelSize -gdk_toplevel_size_get_bounds -gdk_toplevel_size_set_size -gdk_toplevel_size_set_min_size -gdk_toplevel_size_set_shadow_width - -GDK_TYPE_TOPLEVEL_SIZE -gdk_toplevel_size_get_type -
- -
-gdktoplevel -GdkToplevel -GdkToplevel -GdkToplevelState -GdkFullscreenMode -GdkSurfaceEdge -gdk_toplevel_present -gdk_toplevel_minimize -gdk_toplevel_lower -gdk_toplevel_focus -gdk_toplevel_get_state -gdk_toplevel_set_title -gdk_toplevel_set_startup_id -gdk_toplevel_set_transient_for -gdk_toplevel_set_modal -gdk_toplevel_set_icon_list -gdk_toplevel_show_window_menu -gdk_toplevel_set_decorated -gdk_toplevel_set_deletable -gdk_toplevel_supports_edge_constraints -gdk_toplevel_inhibit_system_shortcuts -gdk_toplevel_restore_system_shortcuts -gdk_toplevel_begin_resize -gdk_toplevel_begin_move - -GDK_TYPE_TOPLEVEL -gdk_toplevel_get_type -
- -
-Textures -textures -GdkTexture -GdkMemoryTexture -GdkGLTexture -gdk_texture_new_for_pixbuf -gdk_texture_new_from_resource -gdk_texture_new_from_file -gdk_texture_get_width -gdk_texture_get_height -gdk_texture_download -gdk_texture_save_to_png -GdkMemoryFormat -GDK_MEMORY_DEFAULT -gdk_memory_texture_new -gdk_gl_texture_new -gdk_gl_texture_release - - -GdkTextureClass -gdk_texture_get_type -GDK_TYPE_TEXTURE -GDK_IS_TEXTURE -GDK_TEXTURE -GdkGLTextureClass -gdk_gl_texture_get_type -GDK_TYPE_GL_TEXTURE -GDK_IS_GL_TEXTURE -GDK_GL_TEXTURE -GdkMemoryTextureClass -gdk_memory_texture_get_type -GDK_TYPE_MEMORY_TEXTURE -GDK_IS_MEMORY_TEXTURE -GDK_MEMORY_TEXTURE -
- -
-Cursors -cursors -GdkCursor -gdk_cursor_new_from_texture -gdk_cursor_new_from_name -gdk_cursor_get_fallback -gdk_cursor_get_name -gdk_cursor_get_texture -gdk_cursor_get_hotspot_x -gdk_cursor_get_hotspot_y - - -GDK_TYPE_CURSOR -GDK_CURSOR -GDK_IS_CURSOR - - -gdk_cursor_get_type -
- - -
-Drag and Drop -dnd -GdkDrag -GdkDrop -GdkDragCancelReason -gdk_drag_drop_done -gdk_drag_begin -GdkDragAction -GDK_ACTION_ALL - -gdk_drag_get_display -gdk_drag_get_content -gdk_drag_get_actions -gdk_drag_get_selected_action -gdk_drag_get_formats -gdk_drag_get_device -gdk_drag_get_surface -gdk_drag_get_drag_surface -gdk_drag_set_hotspot - - -gdk_drag_action_is_unique - - -GdkDragSurface -GdkDragSurfaceInterface -gdk_drag_surface_present - - -gdk_drop_get_display -gdk_drop_get_device -gdk_drop_get_surface -gdk_drop_get_formats -gdk_drop_get_actions -gdk_drop_get_drag -gdk_drop_status -gdk_drop_finish -gdk_drop_read_async -gdk_drop_read_finish -gdk_drop_read_value_async -gdk_drop_read_value_finish - - -GDK_DRAG -GDK_TYPE_DRAG -GDK_IS_DRAG -GDK_DRAG_CLASS -GDK_DRAG_GET_CLASS -GDK_IS_DRAG_CLASS -GDK_TYPE_DRAG_ACTION -GDK_TYPE_DRAG_PROTOCOL -GDK_TYPE_DROP -GDK_DROP -GDK_IS_DROP -GDK_TYPE_DRAG_SURFACE - - -GdkDragClass -gdk_drag_get_type -GdkDropClass -gdk_drop_get_type -
- -
-x_interaction -GDK_SURFACE_XID -GDK_DISPLAY_XDISPLAY -GDK_POINTER_TO_XID -GDK_XID_TO_POINTER -gdk_x11_lookup_xdisplay -gdk_x11_get_server_time -gdk_x11_device_get_id -gdk_x11_device_manager_lookup -gdk_x11_display_open -gdk_x11_display_set_program_class -gdk_x11_display_get_user_time -gdk_x11_display_broadcast_startup_message -gdk_x11_display_get_startup_notification_id -gdk_x11_display_set_startup_notification_id -gdk_x11_display_get_xdisplay -gdk_x11_display_get_xscreen -gdk_x11_display_get_xrootwindow -gdk_x11_display_get_xcursor -gdk_x11_display_grab -gdk_x11_display_ungrab -gdk_x11_display_get_default_group -gdk_x11_display_error_trap_push -gdk_x11_display_error_trap_pop -gdk_x11_display_error_trap_pop_ignored -gdk_x11_display_set_cursor_theme -gdk_x11_display_set_surface_scale -gdk_x11_display_get_glx_version -gdk_x11_display_get_primary_monitor -gdk_x11_display_get_screen -gdk_x11_monitor_get_output -gdk_x11_monitor_get_workarea -gdk_x11_screen_get_screen_number -gdk_x11_screen_get_xscreen -gdk_x11_screen_get_window_manager_name -gdk_x11_screen_get_monitor_output -gdk_x11_screen_supports_net_wm_hint -gdk_x11_screen_get_number_of_desktops -gdk_x11_screen_get_current_desktop -gdk_x11_surface_lookup_for_display -gdk_x11_surface_get_xid -gdk_x11_surface_set_theme_variant -gdk_x11_surface_set_user_time -gdk_x11_surface_move_to_current_desktop -gdk_x11_surface_move_to_desktop -gdk_x11_surface_get_desktop -gdk_x11_surface_set_utf8_property -gdk_x11_surface_set_frame_sync_enabled -gdk_x11_surface_set_group -gdk_x11_surface_get_group -gdk_x11_surface_set_skip_pager_hint -gdk_x11_surface_set_skip_taskbar_hint -gdk_x11_surface_set_urgency_hint -gdk_x11_get_xatom_by_name_for_display -gdk_x11_get_xatom_name_for_display -gdk_x11_set_sm_client_id -gdk_x11_display_text_property_to_text_list -gdk_x11_free_text_list -gdk_x11_display_string_to_compound_text -gdk_x11_display_utf8_to_compound_text -gdk_x11_free_compound_text - - -GDK_TYPE_X11_APP_LAUNCH_CONTEXT -GDK_X11_APP_LAUNCH_CONTEXT -GDK_X11_APP_LAUNCH_CONTEXT_CLASS -GDK_IS_X11_APP_LAUNCH_CONTEXT -GDK_IS_X11_APP_LAUNCH_CONTEXT_CLASS -GDK_X11_APP_LAUNCH_CONTEXT_GET_CLASS -GDK_TYPE_X11_DEVICE_MANAGER_XI2 -GDK_X11_DEVICE_MANAGER_XI2 -GDK_X11_DEVICE_MANAGER_XI2_CLASS -GDK_IS_X11_DEVICE_MANAGER_XI2 -GDK_IS_X11_DEVICE_MANAGER_XI2_CLASS -GDK_X11_DEVICE_MANAGER_XI2_GET_CLASS -GDK_TYPE_X11_DEVICE_MANAGER_XI -GDK_X11_DEVICE_MANAGER_XI -GDK_X11_DEVICE_MANAGER_XI_CLASS -GDK_IS_X11_DEVICE_MANAGER_XI -GDK_IS_X11_DEVICE_MANAGER_XI_CLASS -GDK_X11_DEVICE_MANAGER_XI_GET_CLASS -GDK_TYPE_X11_DEVICE_XI2 -GDK_X11_DEVICE_XI2 -GDK_X11_DEVICE_XI2_CLASS -GDK_IS_X11_DEVICE_XI2 -GDK_IS_X11_DEVICE_XI2_CLASS -GDK_X11_DEVICE_XI2_GET_CLASS -GDK_TYPE_X11_DEVICE_XI -GDK_X11_DEVICE_XI -GDK_X11_DEVICE_XI_CLASS -GDK_IS_X11_DEVICE_XI -GDK_IS_X11_DEVICE_XI_CLASS -GDK_X11_DEVICE_XI_GET_CLASS -GDK_TYPE_X11_DISPLAY -GDK_X11_DISPLAY -GDK_X11_DISPLAY_CLASS -GDK_IS_X11_DISPLAY -GDK_IS_X11_DISPLAY_CLASS -GDK_X11_DISPLAY_GET_CLASS -GDK_TYPE_X11_DRAG_CONTEXT -GDK_X11_DRAG_CONTEXT -GDK_X11_DRAG_CONTEXT_CLASS -GDK_IS_X11_DRAG_CONTEXT -GDK_IS_X11_DRAG_CONTEXT_CLASS -GDK_X11_DRAG_CONTEXT_GET_CLASS -GDK_TYPE_X11_GL_CONTEXT -GDK_X11_GL_CONTEXT -GDK_X11_GL_CONTEXT_CLASS -GDK_IS_X11_GL_CONTEXT -GDK_IS_X11_GL_CONTEXT_CLASS -GDK_TYPE_X11_DRAG -GDK_X11_DRAG -GDK_IS_X11_DRAG -GDK_IS_X11_DRAG_CLASS -GDK_TYPE_X11_MONITOR -GDK_X11_MONITOR -GDK_IS_X11_MONITOR -GDK_TYPE_X11_SURFACE -GDK_X11_SURFACE -GDK_X11_SURFACE_CLASS -GDK_IS_X11_SURFACE -GDK_IS_X11_SURFACE_CLASS -GDK_X11_SURFACE_GET_CLASS - - -gdk_x11_app_launch_context_get_type -gdk_x11_cursor_get_type -gdk_x11_device_manager_xi2_get_type -gdk_x11_device_manager_xi_get_type -gdk_x11_device_xi2_get_type -gdk_x11_device_xi_get_type -gdk_x11_display_get_type -gdk_x11_display_manager_get_type -gdk_x11_drag_context_get_type -gdk_x11_drag_get_type -gdk_x11_gl_context_get_type -gdk_x11_monitor_get_type -gdk_x11_screen_get_type -gdk_x11_surface_get_type -gdk_surface_impl_x11_get_type -
- -
-wayland_interaction - - -gdk_wayland_display_get_wl_display -gdk_wayland_display_get_wl_compositor -gdk_wayland_display_query_registry -gdk_wayland_display_set_cursor_theme -gdk_wayland_display_get_startup_notification_id -gdk_wayland_display_set_startup_notification_id - - -gdk_wayland_seat_get_wl_seat -gdk_wayland_device_get_wl_seat -gdk_wayland_device_get_wl_pointer -gdk_wayland_device_get_wl_keyboard -gdk_wayland_device_get_node_path - - -gdk_wayland_monitor_get_wl_output - - -gdk_wayland_surface_get_wl_surface -GdkWaylandToplevelExported -gdk_wayland_toplevel_export_handle -gdk_wayland_toplevel_unexport_handle -gdk_wayland_toplevel_set_transient_for_exported -gdk_wayland_toplevel_set_application_id - - -GDK_TYPE_WAYLAND_DEVICE -GDK_WAYLAND_DEVICE -GDK_WAYLAND_DEVICE_CLASS -GDK_WAYLAND_DEVICE_GET_CLASS -GDK_IS_WAYLAND_DEVICE -GDK_IS_WAYLAND_DEVICE_CLASS -GDK_TYPE_WAYLAND_DISPLAY -GDK_WAYLAND_DISPLAY -GDK_WAYLAND_DISPLAY_CLASS -GDK_WAYLAND_DISPLAY_GET_CLASS -GDK_IS_WAYLAND_DISPLAY -GDK_IS_WAYLAND_DISPLAY_CLASS -GDK_TYPE_WAYLAND_DISPLAY_MANAGER -GDK_WAYLAND_DISPLAY_MANAGER -GDK_WAYLAND_DISPLAY_MANAGER_CLASS -GDK_WAYLAND_DISPLAY_MANAGER_GET_CLASS -GDK_IS_WAYLAND_DISPLAY_MANAGER -GDK_IS_WAYLAND_DISPLAY_MANAGER_CLASS -GDK_TYPE_WAYLAND_SURFACE -GDK_WAYLAND_SURFACE -GDK_WAYLAND_SURFACE_CLASS -GDK_WAYLAND_SURFACE_GET_CLASS -GDK_IS_WAYLAND_SURFACE -GDK_IS_WAYLAND_SURFACE_CLASS - - -gdk_wayland_device_get_type -gdk_wayland_display_get_type -gdk_wayland_display_manager_get_type -gdk_wayland_gl_context_get_type -gdk_wayland_monitor_get_type -gdk_wayland_popup_get_type -gdk_wayland_seat_get_type -gdk_wayland_surface_get_type -gdk_wayland_toplevel_get_type -
- -
-Application launching -gdkapplaunchcontext -GdkAppLaunchContext -gdk_app_launch_context_get_display -gdk_app_launch_context_set_desktop -gdk_app_launch_context_set_timestamp -gdk_app_launch_context_set_icon -gdk_app_launch_context_set_icon_name - -GDK_APP_LAUNCH_CONTEXT -GDK_APP_LAUNCH_CONTEXT_CLASS -GDK_APP_LAUNCH_CONTEXT_GET_CLASS -GDK_IS_APP_LAUNCH_CONTEXT -GDK_IS_APP_LAUNCH_CONTEXT_CLASS -GDK_TYPE_APP_LAUNCH_CONTEXT -GdkAppLaunchContextClass - -gdk_app_launch_context_get_type -
- -
-GdkFrameClock -gdkframeclock -GdkFrameClock -gdk_frame_clock_get_frame_time -GdkFrameClockPhase -gdk_frame_clock_request_phase -gdk_frame_clock_begin_updating -gdk_frame_clock_end_updating -gdk_frame_clock_get_frame_counter -gdk_frame_clock_get_history_start -gdk_frame_clock_get_timings -gdk_frame_clock_get_current_timings -gdk_frame_clock_get_refresh_info -gdk_frame_clock_get_fps - - -GDK_FRAME_CLOCK -GDK_FRAME_CLOCK_CLASS -GDK_FRAME_CLOCK_GET_CLASS -GDK_FRAME_CLOCK_IDLE -GDK_FRAME_CLOCK_IDLE_CLASS -GDK_FRAME_CLOCK_IDLE_GET_CLASS -GDK_IS_FRAME_CLOCK -GDK_IS_FRAME_CLOCK_CLASS -GDK_IS_FRAME_CLOCK_IDLE -GDK_IS_FRAME_CLOCK_IDLE_CLASS -GdkFrameClockPrivate -gdk_frame_clock_get_type -gdk_frame_clock_idle_get_type -
- -
-GdkFrameTimings -gdkframetimings -GdkFrameTimings -gdk_frame_timings_ref -gdk_frame_timings_unref -gdk_frame_timings_get_frame_counter -gdk_frame_timings_get_complete -gdk_frame_timings_get_frame_time -gdk_frame_timings_get_presentation_time -gdk_frame_timings_get_refresh_interval -gdk_frame_timings_get_predicted_presentation_time - -gdk_frame_timings_get_type -
- -
-gdkdrawcontext -GdkDrawContext -gdk_draw_context_get_display -gdk_draw_context_get_surface -gdk_draw_context_begin_frame -gdk_draw_context_end_frame -gdk_draw_context_is_in_frame -gdk_draw_context_get_frame_region - - -GDK_DRAW_CONTEXT -GDK_IS_DRAW_CONTEXT -GDK_TYPE_DRAW_CONTEXT -GDK_DRAW_CONTEXT_CLASS -GDK_DRAW_CONTEXT_GET_CLASS -GDK_IS_DRAW_CONTEXT_CLASS -gdk_draw_context_get_type -
- -
-gdkglcontext -GdkGLContext -gdk_gl_context_get_display -gdk_gl_context_get_surface -gdk_gl_context_get_shared_context -gdk_gl_context_get_version - - -gdk_gl_context_set_required_version -gdk_gl_context_get_required_version -gdk_gl_context_set_debug_enabled -gdk_gl_context_get_debug_enabled -gdk_gl_context_set_forward_compatible -gdk_gl_context_get_forward_compatible -gdk_gl_context_set_use_es -gdk_gl_context_get_use_es -gdk_gl_context_is_legacy - - -GdkGLError -gdk_gl_context_realize -gdk_gl_context_make_current -gdk_gl_context_get_current -gdk_gl_context_clear_current - - -GDK_GL_CONTEXT -GDK_IS_GL_CONTEXT -GDK_TYPE_GL_CONTEXT -GDK_GL_CONTEXT_CLASS -GDK_GL_CONTEXT_GET_CLASS -GDK_IS_GL_CONTEXT_CLASS -gdk_gl_context_get_type -gdk_gl_error_quark -GDK_GL_ERROR -GDK_TYPE_GL_ERROR -GDK_TYPE_GL_PROFILE -
- -
-gdkmonitor -GdkMonitor -gdk_monitor_get_display -gdk_monitor_get_geometry -gdk_monitor_get_width_mm -gdk_monitor_get_height_mm -gdk_monitor_get_manufacturer -gdk_monitor_get_model -gdk_monitor_get_connector -gdk_monitor_get_scale_factor -gdk_monitor_get_refresh_rate -GdkSubpixelLayout -gdk_monitor_get_subpixel_layout -gdk_monitor_is_valid - - -gdk_monitor_get_type -GdkMonitorClass -GDK_TYPE_MONITOR -GDK_MONITOR -GDK_IS_MONITOR -
- -
-gdkcairocontext -GdkCairoContext -gdk_cairo_context_cairo_create - - -GDK_CAIRO_CONTEXT -GDK_IS_CAIRO_CONTEXT -GDK_TYPE_CAIRO_CONTEXT -GDK_CAIRO_ERROR -gdk_cairo_context_get_type -
- -
-gdkvulkancontext -GdkVulkanContext -GdkVulkanError -gdk_vulkan_context_get_device -gdk_vulkan_context_get_draw_index -gdk_vulkan_context_get_draw_semaphore -gdk_vulkan_context_get_image -gdk_vulkan_context_get_image_format -gdk_vulkan_context_get_instance -gdk_vulkan_context_get_n_images -gdk_vulkan_context_get_physical_device -gdk_vulkan_context_get_queue -gdk_vulkan_context_get_queue_family_index - - -GDK_VULKAN_CONTEXT -GDK_IS_VULKAN_CONTEXT -GDK_TYPE_VULKAN_CONTEXT -GDK_RENDERING_VULKAN -GDK_VULKAN_ERROR -gdk_vulkan_context_get_type -gdk_vulkan_error_quark -gdk_vulkan_strerror -
- -
-gdkclipboard -GdkClipboard -gdk_clipboard_get_display -gdk_clipboard_get_formats -gdk_clipboard_is_local -gdk_clipboard_get_content -gdk_clipboard_store_async -gdk_clipboard_store_finish -gdk_clipboard_read_async -gdk_clipboard_read_finish -gdk_clipboard_read_value_async -gdk_clipboard_read_value_finish -gdk_clipboard_read_texture_async -gdk_clipboard_read_texture_finish -gdk_clipboard_read_text_async -gdk_clipboard_read_text_finish -gdk_clipboard_set_content -gdk_clipboard_set -gdk_clipboard_set_valist -gdk_clipboard_set_value -gdk_clipboard_set_text -gdk_clipboard_set_texture - - -GDK_TYPE_CLIPBOARD -GDK_CLIPBOARD -GDK_IS_CLIPBOARD -gdk_clipboard_get_type -
- -
-gdkcontentprovider -GdkContentProvider -GdkContentProviderClass -gdk_content_provider_new_for_value -gdk_content_provider_new_typed -gdk_content_provider_new_for_bytes -gdk_content_provider_new_union -gdk_content_provider_ref_formats -gdk_content_provider_ref_storable_formats -gdk_content_provider_content_changed -gdk_content_provider_write_mime_type_async -gdk_content_provider_write_mime_type_finish -gdk_content_provider_get_value - - -GDK_CONTENT_PROVIDER -GDK_CONTENT_PROVIDER_CLASS -GDK_CONTENT_PROVIDER_GET_CLASS -GDK_IS_CONTENT_PROVIDER -GDK_IS_CONTENT_PROVIDER_CLASS -gdk_content_provider_get_type -
- -
-gdkcontentserializer -GdkContentSerializer -GdkContentSerializeFunc -gdk_content_serializer_get_mime_type -gdk_content_serializer_get_gtype -gdk_content_serializer_get_value -gdk_content_serializer_get_output_stream -gdk_content_serializer_get_priority -gdk_content_serializer_get_cancellable -gdk_content_serializer_get_user_data -gdk_content_serializer_set_task_data -gdk_content_serializer_get_task_data -gdk_content_serializer_return_success -gdk_content_serializer_return_error - - -gdk_content_register_serializer -gdk_content_serialize_async -gdk_content_serialize_finish - - -GDK_TYPE_CONTENT_SERIALIZER -GDK_CONTENT_SERIALIZER -GDK_IS_CONTENT_SERIALIZER -gdk_content_serializer_get_type -
- -
-gdkcontentdeserializer -GdkContentDeserializer -GdkContentDeserializeFunc -gdk_content_deserializer_get_mime_type -gdk_content_deserializer_get_gtype -gdk_content_deserializer_get_value -gdk_content_deserializer_get_input_stream -gdk_content_deserializer_get_priority -gdk_content_deserializer_get_cancellable -gdk_content_deserializer_get_user_data -gdk_content_deserializer_set_task_data -gdk_content_deserializer_get_task_data -gdk_content_deserializer_return_success -gdk_content_deserializer_return_error - - -gdk_content_register_deserializer -gdk_content_deserialize_async -gdk_content_deserialize_finish - - -GDK_TYPE_CONTENT_DESERIALIZER -GDK_CONTENT_DESERIALIZER -GDK_IS_CONTENT_DESERIALIZER -gdk_content_deserializer_get_type -
diff --git a/docs/reference/gdk/gdk4-wayland.toml.in b/docs/reference/gdk/gdk4-wayland.toml.in new file mode 100644 index 0000000000000000000000000000000000000000..ba47b9dc11903bccf7ee7920f6becd6e0dc63117 --- /dev/null +++ b/docs/reference/gdk/gdk4-wayland.toml.in @@ -0,0 +1,23 @@ +[library] +version = "@version@" +browse_url = "https://gitlab.gnome.org/GNOME/gtk/" +repository_url = "https://gitlab.gnome.org/GNOME/gtk.git" +website_url = "https://www.gtk.org" +authors = "GTK Development Team" +logo_url = "gtk-logo.svg" +license = "GPL-2.1-or-later" +description = "The GTK toolkit" +dependencies = [ "GObject-2.0" ] +devhelp = true + + [dependencies."GObject-2.0"] + name = "GObject" + description = "The base type system library" + docs_url = "https://developer.gnome.org/gobject/stable" + +[theme] +name = "basic" +show_index_summary = true + +[source-location] +base_url = "https://gitlab.gnome.org/GNOME/gtk/-/blob/master/" diff --git a/docs/reference/gdk/gdk4-x11.toml.in b/docs/reference/gdk/gdk4-x11.toml.in new file mode 100644 index 0000000000000000000000000000000000000000..ba47b9dc11903bccf7ee7920f6becd6e0dc63117 --- /dev/null +++ b/docs/reference/gdk/gdk4-x11.toml.in @@ -0,0 +1,23 @@ +[library] +version = "@version@" +browse_url = "https://gitlab.gnome.org/GNOME/gtk/" +repository_url = "https://gitlab.gnome.org/GNOME/gtk.git" +website_url = "https://www.gtk.org" +authors = "GTK Development Team" +logo_url = "gtk-logo.svg" +license = "GPL-2.1-or-later" +description = "The GTK toolkit" +dependencies = [ "GObject-2.0" ] +devhelp = true + + [dependencies."GObject-2.0"] + name = "GObject" + description = "The base type system library" + docs_url = "https://developer.gnome.org/gobject/stable" + +[theme] +name = "basic" +show_index_summary = true + +[source-location] +base_url = "https://gitlab.gnome.org/GNOME/gtk/-/blob/master/" diff --git a/docs/reference/gdk/gdk4.toml.in b/docs/reference/gdk/gdk4.toml.in new file mode 100644 index 0000000000000000000000000000000000000000..f720744f9f4fde5ddcfde80bec1960c26099382a --- /dev/null +++ b/docs/reference/gdk/gdk4.toml.in @@ -0,0 +1,97 @@ +[library] +version = "@version@" +browse_url = "https://gitlab.gnome.org/GNOME/gtk/" +repository_url = "https://gitlab.gnome.org/GNOME/gtk.git" +website_url = "https://www.gtk.org" +authors = "GTK Development Team" +logo_url = "gtk-logo.svg" +license = "GPL-2.1-or-later" +description = "The GTK toolkit" +dependencies = [ "GObject-2.0", "cairo-1.0", "Pango-1.0", "GdkWayland-4.0", "GdkX11-4.0" ] +devhelp = true +search_index = true + + [dependencies."GObject-2.0"] + name = "GObject" + description = "The base type system library" + docs_url = "https://developer.gnome.org/gobject/stable" + + [dependencies."cairo-1.0"] + name = "Cairo" + description = "A 2D graphics library with support for multiple output devices" + docs_url = "https://www.cairographics.org/manual/" + + [dependencies."Pango-1.0"] + name = "Pango" + description = "Text shaping and rendering" + docs_url = "https://developer.gnome.org/pango/stable" + + [dependencies."GdkWayland-4.0"] + name = "GdkWayland" + description = "GDK Wayland Backend" + docs_url = "https://developer.gnome.org/gtk4/stable" # fixme + + [dependencies."GdkX11-4.0"] + name = "GdkX11" + description = "GDK X11 Backend" + docs_url = "https://developer.gnome.org/gtk4/stable" # fixme + +[theme] +name = "basic" +show_index_summary = true +show_class_hierarchy = true + +[source-location] +base_url = "https://gitlab.gnome.org/GNOME/gtk/-/blob/master/" + +[extra] +content_files = [ + "keys.md", + "cairo.md", + "pango.md", + "wayland.md", + "x11.md", + "macos.md", +] +content_images = [ + "images/gtk-logo.svg", + "images/rotated-text.png", + "images/default_cursor.png", + "images/help_cursor.png", + "images/pointer_cursor.png", + "images/context_menu_cursor.png", + "images/progress_cursor.png", + "images/wait_cursor.png", + "images/cell_cursor.png", + "images/crosshair_cursor.png", + "images/text_cursor.png", + "images/vertical_text_cursor.png", + "images/alias_cursor.png", + "images/copy_cursor.png", + "images/no_drop_cursor.png", + "images/move_cursor.png", + "images/not_allowed_cursor.png", + "images/grab_cursor.png", + "images/grabbing_cursor.png", + "images/all_scroll_cursor.png", + "images/col_resize_cursor.png", + "images/row_resize_cursor.png", + "images/n_resize_cursor.png", + "images/e_resize_cursor.png", + "images/s_resize_cursor.png", + "images/w_resize_cursor.png", + "images/ne_resize_cursor.png", + "images/nw_resize_cursor.png", + "images/sw_resize_cursor.png", + "images/se_resize_cursor.png", + "images/ew_resize_cursor.png", + "images/ns_resize_cursor.png", + "images/nesw_resize_cursor.png", + "images/nwse_resize_cursor.png", + "images/zoom_in_cursor.png", + "images/zoom_out_cursor.png", + "images/popup-anchors.png", + "images/popup-flip.png", + "images/popup-slide.png", +] +urlmap_file = "urlmap.js" diff --git a/docs/reference/gdk/gdk4.types b/docs/reference/gdk/gdk4.types deleted file mode 100644 index 3127e63a5c2a4fe814f223c62e2c1bd92b47f9c7..0000000000000000000000000000000000000000 --- a/docs/reference/gdk/gdk4.types +++ /dev/null @@ -1,32 +0,0 @@ -gdk_app_launch_context_get_type -gdk_clipboard_get_type -gdk_content_deserializer_get_type -gdk_content_formats_get_type -gdk_content_provider_get_type -gdk_content_serializer_get_type -gdk_cursor_get_type -gdk_device_get_type -gdk_device_pad_get_type -gdk_device_tool_get_type -gdk_display_get_type -gdk_display_manager_get_type -gdk_drag_get_type -gdk_drag_surface_get_type -gdk_drop_get_type -gdk_event_get_type -gdk_frame_clock_get_type -gdk_gl_context_get_type -gdk_gl_texture_get_type -gdk_memory_texture_get_type -gdk_monitor_get_type -gdk_paintable_get_type -gdk_popup_get_type -gdk_popup_layout_get_type -gdk_rgba_get_type -gdk_seat_get_type -gdk_snapshot_get_type -gdk_surface_get_type -gdk_texture_get_type -gdk_toplevel_get_type -gdk_toplevel_layout_get_type -gdk_vulkan_context_get_type diff --git a/docs/reference/gdk/general.md b/docs/reference/gdk/general.md new file mode 100644 index 0000000000000000000000000000000000000000..6e8243b6ccc0c49d1c951bbcc318e1e74d8ca6ee --- /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/images/gtk-logo.svg b/docs/reference/gdk/images/gtk-logo.svg new file mode 100644 index 0000000000000000000000000000000000000000..9edbe2da97d767814b289ffea337fc9034653d73 --- /dev/null +++ b/docs/reference/gdk/images/gtk-logo.svg @@ -0,0 +1,138 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + diff --git a/docs/reference/gdk/keys.md b/docs/reference/gdk/keys.md new file mode 100644 index 0000000000000000000000000000000000000000..e44d0e13ce0cdcaa01b38e16e235775431de9a21 --- /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 0000000000000000000000000000000000000000..1a0429be9dcaf76e9480db51c5ec8730ea2d4ba9 --- /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/meson.build b/docs/reference/gdk/meson.build index cdd018def9537b416bffe4366606aa96985c2b4c..66b0d150fc0a25e0e0ab829f9335d8135d265890 100644 --- a/docs/reference/gdk/meson.build +++ b/docs/reference/gdk/meson.build @@ -1,190 +1,68 @@ -private_headers = [ - 'gdk-autocleanup.h', - 'gdk-private.h', - 'gdkapplaunchcontextprivate.h', - 'gdkcairocontextprivate.h', - 'gdkcairoprivate.h', - 'gdkclipboardprivate.h', - 'gdkcontentformatsprivate.h', - 'gdkcontentproviderprivate.h', - 'gdkcursorprivate.h', - 'gdkdebug.h', - 'gdkdevicepadprivate.h', - 'gdkdeviceprivate.h', - 'gdkdevicetoolprivate.h', - 'gdkdisplaymanagerprivate.h', - 'gdkdisplayprivate.h', - 'gdkdndprivate.h', - 'gdkdragprivate.h', - 'gdkdragsurfaceprivate.h', - 'gdkdrawcontextprivate.h', - 'gdkdropprivate.h', - 'gdkeventsprivate.h', - 'gdkframeclockidleprivate.h', - 'gdkframeclockprivate.h', - 'gdkglcontextprivate.h', - 'gdkgltextureprivate.h', - 'gdkinternals.h', - 'gdkintl.h', - 'gdkkeysprivate.h', - 'gdkkeysyms.h', - 'gdkmarshalers.h', - 'gdkmemorytextureprivate.h', - 'gdkmonitorprivate.h', - 'gdkpipeiostreamprivate.h', - 'gdkpopupprivate.h', - 'gdkprofilerprivate.h', - 'gdkrgbaprivate.h', - 'gdkscreenprivate.h', - 'gdkseatdefaultprivate.h', - 'gdkseatprivate.h', - 'gdksnapshotprivate.h', - 'gdksurfaceimpl.h', - 'gdksurfaceprivate.h', - 'gdktextureprivate.h', - 'gdktoplevelprivate.h', - 'gdktoplevelsizeprivate.h', - 'gdkvulkancontextprivate.h', - - 'filetransferportalprivate.h', - 'gdkconstructor.h', - 'keyname-table.h', - - # gdk/x11 - 'gdkasync.h', - 'gdkcairocontext-x11.h', - 'gdkclipboard-x11.h', - 'gdkdevice-xi2-private.h', - 'gdkdevicemanagerprivate-core.h', - 'gdkdisplay-x11.h', - 'gdkeventsource.h', - 'gdkeventtranslator.h', - 'gdkglcontext-x11.h', - 'gdkkeys-x11.h', - 'gdkmonitor-x11.h', - 'gdkprivate-x11.h', - 'gdkscreen-x11.h', - 'gdkselectioninputstream-x11.h', - 'gdkselectionoutputstream-x11.h', - 'gdksurface-x11.h', - 'gdktextlistconverter-x11.h', - 'gdkvisual-x11.h', - 'gdkvulkancontext-x11.h', - 'gdkx-autocleanups.h', - 'MwmUtil.h', - 'xsettings-client.h', - - # gdk/wayland - 'gdkcairocontext-wayland.h', - 'gdkclipboard-wayland.h', - 'gdkdevice-wayland-private.h', - 'gdkdisplay-wayland.h', - 'gdkglcontext-wayland.h', - 'gdkmonitor-wayland.h', - 'gdkprimary-wayland.h', - 'gdkprivate-wayland.h', - 'gdkseat-wayland.h', - 'gdksurface-wayland.h', - 'gdkvulkancontext-wayland.h', - 'wm-button-layout-translation.h', - 'gtk-primary-selection-client-protocol.h', - 'gtk-shell-client-protocol.h', - 'idle-inhibit-unstable-v1-client-protocol.h', - 'keyboard-shortcuts-inhibit-unstable-v1-client-protocol.h', - 'pointer-gestures-unstable-v1-client-protocol.h', - 'primary-selection-unstable-v1-client-protocol.h', - 'server-decoration-client-protocol.h', - 'tablet-unstable-v2-client-protocol.h', - 'xdg-foreign-unstable-v1-client-protocol.h', - 'xdg-shell-unstable-v6-client-protocol.h', - 'xdg-output-unstable-v1-client-protocol.h', - 'xdg-shell-client-protocol.h', - 'xdg-shell-unstable-v6-client-protocol.h', - 'wayland-cursor.h', - 'os-compatibility.h', - 'xcursor.h', - - 'broadway', - 'wayland/cursor', - 'macos', - 'win32', +expand_content_md_files = [ ] -images = [ - 'images/rotated-text.png', - 'images/default_cursor.png', - 'images/help_cursor.png', - 'images/pointer_cursor.png', - 'images/context_menu_cursor.png', - 'images/progress_cursor.png', - 'images/wait_cursor.png', - 'images/cell_cursor.png', - 'images/crosshair_cursor.png', - 'images/text_cursor.png', - 'images/vertical_text_cursor.png', - 'images/alias_cursor.png', - 'images/copy_cursor.png', - 'images/no_drop_cursor.png', - 'images/move_cursor.png', - 'images/not_allowed_cursor.png', - 'images/grab_cursor.png', - 'images/grabbing_cursor.png', - 'images/all_scroll_cursor.png', - 'images/col_resize_cursor.png', - 'images/row_resize_cursor.png', - 'images/n_resize_cursor.png', - 'images/e_resize_cursor.png', - 'images/s_resize_cursor.png', - 'images/w_resize_cursor.png', - 'images/ne_resize_cursor.png', - 'images/nw_resize_cursor.png', - 'images/sw_resize_cursor.png', - 'images/se_resize_cursor.png', - 'images/ew_resize_cursor.png', - 'images/ns_resize_cursor.png', - 'images/nesw_resize_cursor.png', - 'images/nwse_resize_cursor.png', - 'images/zoom_in_cursor.png', - 'images/zoom_out_cursor.png', - 'images/popup-anchors.png', - 'images/popup-flip.png', - 'images/popup-slide.png', -] - -src_dir = [ gdkinc ] - -if x11_enabled - src_dir += [ gdkx11_inc ] -endif - -if wayland_enabled - src_dir += [ gdkwayland_inc ] -endif +gdk4_toml = configure_file(input: 'gdk4.toml.in', output: 'gdk4.toml', configuration: toml_conf) +gdk4x11_toml = configure_file(input: 'gdk4-x11.toml.in', output: 'gdk4-x11.toml', configuration: toml_conf) +gdk4wayland_toml = configure_file(input: 'gdk4-wayland.toml.in', output: 'gdk4-wayland.toml', configuration: toml_conf) if get_option('gtk_doc') - configure_file(input: 'version.xml.in', output: 'version.xml', configuration: version_conf) - - gnome.gtkdoc('gdk4', - mode: 'none', - main_xml: 'gdk4-docs.xml', - src_dir: src_dir, - dependencies: libgtk_dep, - gobject_typesfile: join_paths(meson.current_source_dir(), 'gdk4.types'), - scan_args: [ - '--ignore-decorators=_GDK_EXTERN|G_GNUC_WARN_UNUSED_RESULT', - '--ignore-headers=' + ' '.join(private_headers), - ], - mkdb_args: [ - '--ignore-files=' + ' '.join(private_headers), + custom_target('gdk4-doc', + input: [ gdk4_toml, gdk_gir[0] ], + output: 'gdk4', + command: [ + gidocgen, + 'generate', + '--quiet', + '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'), + '--config=@INPUT0@', + '--output-dir=@OUTPUT@', + '--no-namespace-dir', + '--content-dir=@0@'.format(meson.current_source_dir()), + '@INPUT1@', ], - fixxref_args: [ - '--html-dir=@0@'.format(docpath), - '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')), - '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')), - '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')), - '--extra-dir=@0@'.format(cairo_docpath), - ], - html_assets: images, - install: true, + depend_files: [ expand_content_md_files ], + build_by_default: true, ) + + if x11_enabled + custom_target('gdk4-x11-doc', + input: [ gdk4x11_toml, gdk_x11_gir[0] ], + output: 'gdk4-x11', + command: [ + gidocgen, + 'generate', + '--quiet', + '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'), + '--config=@INPUT0@', + '--output-dir=@OUTPUT@', + '--no-namespace-dir', + '--content-dir=@0@'.format(meson.current_source_dir()), + '@INPUT1@', + ], + depends: [ gdk_gir[0] ], + depend_files: [ ], + build_by_default: true, + ) + endif + + if wayland_enabled + custom_target('gdk4-wayland-doc', + input: [ gdk4wayland_toml, gdk_wayland_gir[0] ], + output: 'gdk4-wayland', + command: [ + gidocgen, + 'generate', + '--quiet', + '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'), + '--config=@INPUT0@', + '--output-dir=@OUTPUT@', + '--no-namespace-dir', + '--content-dir=@0@'.format(meson.current_source_dir()), + '@INPUT1@', + ], + depends: [ gdk_gir[0] ], + depend_files: [ ], + build_by_default: true, + ) + endif endif diff --git a/docs/reference/gdk/pango.md b/docs/reference/gdk/pango.md new file mode 100644 index 0000000000000000000000000000000000000000..98ada407809e264a1a97bc5eb356243c92c0d04c --- /dev/null +++ b/docs/reference/gdk/pango.md @@ -0,0 +1,94 @@ + 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 [method@Gtk.Widget.get_pango_context], or +[method@Gtk.Widget.create_pango_layout]. Once you have a `PangoLayout`, +you can set the text and attributes of it with Pango functions like +[method@Pango.Layout.set_text] and get its size with +[method@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 [func@PangoCairo.show_layout]; +you can also draw pieces of the layout with [func@PangoCairo.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/urlmap.js b/docs/reference/gdk/urlmap.js new file mode 100644 index 0000000000000000000000000000000000000000..eaf2de9886ce7c2b07624c98fefe7f4ea7756d8f --- /dev/null +++ b/docs/reference/gdk/urlmap.js @@ -0,0 +1,13 @@ +// SPDX-FileCopyrightText: 2021 GNOME Foundation +// SPDX-License-Identifier: LGPL-2.1-or-later + +// A map between namespaces and base URLs for their online documentation +baseURLs = [ + [ 'Gdk', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4/' ], + [ 'GdkWayland', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-wayland/' ], + [ 'GdkX11', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-x11/' ], + [ 'Gsk', 'https://gnome.pages.gitlab.gnome.org/gtk/gsk4/' ], + [ 'Gtk', 'https://gnome.pages.gitlab.gnome.org/gtk/gtk4/' ], + [ 'Pango', 'https://gnome.pages/gitlab.gnome.org/pango/pango/' ], + [ 'PangoCairo', 'https://gnome.pages.gitlab.gnome.org/pango/pangocairo/' ], +] diff --git a/docs/reference/gdk/version.xml.in b/docs/reference/gdk/version.xml.in deleted file mode 100644 index 3bb59ac105c26591aa3ac4ee9d344185fb263e20..0000000000000000000000000000000000000000 --- a/docs/reference/gdk/version.xml.in +++ /dev/null @@ -1 +0,0 @@ -@GTK_VERSION@ diff --git a/docs/reference/gdk/wayland.md b/docs/reference/gdk/wayland.md new file mode 100644 index 0000000000000000000000000000000000000000..040e96a4e9c68e68719826a5b907f277352cf919 --- /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 0000000000000000000000000000000000000000..6602e24b820ba076f60f0a89e9d3c3db2e1b8c75 --- /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/docs/reference/gsk/gsk4-docs.xml b/docs/reference/gsk/gsk4-docs.xml deleted file mode 100644 index 2bfecbf2903a700e6abe0f9dbd902ed6048d392c..0000000000000000000000000000000000000000 --- a/docs/reference/gsk/gsk4-docs.xml +++ /dev/null @@ -1,33 +0,0 @@ - - - -]> - - - GSK 4 Reference Manual - - This document is for the GSK 4 library, version &version; - The latest versions can be found online at - https://developer.gnome.org/gsk4/. - - - - - API Reference - - - - - - - - - Index of all symbols - - - - - - diff --git a/docs/reference/gsk/gsk4-sections.txt b/docs/reference/gsk/gsk4-sections.txt deleted file mode 100644 index e4a10930ae1ab6ec338be36698c5fbc6c7b0f327..0000000000000000000000000000000000000000 --- a/docs/reference/gsk/gsk4-sections.txt +++ /dev/null @@ -1,399 +0,0 @@ -
-GskRenderer -GskRenderer -gsk_renderer_get_surface -gsk_renderer_realize -gsk_renderer_unrealize -gsk_renderer_is_realized -gsk_renderer_render -gsk_renderer_render_texture - -gsk_renderer_new_for_surface -gsk_gl_renderer_new -gsk_cairo_renderer_new -gsk_vulkan_renderer_new -gsk_broadway_renderer_new - -GSK_IS_RENDERER -GSK_RENDERER -GSK_TYPE_RENDERER -GskRendererClass -gsk_renderer_get_type -GSK_TYPE_SCALING_FILTER -GSK_BROADWAY_RENDERER -GSK_BROADWAY_RENDERER_CLASS -GSK_BROADWAY_RENDERER_GET_CLASS -GSK_IS_BROADWAY_RENDERER -GSK_IS_BROADWAY_RENDERER_CLASS -GSK_TYPE_BROADWAY_RENDERER -GskBroadwayRenderer -GskBroadwayRendererClass -GSK_CAIRO_RENDERER -GSK_CAIRO_RENDERER_CLASS -GSK_CAIRO_RENDERER_GET_CLASS -GSK_IS_CAIRO_RENDERER -GSK_IS_CAIRO_RENDERER_CLASS -GSK_TYPE_CAIRO_RENDERER -GskCairoRenderer -GskCairoRendererClass -GSK_GL_RENDERER -GSK_GL_RENDERER_CLASS -GSK_GL_RENDERER_GET_CLASS -GSK_IS_GL_RENDERER -GSK_IS_GL_RENDERER_CLASS -GSK_TYPE_GL_RENDERER -GskGLRenderer -GskGLRendererClass -gsk_gl_renderer_get_type -GSK_VULKAN_RENDERER -GSK_VULKAN_RENDERER_CLASS -GSK_VULKAN_RENDERER_GET_CLASS -GSK_IS_VULKAN_RENDERER -GSK_IS_VULKAN_RENDERER_CLASS -GSK_TYPE_VULKAN_RENDERER -GskVulkanRenderer -GskVulkanRendererClass -gsk_vulkan_renderer_get_type -
- -
-GskRenderNode -GskRenderNode -GskBlendNode -GskBlurNode -GskBorderNode -GskCairoNode -GskClipNode -GskColorMatrixNode -GskColorNode -GskConicGradientNode -GskContainerNode -GskCrossFadeNode -GskDebugNode -GskInsetShadowNode -GskLinearGradientNode -GskRadialGradientNode -GskOpacityNode -GskOutsetShadowNode -GskRepeatingLinearGradientNode -GskRepeatingRadialGradientNode -GskRepeatNode -GskRoundedClipNode -GskShadowNode -GskTextNode -GskTextureNode -GskTransformNode -GskGLShaderNode -gsk_render_node_ref -gsk_render_node_unref -GskRenderNodeType -gsk_render_node_get_node_type -gsk_render_node_draw -GskSerializationError -GskParseErrorFunc -GskParseLocation -gsk_render_node_serialize -gsk_render_node_deserialize -gsk_render_node_write_to_file -GskScalingFilter -gsk_render_node_get_bounds - - -gsk_color_node_new -gsk_color_node_get_color -gsk_texture_node_new -gsk_texture_node_get_texture - -GskColorStop -gsk_linear_gradient_node_new -gsk_repeating_linear_gradient_node_new -gsk_linear_gradient_node_get_start -gsk_linear_gradient_node_get_end -gsk_linear_gradient_node_get_n_color_stops -gsk_linear_gradient_node_get_color_stops - -gsk_radial_gradient_node_new -gsk_repeating_radial_gradient_node_new -gsk_radial_gradient_node_get_n_color_stops -gsk_radial_gradient_node_get_color_stops -gsk_radial_gradient_node_get_start -gsk_radial_gradient_node_get_end -gsk_radial_gradient_node_get_hradius -gsk_radial_gradient_node_get_vradius -gsk_radial_gradient_node_get_center - -gsk_conic_gradient_node_new -gsk_conic_gradient_node_get_n_color_stops -gsk_conic_gradient_node_get_color_stops -gsk_conic_gradient_node_get_center -gsk_conic_gradient_node_get_rotation - -gsk_border_node_new -gsk_border_node_get_outline -gsk_border_node_get_widths -gsk_border_node_get_colors - -gsk_inset_shadow_node_new -gsk_inset_shadow_node_get_outline -gsk_inset_shadow_node_get_color -gsk_inset_shadow_node_get_dx -gsk_inset_shadow_node_get_dy -gsk_inset_shadow_node_get_spread -gsk_inset_shadow_node_get_blur_radius - -gsk_outset_shadow_node_new -gsk_outset_shadow_node_get_outline -gsk_outset_shadow_node_get_color -gsk_outset_shadow_node_get_dx -gsk_outset_shadow_node_get_dy -gsk_outset_shadow_node_get_spread -gsk_outset_shadow_node_get_blur_radius - -gsk_cairo_node_new -gsk_cairo_node_get_draw_context -gsk_cairo_node_get_surface - -gsk_container_node_new -gsk_container_node_get_n_children -gsk_container_node_get_child - -gsk_transform_node_new -gsk_transform_node_get_child -gsk_transform_node_get_transform - -gsk_opacity_node_new -gsk_opacity_node_get_child -gsk_opacity_node_get_opacity - -gsk_color_matrix_node_new -gsk_color_matrix_node_get_child -gsk_color_matrix_node_get_color_matrix -gsk_color_matrix_node_get_color_offset - -gsk_repeat_node_new -gsk_repeat_node_get_child -gsk_repeat_node_get_child_bounds - -gsk_clip_node_new -gsk_clip_node_get_child -gsk_clip_node_get_clip - -gsk_rounded_clip_node_new -gsk_rounded_clip_node_get_child -gsk_rounded_clip_node_get_clip - -GskShadow -gsk_shadow_node_new -gsk_shadow_node_get_shadow -gsk_shadow_node_get_n_shadows -gsk_shadow_node_get_child - -GskBlendMode -gsk_blend_node_new -gsk_blend_node_get_bottom_child -gsk_blend_node_get_top_child -gsk_blend_node_get_blend_mode - -gsk_cross_fade_node_new -gsk_cross_fade_node_get_start_child -gsk_cross_fade_node_get_end_child -gsk_cross_fade_node_get_progress - -gsk_text_node_new -gsk_text_node_get_font -gsk_text_node_get_glyphs -gsk_text_node_get_color -gsk_text_node_has_color_glyphs -gsk_text_node_get_num_glyphs -gsk_text_node_get_offset - -gsk_blur_node_new -gsk_blur_node_get_child -gsk_blur_node_get_radius - -gsk_debug_node_new -gsk_debug_node_get_child -gsk_debug_node_get_message - -gsk_gl_shader_node_new -gsk_gl_shader_node_get_n_children -gsk_gl_shader_node_get_child -gsk_gl_shader_node_get_args -gsk_gl_shader_node_get_shader - -GSK_IS_RENDER_NODE -GSK_RENDER_NODE -GSK_TYPE_RENDER_NODE -GSK_TYPE_BLEND_NODE -GSK_TYPE_BLUR_NODE -GSK_TYPE_BORDER_NODE -GSK_TYPE_CAIRO_NODE -GSK_TYPE_CLIP_NODE -GSK_TYPE_COLOR_MATRIX_NODE -GSK_TYPE_COLOR_NODE -GSK_TYPE_CONTAINER_NODE -GSK_TYPE_CONIC_GRADIENT_NODE -GSK_TYPE_CROSS_FADE_NODE -GSK_TYPE_DEBUG_NODE -GSK_TYPE_GL_SHADER_NODE -GSK_TYPE_INSET_SHADOW_NODE -GSK_TYPE_LINEAR_GRADIENT_NODE -GSK_TYPE_OPACITY_NODE -GSK_TYPE_OUTSET_SHADOW_NODE -GSK_TYPE_RADIAL_GRADIENT_NODE -GSK_TYPE_REPEATING_LINEAR_GRADIENT_NODE -GSK_TYPE_REPEATING_RADIAL_GRADIENT_NODE -GSK_TYPE_REPEAT_NODE -GSK_TYPE_ROUNDED_CLIP_NODE -GSK_TYPE_SHADOW_NODE -GSK_TYPE_TEXT_NODE -GSK_TYPE_TEXTURE_NODE -GSK_TYPE_TRANSFORM_NODE -GSK_TYPE_GLSHADER_NODE -GSK_TYPE_RENDER_NODE_TYPE -GskRenderNodeClass -gsk_blend_node_get_type -gsk_blur_node_get_type -gsk_border_node_get_type -gsk_broadway_renderer_get_type -gsk_cairo_node_get_type -gsk_cairo_renderer_get_type -gsk_clip_node_get_type -gsk_color_matrix_node_get_type -gsk_color_node_get_type -gsk_conic_gradient_node_get_type -gsk_container_node_get_type -gsk_cross_fade_node_get_type -gsk_debug_node_get_type -gsk_gl_shader_node_get_type -gsk_inset_shadow_node_get_type -gsk_linear_gradient_node_get_type -gsk_opacity_node_get_type -gsk_outset_shadow_node_get_type -gsk_radial_gradient_node_get_type -gsk_render_node_get_type -gsk_repeating_linear_gradient_node_get_type -gsk_repeating_radial_gradient_node_get_type -gsk_repeat_node_get_type -gsk_rounded_clip_node_get_type -gsk_shadow_node_get_type -gsk_text_node_get_type -gsk_texture_node_get_type -gsk_transform_node_get_type -GSK_TYPE_BLEND_MODE - -gsk_serialization_error_quark -GSK_SERIALIZATION_ERROR -GSK_TYPE_SERIALIZATION_ERROR -
- -
-GskRoundedRect -GskCorner -GskRoundedRect -GSK_ROUNDED_RECT_INIT -gsk_rounded_rect_init -gsk_rounded_rect_init_copy -gsk_rounded_rect_init_from_rect -gsk_rounded_rect_normalize -gsk_rounded_rect_offset -gsk_rounded_rect_shrink -gsk_rounded_rect_is_rectilinear -gsk_rounded_rect_contains_point -gsk_rounded_rect_contains_rect -gsk_rounded_rect_intersects_rect - -GSK_TYPE_CORNER -
- -
-GskTransform -GskTransform -gsk_transform_ref -gsk_transform_unref - -GskTransformCategory -gsk_transform_get_category - -gsk_transform_print -gsk_transform_to_string -gsk_transform_parse - -gsk_transform_to_matrix -gsk_transform_to_2d -gsk_transform_to_affine -gsk_transform_to_translate - -gsk_transform_transform -gsk_transform_invert -gsk_transform_matrix -gsk_transform_translate -gsk_transform_translate_3d -gsk_transform_rotate -gsk_transform_rotate_3d -gsk_transform_scale -gsk_transform_scale_3d -gsk_transform_perspective - -gsk_transform_equal - -gsk_transform_transform_bounds -gsk_transform_transform_point - -GSK_TYPE_TRANSFORM -GSK_TYPE_TRANSFORM_CATEGORY -gsk_transform_get_type -gsk_transform_new -
- -
-GskGLShader -GskGLShader -gsk_gl_shader_new_from_bytes -gsk_gl_shader_new_from_resource -gsk_gl_shader_compile -gsk_gl_shader_get_source -gsk_gl_shader_get_resource -gsk_gl_shader_get_n_textures -gsk_gl_shader_get_n_uniforms -gsk_gl_shader_get_uniform_name -gsk_gl_shader_find_uniform_by_name -GskGLUniformType -gsk_gl_shader_get_uniform_type -gsk_gl_shader_get_uniform_offset -gsk_gl_shader_get_args_size - - -gsk_gl_shader_get_arg_float -gsk_gl_shader_get_arg_int -gsk_gl_shader_get_arg_uint -gsk_gl_shader_get_arg_bool -gsk_gl_shader_get_arg_vec2 -gsk_gl_shader_get_arg_vec3 -gsk_gl_shader_get_arg_vec4 -gsk_gl_shader_format_args_va -gsk_gl_shader_format_args - - -GskShaderArgsBuilder - -gsk_shader_args_builder_new -gsk_shader_args_builder_to_args -gsk_shader_args_builder_free_to_args -gsk_shader_args_builder_unref -gsk_shader_args_builder_ref - -gsk_shader_args_builder_set_float -gsk_shader_args_builder_set_int -gsk_shader_args_builder_set_uint -gsk_shader_args_builder_set_bool -gsk_shader_args_builder_set_vec2 -gsk_shader_args_builder_set_vec3 -gsk_shader_args_builder_set_vec4 - - -GSK_TYPE_GL_SHADER -GSK_TYPE_GL_UNIFORM_TYPE -GSK_TYPE_SHADER_ARGS_BUILDER -gsk_shader_args_builder_get_type -
diff --git a/docs/reference/gsk/gsk4.toml.in b/docs/reference/gsk/gsk4.toml.in new file mode 100644 index 0000000000000000000000000000000000000000..44d11c9d9b308e9efef48e10c8dccdda43b2c8c7 --- /dev/null +++ b/docs/reference/gsk/gsk4.toml.in @@ -0,0 +1,46 @@ +[library] +version = "@version@" +browse_url = "https://gitlab.gnome.org/GNOME/gtk/" +repository_url = "https://gitlab.gnome.org/GNOME/gtk.git" +website_url = "https://www.gtk.org" +authors = "GTK Development Team" +logo_url = "gtk-logo.svg" +license = "GPL-2.1-or-later" +description = "The GTK toolkit" +dependencies = [ "GObject-2.0", "Graphene-1.0", "Pango-1.0", "Gdk-4.0" ] +devhelp = true +search_index = true + + [dependencies."GObject-2.0"] + name = "GObject" + description = "The base type system library" + docs_url = "https://developer.gnome.org/gobject/stable" + + [dependencies."Graphene-1.0"] + name = "Graphene" + description = "A thin layer of mathematical types for 3D libraries" + docs_url = "https://ebassi.github.io/graphene/docs" + + [dependencies."Pango-1.0"] + name = "Pango" + description = "Text shaping and rendering" + docs_url = "https://developer.gnome.org/pango/stable" + + [dependencies."Gdk-4.0"] + name = "GDK" + description = "The GTK windowing system abstraction" + docs_url = "../../Gdk/4.0/" + +[theme] +name = "basic" +show_index_summary = true +show_class_hierarchy = true + +[source-location] +base_url = "https://gitlab.gnome.org/GNOME/gtk/-/blob/master/" + +[extra] +content_images = [ + "gtk-logo.svg", +] +urlmap_file = "urlmap.js" diff --git a/docs/reference/gsk/gsk4.types b/docs/reference/gsk/gsk4.types deleted file mode 100644 index 94eeabf270f1620a573e115b4bbe8debfed4ac53..0000000000000000000000000000000000000000 --- a/docs/reference/gsk/gsk4.types +++ /dev/null @@ -1,3 +0,0 @@ -gsk_render_node_get_type -gsk_renderer_get_type -gsk_gl_shader_get_type diff --git a/docs/reference/gsk/gtk-logo.svg b/docs/reference/gsk/gtk-logo.svg new file mode 100644 index 0000000000000000000000000000000000000000..9edbe2da97d767814b289ffea337fc9034653d73 --- /dev/null +++ b/docs/reference/gsk/gtk-logo.svg @@ -0,0 +1,138 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + diff --git a/docs/reference/gsk/meson.build b/docs/reference/gsk/meson.build index bf54aa1dcbe0f4230c94747fed8d08eb81260748..1e34799280bab26ee3aeb1cd0bbb88ade7cc92c5 100644 --- a/docs/reference/gsk/meson.build +++ b/docs/reference/gsk/meson.build @@ -1,91 +1,22 @@ -private_headers = [ - 'gsk-autocleanup.h', - - 'gskcairoblurprivate.h', - 'gskcairorendererprivate.h', - 'gskdebugprivate.h', - 'gskdiffprivate.h', - 'gskglshaderprivate.h', - 'gskprivate.h', - 'gskprofilerprivate.h', - 'gskrendererprivate.h', - 'gskrendernodeprivate.h', - 'gskrendernodeparserprivate.h', - 'gskroundedrectprivate.h', - 'gsktransformprivate.h', - - # gsk/gl - 'glutilsprivate.h', - 'gskgldriverprivate.h', - 'gskglglyphcacheprivate.h', - 'gskgliconcacheprivate.h', - 'gskglimageprivate.h', - 'gskglnodesampleprivate.h', - 'gskglprofilerprivate.h', - 'gskglrendererprivate.h', - 'gskglrenderopsprivate.h', - 'gskglshaderbuilderprivate.h', - 'gskglshadowcacheprivate.h', - 'gskgltextureatlasprivate.h', - 'opbuffer.h', - 'stb_rect_pack.h', - - # gsk/vulkan - 'gskvulkanblendmodepipelineprivate.h', - 'gskvulkanblurpipelineprivate.h', - 'gskvulkanborderpipelineprivate.h', - 'gskvulkanboxshadowpipelineprivate.h', - 'gskvulkanbufferprivate.h', - 'gskvulkanclipprivate.h', - 'gskvulkancolorpipelineprivate.h', - 'gskvulkancolortextpipelineprivate.h', - 'gskvulkancommandpoolprivate.h', - 'gskvulkancrossfadepipelineprivate.h', - 'gskvulkaneffectpipelineprivate.h', - 'gskvulkanglyphcacheprivate.h', - 'gskvulkanimageprivate.h', - 'gskvulkanlineargradientpipelineprivate.h', - 'gskvulkanmemoryprivate.h', - 'gskvulkanpipelineprivate.h', - 'gskvulkanpushconstantsprivate.h', - 'gskvulkanrendererprivate.h', - 'gskvulkanrenderpassprivate.h', - 'gskvulkanrenderprivate.h', - 'gskvulkanshaderprivate.h', - 'gskvulkantextpipelineprivate.h', - 'gskvulkantexturepipelineprivate.h', -] - -images = [ -] +gsk4_toml = configure_file(input: 'gsk4.toml.in', output: 'gsk4.toml', configuration: toml_conf) if get_option('gtk_doc') - configure_file(input: 'version.xml.in', output: 'version.xml', configuration: version_conf) - - gnome.gtkdoc('gsk4', - mode: 'none', - main_xml: 'gsk4-docs.xml', - src_dir: [ - gskinc, - ], - dependencies: libgtk_dep, - gobject_typesfile: join_paths(meson.current_source_dir(), 'gsk4.types'), - scan_args: [ - '--ignore-decorators=_GDK_EXTERN', - '--ignore-headers=' + ' '.join(private_headers), - ], - mkdb_args: [ - '--ignore-files=' + ' '.join(private_headers), - ], - fixxref_args: [ - '--html-dir=@0@'.format(docpath), - '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')), - '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')), - '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')), - '--extra-dir=@0@'.format(cairo_docpath), - '--extra-dir=../gdk', + custom_target('gsk4-doc', + input: [ gsk4_toml, gsk_gir[0] ], + output: 'gsk4', + command: [ + gidocgen, + 'generate', + '--quiet', + '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'), + '--config=@INPUT0@', + '--output-dir=@OUTPUT@', + '--no-namespace-dir', + '--content-dir=@0@'.format(meson.current_source_dir()), + '@INPUT1@', ], - html_assets: images, - install: true, + depends: [ gdk_gir[0] ], + depend_files: [ expand_content_md_files ], + build_by_default: true, ) endif diff --git a/docs/reference/gsk/urlmap.js b/docs/reference/gsk/urlmap.js new file mode 100644 index 0000000000000000000000000000000000000000..eaf2de9886ce7c2b07624c98fefe7f4ea7756d8f --- /dev/null +++ b/docs/reference/gsk/urlmap.js @@ -0,0 +1,13 @@ +// SPDX-FileCopyrightText: 2021 GNOME Foundation +// SPDX-License-Identifier: LGPL-2.1-or-later + +// A map between namespaces and base URLs for their online documentation +baseURLs = [ + [ 'Gdk', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4/' ], + [ 'GdkWayland', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-wayland/' ], + [ 'GdkX11', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-x11/' ], + [ 'Gsk', 'https://gnome.pages.gitlab.gnome.org/gtk/gsk4/' ], + [ 'Gtk', 'https://gnome.pages.gitlab.gnome.org/gtk/gtk4/' ], + [ 'Pango', 'https://gnome.pages/gitlab.gnome.org/pango/pango/' ], + [ 'PangoCairo', 'https://gnome.pages.gitlab.gnome.org/pango/pangocairo/' ], +] diff --git a/docs/reference/gsk/version.xml.in b/docs/reference/gsk/version.xml.in deleted file mode 100644 index 3bb59ac105c26591aa3ac4ee9d344185fb263e20..0000000000000000000000000000000000000000 --- a/docs/reference/gsk/version.xml.in +++ /dev/null @@ -1 +0,0 @@ -@GTK_VERSION@ diff --git a/docs/reference/gtk/actions.md b/docs/reference/gtk/actions.md index 61433ccc19460eb1c09d5649ada1ad24bbef7e07..2482c5c0b98922485f8ddf0cc5ac2cb9decc9520 100644 --- a/docs/reference/gtk/actions.md +++ b/docs/reference/gtk/actions.md @@ -1,13 +1,14 @@ -# Overview of actions in GTK {#actions-overview} +Title: Overview of actions in GTK +Slug: actions This chapter describes in detail how GTK uses actions to connect activatable UI elements to callbacks. GTK inherits the underlying -architecture of GAction and GMe:u for describing abstract actions +architecture of `GAction` and `GMenu` for describing abstract actions and menus from the GIO library. ## Basics about actions -A GAction is essentially a way to tell the toolkit about a piece of +A `GAction` is essentially a way to tell the toolkit about a piece of functionality in your program, and to give it a name. Actions are purely functional. They do not contain any presentational @@ -76,7 +77,7 @@ state type, and activating them with a particular parameter value is equivalent to changing their state to that value. This approach to handling radio buttons is different than many other -action systems such as GtkAction. With GAction, there is only one action +action systems such as `GtkAction`. With `GAction`, there is only one action for "text-justify" and "left", "center" and "right" are possible states on that action. There are not three separate "justify-left", "justify-center" and "justify-right" actions. @@ -96,7 +97,7 @@ Even though toggle actions have a state, they do not have a parameter. Therefore, a target value is not needed when referring to them — they will always be toggled on activation. -Most APIs that allow using a GAction (such as GMenuModel and GtkActionable) +Most APIs that allow using a `GAction` (such as `GMenuModel` and `GtkActionable`) allow use of detailed action names. This is a convenient way of specifying an action name and an action target with a single string. @@ -140,7 +141,7 @@ separate state for each instance of the action as well as being able to control the enabled state of the action on a per-window basis. Actions are added to their relevant scope (application, window or widget) -either using the GActionMap interface, or by using +either using the `GActionMap` interface, or by using gtk_widget_insert_action_group(). Actions that will be the same for all instances of a widget class can be added globally using gtk_widget_class_install_action(). @@ -149,7 +150,7 @@ gtk_widget_class_install_action(). Actions rarely occurs in isolation. It is common to have groups of related actions, which are represented by instances of the -GActionGroup interface. +`GActionGroup` interface. Action maps are a variant of action groups that allow to change the name of the action as it is looked up. In GTK, the convention @@ -160,46 +161,46 @@ or "win." for those with window scope. When referring to actions on a GActionMap only the name of the action itself is used (ie: "quit", not "app.quit"). The "app.quit" form is only used when referring to actions from -places like a GMenu or GtkActionable widget where the scope +places like a `GMenu` or `GtkActionable` widget where the scope of the action is not already known. -GtkApplication and GtkApplicationWindow implement the GActionMap +`GtkApplication` and `GtkApplicationWindow` implement the `GActionMap` interface, so you can just add actions directly to them. For other widgets, use gtk_widget_insert_action_group() to add actions to it. If you want to insert several actions at the same time, it is -typically faster and easier to use GActionEntry. +typically faster and easier to use `GActionEntry`. ## Connecting actions to widgets -Any widget that implements the GtkActionable interface can +Any widget that implements the `GtkActionable` interface can be connected to an action just by setting the ::action-name property. If the action has a parameter, you will also need -to set the ::action-target property. -Widgets that implement GtkActionable include GtkSwitch, GtkButton, -and their respective subclasses. +to set the ::action-target property. Widgets that implement +`GtkActionable` include `GtkSwitch`, `GtkButton`, and their +respective subclasses. Another way of obtaining widgets that are connected to actions -is to create a menu using a GMenu menu model. GMenu provides an +is to create a menu using a `GMenu` menu model. `GMenu` provides an abstract way to describe typical menus: nested groups of items where each item can have a label, and icon, and an action. -A typical use of GMenu inside GTK is to set up an application +A typical use of `GMenu` inside GTK is to set up an application menubar with gtk_application_set_menubar(). Another, maybe more common use is to create a popover for a menubutton, using gtk_menu_button_set_menu_model(). Unlike traditional menus, those created from menu models don't have keyboard accelerators associated with menu items. Instead, -GtkApplication offers the gtk_application_set_accels_for_action() +`GtkApplication` offers the gtk_application_set_accels_for_action() API to associate keyboard shortcuts with actions. ## Activation When a widget with a connected action is activated, GTK finds the action to activate by walking up the widget hierarchy, -looking for a matching action, ending up at the GtkApplication. +looking for a matching action, ending up at the `GtkApplication`. ## Built-in Actions @@ -209,13 +210,16 @@ you should avoid naming conflicts with them when creating your own actions. default.activate - : Activates the default widget in a context (typically a GtkWindow, - GtkDialog or GtkPopover) +: Activates the default widget in a context (typically a `GtkWindow`, + `GtkDialog` or `GtkPopover`) + clipboard.cut, clipboard.copy, clipboard.paste - : Clipboard operations on entries, text view and labels, typically - used in the context menu +: Clipboard operations on entries, text view and labels, typically + used in the context menu + selection.delete, selection.select-all - : Selection operations on entries, text view and labels +: Selection operations on entries, text view and labels + color.select, color.customize: - : Operate on colors in a #GtkColorChooserWidget. These actions are - unusual in that they have the non-trivial parameter type (dddd): +: Operate on colors in a `GtkColorChooserWidget`. These actions are + unusual in that they have the non-trivial parameter type (dddd): diff --git a/docs/reference/gtk/broadway.md b/docs/reference/gtk/broadway.md index 53d6d3d33454ae6a9eb65604ec93dacce6259022..8bf24c43c1d593f037b7ab8ee67bc5f098c614f7 100644 --- a/docs/reference/gtk/broadway.md +++ b/docs/reference/gtk/broadway.md @@ -1,4 +1,7 @@ -# Using GTK with Broadway {#gtk-broadway} +Title: The Broadway windowing system +Slug: broadway + +## Using GTK with Broadway The GDK Broadway backend provides support for displaying GTK applications in a web browser, using HTML5 and web sockets. To run @@ -26,9 +29,9 @@ Start your applications like this: GDK_BACKEND=broadway BROADWAY_DISPLAY=:5 gtk4-demo ``` -## Broadway-specific environment variables {#broadway-envar} +## Broadway-specific environment variables -### BROADWAY_DISPLAY +### BROADWAY\_DISPLAY Specifies the Broadway display number. The default display is 0. The display number determines the port to use when connecting diff --git a/docs/reference/gtk/building.md b/docs/reference/gtk/building.md index 51c8802168653b517513eced3b65f7c7b8745b8d..31073d1d049a944aba33dcd06f2b3f5964d32c6a 100644 --- a/docs/reference/gtk/building.md +++ b/docs/reference/gtk/building.md @@ -1,4 +1,5 @@ -# Compiling the GTK Libraries {#gtk-building} +Title: Compiling the GTK Libraries +Slug: gtk-building ## Building GTK @@ -75,7 +76,7 @@ PATH="/opt/gtk/bin:$PATH" export LD_LIBRARY_PATH PATH ``` -## Build types {#build-types} +## Build types Meson has different build types, exposed by the `buildtype` configuration option. GTK enables and disables functionality @@ -111,7 +112,7 @@ linker flags. Note that with the plain build type, you are also responsible for controlling the debugging features of GTK with `-DG_ENABLE_DEBUG` and `-DG_DISABLE_CAST_CHECKS`. -## Dependencies {#dependencies} +## Dependencies Before you can compile the GTK widget toolkit, you need to have various other tools and libraries installed on your @@ -179,7 +180,7 @@ Other libraries are maintained separately. `XDG_DATA_DIRS` set accordingly at configure time. Otherwise, gdk-pixbuf falls back to its built-in mime type detection. -## Building and testing GTK {#building} +## Building and testing GTK First make sure that you have the necessary external dependencies installed: `pkg-config`, Meson, Ninja, @@ -207,7 +208,7 @@ log that can help you understand the issue you're encountering. If all else fails, you can ask for help on the [GTK forums](#gtk-resources). -## Extra Configuration Options {#extra-configuration-options} +## Extra Configuration Options In addition to the normal options provided by Meson, GTK defines various arguments that modify what should be built. All of these options are passed diff --git a/docs/reference/gtk/compiling.md b/docs/reference/gtk/compiling.md index 1cceedded1761e69799e8d834edf1390aeb71fd4..f73207d446fcc025ae85acbfe8764ea57e3aa245 100644 --- a/docs/reference/gtk/compiling.md +++ b/docs/reference/gtk/compiling.md @@ -1,4 +1,5 @@ -# Compiling GTK Applications on UNIX {#gtk-compiling} +Title: Compiling GTK Applications on UNIX +Slug: gtk-compiling To compile a GTK application, you need to tell the compiler where to find the GTK header files and libraries. This is done with the diff --git a/docs/reference/gtk/css-overview.md b/docs/reference/gtk/css-overview.md index 0070c7e4f3b1e769280d124c44db7d8c44635092..a9518dd428c5273ff15938ce5d1dd7bc99d8a9af 100644 --- a/docs/reference/gtk/css-overview.md +++ b/docs/reference/gtk/css-overview.md @@ -1,4 +1,5 @@ -# CSS in GTK {#css} +Title: CSS in GTK +Slug: css This chapter describes how GTK uses CSS for styling and layout. It is not meant to be an explanation of CSS from first principles, diff --git a/docs/reference/gtk/css-properties.md b/docs/reference/gtk/css-properties.md index 8fa9819fc7e56ba4320ebeedd5a3ff64a2d74b9b..d09141a3956360c2f113db20897df73c2a595048 100644 --- a/docs/reference/gtk/css-properties.md +++ b/docs/reference/gtk/css-properties.md @@ -1,4 +1,5 @@ -# GTK CSS Properties +Title: GTK CSS Properties +Slug: css-properties GTK supports CSS properties and shorthands as far as they can be applied in the context of widgets, and adds its own properties only when needed. @@ -14,13 +15,16 @@ spec. The following units are supported for basic datatypes: Length - : px, pt, em, ex, rem, pc, in, cm, mm, calc() +: px, pt, em, ex, rem, pc, in, cm, mm, calc() + Percentage - : %, calc() +: %, calc() + Angle - : deg, grad, turn, calc() +: deg, grad, turn, calc() + Time - : s, ms, calc() +: s, ms, calc() Length values with the em or ex units are resolved using the font size value, unless they occur in setting the font-size itself, in @@ -41,13 +45,16 @@ side of an area. In this case, the specified values are interpreted as follows: 4 values: - : top right bottom left +: top right bottom left + 3 values: - : top horizontal bottom +: top horizontal bottom + 2 values: - : vertical horizontal +: vertical horizontal + 1 value: - : all +: all ## Colors diff --git a/docs/reference/gtk/drawing-model.md b/docs/reference/gtk/drawing-model.md index fb3ad74690f1342bd5d505852c100a7f11661230..0921989842338bb36411caff92ac523fed6fc4d5 100644 --- a/docs/reference/gtk/drawing-model.md +++ b/docs/reference/gtk/drawing-model.md @@ -1,13 +1,14 @@ -# Overview of the drawing model {#drawing-overview} +Title: Overview of the drawing model +Slug: drawing-overview -This chapter describes the GTK drawing model in detail. If you +This chapter describes the GTK drawing model in detail. If you are interested in the procedure which GTK follows to draw its widgets and windows, you should read this chapter; this will be -useful to know if you decide to implement your own widgets. This +useful to know if you decide to implement your own widgets. This chapter will also clarify the reasons behind the ways certain things are done in GTK. -## Windows and events {#drawing-windows} +## Windows and events Applications that use a windowing system generally create rectangular regions in the screen called _surfaces_ (GTK is @@ -27,14 +28,14 @@ windowing system surface. Child widgets such as buttons or entries don't have their own surface; they use the surface of their toplevel. -Generally, the drawing cycle begins when GTK receives -a frame event from the underlying windowing system: if the -user drags a window over another one, the windowing system will -tell the underlying surface that it needs to repaint itself. The -drawing cycle can also be initiated when a widget itself decides -that it needs to update its display. For example, when the user -types a character in an entry widget, the entry asks GTK to queue -a redraw operation for itself. +Generally, the drawing cycle begins when GTK receives a frame event +from the underlying windowing system: if the user drags a window +over another one, the windowing system will tell the underlying +surface that it needs to repaint itself. The drawing cycle can +also be initiated when a widget itself decides that it needs to +update its display. For example, when the user types a character +in an entry widget, the entry asks GTK to queue a redraw operation +for itself. The windowing system generates frame events for surfaces. The GDK interface to the windowing system translates such events into @@ -46,7 +47,7 @@ need to be repainted in response to such events, and how widgets work internally in terms of the resources they use from the windowing system. -## The frame clock {#frameclock} +## The frame clock All GTK applications are mainloop-driven, which means that most of the time the app is idle inside a loop that just waits for @@ -112,7 +113,7 @@ happen at higher levels: There are also a lot of implicit triggers of these from the CSS layer (which does animations, resizes and repaints as needed). -## The scene graph {#scene-graph} +## The scene graph The first step in “drawing” a window is that GTK creates _render nodes_ for all the widgets in the window. The render @@ -133,15 +134,15 @@ rendering commands for the drawing API it targets, and arranges for the resulting drawing to be associated with the right surface. GSK has renderers for OpenGL, Vulkan and cairo. -## Hierarchical drawing {#hierarchical-drawing} +## Hierarchical drawing -During the Paint phase GTK receives a single #GdkSurface::render -signal on the toplevel surface. The signal handler will create a -snapshot object (which is a helper for creating a scene graph) and -call the #GtkWidget::snapshot() vfunc, which will propagate down -the widget hierarchy. This lets each widget snapshot its content -at the right place and time, correctly handling things like partial -transparencies and overlapping widgets. +During the Paint phase GTK receives a single ::render signal on the +toplevel surface. The signal handler will create a snapshot object +(which is a helper for creating a scene graph) and call the +GtkWidget snapshot() vfunc, which will propagate down the widget +hierarchy. This lets each widget snapshot its content at the right +place and time, correctly handling things like partial transparencies +and overlapping widgets. During the snapshotting of each widget, GTK automatically handles the CSS rendering according to the CSS box model. It snapshots first diff --git a/docs/reference/gtk/getting_started.md b/docs/reference/gtk/getting_started.md index 3196bef7024bfcd0d84cb57965e4bab62430cebf..9daba55a232567c5a6e5ea3c198e220ac77e1163 100644 --- a/docs/reference/gtk/getting_started.md +++ b/docs/reference/gtk/getting_started.md @@ -1,4 +1,5 @@ -# Getting Started with GTK {#gtk-getting-started} +Title: Getting Started with GTK +Slug: gtk-getting-started GTK is a [widget toolkit](http://en.wikipedia.org/wiki/Widget_toolkit). Each user interface created by GTK consists of widgets. This is implemented @@ -29,7 +30,7 @@ window. Create a new file with the following content named `example-0.c`. -``` {.c source=examples/window-default.c } +```c #include static void @@ -63,7 +64,7 @@ main (int argc, You can compile the program above with GCC using: ``` -gcc `pkg-config --cflags gtk4` -o example-0 example-0.c `pkg-config --libs gtk4` +gcc $( pkg-config --cflags gtk4 ) -o example-0 example-0.c $( pkg-config --libs gtk4 ) ``` For more information on how to compile a GTK application, please @@ -77,49 +78,51 @@ Even if GTK installs multiple header files, only the top-level `gtk/gtk.h` header can be directly included by third-party code. The compiler will abort with an error if any other header is directly included. -In a GTK application, the purpose of the main() function is to create a -GtkApplication object and run it. In this example a GtkApplication pointer -named `app` is declared and then initialized using gtk_application_new(). +In a GTK application, the purpose of the `main()` function is to create a +[class@Gtk.Application] object and run it. In this example a +[class@Gtk.Application] pointer named `app` is declared and then initialized +using `gtk_application_new()`. -When creating a GtkApplication, you need to pick an application identifier -(a name) and pass it to gtk_application_new() as parameter. For this example -`org.gtk.example` is used. For choosing an identifier for your application, see -[this guide](https://wiki.gnome.org/HowDoI/ChooseApplicationID). Lastly, -gtk_application_new() takes GApplicationFlags as input for your application, -if your application would have special needs. +When creating a [class@Gtk.Application], you need to pick an application +identifier (a name) and pass it to [ctor@Gtk.Application.new] as parameter. For +this example `org.gtk.example` is used. For choosing an identifier for your +application, see [this guide](https://wiki.gnome.org/HowDoI/ChooseApplicationID). +Lastly, [ctor@Gtk.Application.new] takes `GApplicationFlags` as input +for your application, if your application would have special needs. Next the [activate signal](https://wiki.gnome.org/HowDoI/GtkApplication) is -connected to the activate() function above the main() function. The `activate` -signal will be emitted when your application is launched with g_application_run() -on the line below. The g_application_run() call also takes as arguments the +connected to the activate() function above the `main()` function. The `activate` +signal will be emitted when your application is launched with `g_application_run()` +on the line below. The `g_application_run()` call also takes as arguments the command line arguments (the `argc` count and the `argv` string array). Your application can override the command line handling, e.g. to open files passed on the commandline. -Within g_application_run() the activate signal is sent and we then proceed +Within `g_application_run()` the activate signal is sent and we then proceed into the activate() function of the application. This is where we construct our GTK window, so that a window is shown when the application is launched. -The call to gtk_application_window_new() will create a new GtkWindow and -store it inside the `window` pointer. The window will have a frame, a title -bar, and window controls depending on the platform. - -A window title is set using gtk_window_set_title(). This function takes a -GtkWindow* pointer and a string as input. As our `window` pointer is a -GtkWidget pointer, we need to cast it to GtkWindow*. But instead of casting -`window` via `(GtkWindow*)`, `window` can be cast using the macro -`GTK_WINDOW()`. `GTK_WINDOW()` will check if the pointer is an instance of -the GtkWindow class, before casting, and emit a warning if the check fails. -More information about this convention can be found -[here](https://developer.gnome.org/gobject/stable/gtype-conventions.html). - -Finally the window size is set using gtk_window_set_default_size() -and the window is then shown by GTK via gtk_widget_show(). - -When you close the window, by for example pressing the X, the g_application_run() -call returns with a number which is saved inside an integer variable named -`status`. Afterwards, the GtkApplication object is freed from memory with -g_object_unref(). Finally the status integer is returned and the application -exits. +The call to [ctor@Gtk.ApplicationWindow.new] will create a new +[class@Gtk.ApplicationWindow] and store it inside the `window` pointer. The +window will have a frame, a title bar, and window controls depending on the +platform. + +A window title is set using [`method@Gtk.Window.set_title`]. This function +takes a `GtkWindow` pointer and a string as input. As our `window` pointer +is a `GtkWidget` pointer, we need to cast it to `GtkWindow`; instead of +casting `window` via a typical C cast like `(GtkWindow*)`, `window` can be +cast using the macro `GTK_WINDOW()`. `GTK_WINDOW()` will check if the +pointer is an instance of the `GtkWindow` class, before casting, and emit a +warning if the check fails. More information about this convention can be +found [here](https://developer.gnome.org/gobject/stable/gtype-conventions.html). + +Finally the window size is set using [`method@Gtk.Window.set_default_size`] +and the window is then shown by GTK via [method@Gtk.Widget.show]. + +When you close the window, by (for example) pressing the X button, the +`g_application_run()` call returns with a number which is saved inside an +integer variable named `status`. Afterwards, the `GtkApplication` object is +freed from memory with `g_object_unref()`. Finally the status integer is +returned and the application exits. While the program is running, GTK is receiving _events_. These are typically input events caused by the user interacting with your program, but also things @@ -138,11 +141,11 @@ this example is called *Hello, World*. ![Hello, world](hello-world.png) -### Hello World in C {#gtk-getting-started-hello-world} +### Hello World in C Create a new file with the following content named `example-1.c`. -``` {.c source=examples/hello-world.c } +```c #include static void @@ -195,43 +198,44 @@ main (int argc, You can compile the program above with GCC using: ``` -gcc `pkg-config --cflags gtk4` -o example-1 example-1.c `pkg-config --libs gtk4` +gcc $( pkg-config --cflags gtk4 ) -o example-1 example-1.c $( pkg-config --libs gtk4 ) ``` -As seen above, example-1.c builds further upon example-0.c by adding a -button to our window, with the label "Hello World". Two new GtkWidget +As seen above, `example-1.c` builds further upon `example-0.c` by adding a +button to our window, with the label "Hello World". Two new `GtkWidget` pointers are declared to accomplish this, `button` and `box`. The box -variable is created to store a GtkBox, which is GTK's way of controlling -the size and layout of buttons. +variable is created to store a [class@Gtk.Box], which is GTK's way of +controlling the size and layout of buttons. -The GtkBox is created with gtk_box_new() which takes a GtkOrientation -enum as parameter. The buttons which this box will contain can either be laid -out horizontally or vertically. This does not matter in this particular case, -as we are dealing with only one button. After initializing box with the newly -created GtkBox, the code adds the box widget to the window widget using -gtk_window_set_child(). +The `GtkBox` widget is created with [ctor@Gtk.Box.new], which takes a +[enum@Gtk.Orientation] enumeration value as parameter. The buttons which +this box will contain can either be laid out horizontally or vertically. +This does not matter in this particular case, as we are dealing with only +one button. After initializing box with the newly created `GtkBox`, the code +adds the box widget to the window widget using [`method@Gtk.Window.set_child`]. Next the `button` variable is initialized in similar manner. -gtk_button_new_with_label() is called which returns a GtkButton to be -stored in `button`. Afterwards `button` is added to our `box`. - -Using g_signal_connect(), the button is connected to a function in our app called -print_hello(), so that when the button is clicked, GTK will call this function. -As the print_hello() function does not use any data as input, NULL is passed -to it. print_hello() calls g_print() with the string "Hello World" which will +[`ctor@Gtk.Button.new_with_label`] is called which returns a +[class@Gtk.Button] to be stored in `button`. Afterwards `button` is added to +our `box`. + +Using `g_signal_connect()`, the button is connected to a function in our app called +`print_hello()`, so that when the button is clicked, GTK will call this function. +As the `print_hello()` function does not use any data as input, `NULL` is passed +to it. `print_hello()` calls `g_print()` with the string "Hello World" which will print Hello World in a terminal if the GTK application was started from one. -After connecting print_hello(), another signal is connected to the "clicked" -state of the button using g_signal_connect_swapped(). This functions is similar -to a g_signal_connect() with the difference lying in how the callback function -is treated. g_signal_connect_swapped() allows you to specify what the callback +After connecting `print_hello()`, another signal is connected to the "clicked" +state of the button using `g_signal_connect_swapped()`. This functions is similar +to a `g_signal_connect()`, with the difference lying in how the callback function +is treated; `g_signal_connect_swapped()` allows you to specify what the callback function should take as parameter by letting you pass it as data. In this case -the function being called back is gtk_window_destroy() and the `window` pointer +the function being called back is [method@Gtk.Window.destroy] and the `window` pointer is passed to it. This has the effect that when the button is clicked, the whole -GTK window is destroyed. In contrast if a normal g_signal_connect() were used -to connect the "clicked" signal with gtk_window_destroy(), then the function +GTK window is destroyed. In contrast if a normal `g_signal_connect()` were used +to connect the "clicked" signal with [method@Gtk.Window.destroy], then the function would be called on `button` (which would not go well, since the function expects -a GtkWindow as argument). +a `GtkWindow` as argument). More information about creating buttons can be found [here](https://wiki.gnome.org/HowDoI/Buttons). @@ -255,11 +259,11 @@ arrange several buttons: ![Grid packing](grid-packing.png) -### Packing buttons {#gtk-getting-started-grid-packing} +### Packing buttons Create a new file with the following content named `example-2.c`. -``` {.c source=examples/grid-packing.c } +```c #include static void @@ -334,7 +338,7 @@ main (int argc, You can compile the program above with GCC using: ``` -gcc `pkg-config --cflags gtk4` -o example-2 example-2.c `pkg-config --libs gtk4` +gcc $( pkg-config --cflags gtk4 ) -o example-2 example-2.c $( pkg-config --libs gtk4 ) ``` ## Custom Drawing @@ -342,14 +346,14 @@ gcc `pkg-config --cflags gtk4` -o example-2 example-2.c `pkg-config --libs gtk4` Many widgets, like buttons, do all their drawing themselves. You just tell them the label you want to see, and they figure out what font to use, draw the button outline and focus rectangle, etc. Sometimes, it is necessary to -do some custom drawing. In that case, a GtkDrawingArea might be the right +do some custom drawing. In that case, a [class@Gtk.DrawingArea] might be the right widget to use. It offers a canvas on which you can draw by setting its draw function. -The contents of a widget often need to be partially or fully redrawn, -e.g. when another window is moved and uncovers part of the widget, or -when the window containing it is resized. It is also possible to explicitly -cause a widget to be redrawn, by calling gtk_widget_queue_draw(). GTK takes +The contents of a widget often need to be partially or fully redrawn, e.g. +when another window is moved and uncovers part of the widget, or when the +window containing it is resized. It is also possible to explicitly cause a +widget to be redrawn, by calling [`method@Gtk.Widget.queue_draw`]. GTK takes care of most of the details by providing a ready-to-use cairo context to the draw function. @@ -359,11 +363,11 @@ demonstrates input event handling with event controllers. ![Drawing](drawing.png) -### Drawing in response to input {#gtk-getting-started-drawing} +### Drawing in response to input Create a new file with the following content named `example-4.c`. -``` {.c source=examples/drawing.c } +```c #include /* Surface to store current scribbles */ @@ -556,7 +560,7 @@ main (int argc, You can compile the program above with GCC using: ``` -gcc `pkg-config --cflags gtk4` -o example-4 example-4.c `pkg-config --libs gtk4` +gcc $( pkg-config --cflags gtk4 ) -o example-4 example-4.c $( pkg-config --libs gtk4 ) ``` ## Building user interfaces @@ -567,13 +571,13 @@ cumbersome, and making changes becomes next to impossible. Thankfully, GTK supports the separation of user interface layout from your business logic, by using UI descriptions in an -XML format that can be parsed by the GtkBuilder class. +XML format that can be parsed by the [class@Gtk.Builder] class. ### Packing buttons with GtkBuilder Create a new file with the following content named `example-3.c`. -``` {.c source=examples/builder.c } +```c #include #include @@ -637,7 +641,7 @@ main (int argc, Create a new file with the following content named `builder.ui`. -``` {.xml source=examples/builder.ui } +```xml @@ -681,24 +685,24 @@ Create a new file with the following content named `builder.ui`. You can compile the program above with GCC using: ``` -gcc `pkg-config --cflags gtk4` -o example-3 example-3.c `pkg-config --libs gtk4` +gcc $( pkg-config --cflags gtk4 ) -o example-3 example-3.c $( pkg-config --libs gtk4 ) ``` -Note that GtkBuilder can also be used to construct objects that are +Note that `GtkBuilder` can also be used to construct objects that are not widgets, such as tree models, adjustments, etc. That is the reason -the method we use here is called gtk_builder_get_object() and returns -a GObject* instead of a GtkWidget*. +the method we use here is called [`method@Gtk.Builder.get_object`] and returns +a `GObject` instead of a `GtkWidget`. -Normally, you would pass a full path to gtk_builder_add_from_file() to +Normally, you would pass a full path to [`method@Gtk.Builder.add_from_file`] to make the execution of your program independent of the current directory. A common location to install UI descriptions and similar data is `/usr/share/appname`. It is also possible to embed the UI description in the source code as a -string and use gtk_builder_add_from_string() to load it. But keeping the +string and use [`method@Gtk.Builder.add_from_string`] to load it. But keeping the UI description in a separate file has several advantages: It is then possible to make minor adjustments to the UI without recompiling your program, and, -more importantly, graphical UI editors such as [glade](http://glade.gnome.org) +more importantly, graphical UI editors such as [Glade](http://glade.gnome.org) can load the file and allow you to create and modify your UI by point-and-click. ## Building applications @@ -707,41 +711,45 @@ An application consists of a number of files: The binary : This gets installed in `/usr/bin`. + A desktop file : The desktop file provides important information about the application to the desktop shell, such as its name, icon, D-Bus name, commandline to launch it, etc. It is installed in `/usr/share/applications`. + An icon : The icon gets installed in `/usr/share/icons/hicolor/48x48/apps`, where it -will be found regardless of the current theme. + will be found regardless of the current theme. + A settings schema : If the application uses GSettings, it will install its schema in - `/usr/share/glib-2.0/schemas`, so that tools like dconf-editor can find it. + `/usr/share/glib-2.0/schemas`, so that tools like dconf-editor can find it. + Other resources : Other files, such as GtkBuilder ui files, are best loaded from resources stored in the application binary itself. This eliminates the need for most of the files that would traditionally be installed in an application-specific location in `/usr/share`. -GTK includes application support that is built on top of GApplication. In this +GTK includes application support that is built on top of `GApplication`. In this tutorial we'll build a simple application by starting from scratch, adding more -and more pieces over time. Along the way, we'll learn about GtkApplication, -templates, resources, application menus, settings, GtkHeaderBar, GtkStack, -GtkSearchBar, GtkListBox, and more. +and more pieces over time. Along the way, we'll learn about [class@Gtk.Application], +templates, resources, application menus, settings, [class@Gtk.HeaderBar], [class@Gtk.Stack], +[class@Gtk.SearchBar], [class@Gtk.ListBox], and more. -The full, buildable sources for these examples can be found in the `examples/` -directory of the GTK source distribution, or -[online](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples) in the GTK git -repository. You can build each example separately by using make with the -`Makefile.example` file. For more information, see the `README` included in the -examples directory. +The full, buildable sources for these examples can be found in the +`examples` directory of the GTK source distribution, or +[online](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples) in the GTK +source code repository. You can build each example separately by using make +with the `Makefile.example` file. For more information, see the `README` +included in the examples directory. ### A trivial application -When using GtkApplication, the main() function can be very simple. We just call -g_application_run() and give it an instance of our application class. +When using `GtkApplication`, the `main()` function can be very simple. We just call +`g_application_run()` and give it an instance of our application class. -``` {.c source=examples/application1/main.c } +```c #include #include "exampleapp.h" @@ -758,15 +766,15 @@ GtkApplication. Our example does not yet have any interesting functionality. All it does is open a window when it is activated without arguments, and open the files it is given, if it is started with arguments. -To handle these two cases, we override the activate() vfunc, which gets called -when the application is launched without commandline arguments, and the open() -vfunc, which gets called when the application is launched with commandline -arguments. +To handle these two cases, we override the activate() vfunc, which gets +called when the application is launched without commandline arguments, and +the `open()` virtual function, which gets called when the application is +launched with commandline arguments. -To learn more about GApplication entry points, consult the GIO -[documentation](https://developer.gnome.org/gio/2.36/GApplication.html#GApplication.description). +To learn more about `GApplication` entry points, consult the GIO +[documentation](https://developer.gnome.org/gio/stable/GApplication.html#GApplication.description). -``` {.c source=examples/application1/exampleapp.c } +```c #include #include "exampleapp.h" @@ -833,10 +841,10 @@ example_app_new (void) ``` Another important class that is part of the application support in GTK is -GtkApplicationWindow. It is typically subclassed as well. Our subclass does +`GtkApplicationWindow`. It is typically subclassed as well. Our subclass does not do anything yet, so we will just get an empty window. -``` {.c source=examples/application1/examplewin.c } +```c #include #include "exampleapp.h" @@ -877,7 +885,7 @@ create an icon and a desktop file. ![An icon](exampleapp.png) -``` { source=examples/application1/org.gtk.exampleapp.desktop } +``` [Desktop Entry] Type=Application Name=Example @@ -905,7 +913,7 @@ GtkBuilder ui file with our application window class. Our simple ui file gives the window a title, and puts a GtkStack widget as the main content. -``` { .xml source=examples/application2/window.ui } +```xml