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