AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-11-10 02:40:11 +00:00
Code Issues Projects Releases Wiki Activity

gdk: Some more tweaks of the docs

Browse Source
This commit is contained in:
Matthias Clasen 2021-02-21 09:19:37 -05:00 committed by Emmanuele Bassi
parent e82d090bf5
commit a9dd352986
9 changed files with 199 additions and 190 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
gdk/gdkcairo.c
View File

@ -281,13 +281,13 @@ _gdk_cairo_surface_extents (cairo_surface_t *surface,
* gdk_cairo_region_create_from_surface: * gdk_cairo_region_create_from_surface:
* @surface: a cairo surface * @surface: a cairo surface
* *
* Creates region that describes covers the area where the given * Creates region that covers the area where the given
* @surface is more than 50% opaque. * @surface is more than 50% opaque.
* *
* This function takes into account device offsets that might be * This function takes into account device offsets that might be
* set with cairo_surface_set_device_offset(). * set with cairo_surface_set_device_offset().
* *
* Returns: A #cairo_region_t; must be freed with cairo_region_destroy() * Returns: A `cairo_region_t`; must be freed with cairo_region_destroy()
*/ */
cairo_region_t * cairo_region_t *
gdk_cairo_region_create_from_surface (cairo_surface_t *surface) gdk_cairo_region_create_from_surface (cairo_surface_t *surface)

5
gdk/gdkdevicepad.c
View File

@ -21,8 +21,9 @@
* GdkDevicePad: * GdkDevicePad:
* *
* `GdkDevicePad` is an interface implemented by devices of type * `GdkDevicePad` is an interface implemented by devices of type
* %GDK_SOURCE_TABLET_PAD, it allows querying the features provided * %GDK_SOURCE_TABLET_PAD
* by the pad device. *
* It allows querying the features provided by the pad device.
* *
* Tablet pads may contain one or more groups, each containing a subset * Tablet pads may contain one or more groups, each containing a subset
* of the buttons/rings/strips available. [method@Gdk.DevicePad.get_n_groups] * of the buttons/rings/strips available. [method@Gdk.DevicePad.get_n_groups]

257
gdk/gdkdisplay.c
View File

@ -39,30 +39,24 @@
#include <glib.h> #include <glib.h>
/** /**
* SECTION:gdkdisplay * GdkDisplay:
* @Short_description: Controls a set of monitors and their associated input devices
* @Title: GdkDisplay
* *
* GdkDisplay objects are the GDK representation of a workstation. * `GdkDisplay` objects are the GDK representation of a workstation.
* *
* Their purpose are two-fold: * Their purpose are two-fold:
*
* - To manage and provide information about input devices (pointers, keyboards, etc) * - To manage and provide information about input devices (pointers, keyboards, etc)
* - To manage and provide information about output devices (monitors, projectors, etc) * - To manage and provide information about output devices (monitors, projectors, etc)
* *
* Most of the input device handling has been factored out into separate #GdkSeat * Most of the input device handling has been factored out into separate
* objects. Every display has a one or more seats, which can be accessed with * [class@Gdk.Seat] objects. Every display has a one or more seats, which
* gdk_display_get_default_seat() and gdk_display_list_seats(). * can be accessed with [method@Gdk.Display.get_default_seat] and
* [method@Gdk.Display.list_seats].
* *
* Output devices are represented by #GdkMonitor objects, which can be accessed * Output devices are represented by [class@Gdk.Monitor] objects, which can
* with gdk_display_get_monitor_at_surface() and similar APIs. * be accessed with [method@Gdk.Display.get_monitor_at_surface] and similar APIs.
*/ */
/**
* GdkDisplay:
*
* The GdkDisplay struct contains only private fields and should not
* be accessed directly.
*/
enum enum
{ {
PROP_0, PROP_0,
@ -158,7 +152,8 @@ gdk_display_class_init (GdkDisplayClass *class)
* GdkDisplay:composited: * GdkDisplay:composited:
* *
* %TRUE if the display properly composites the alpha channel. * %TRUE if the display properly composites the alpha channel.
* See gdk_display_is_composited() for details. *
* See [method@Gdk.Display.is_composited] for details.
*/ */
props[PROP_COMPOSITED] = props[PROP_COMPOSITED] =
g_param_spec_boolean ("composited", g_param_spec_boolean ("composited",
@ -170,8 +165,9 @@ gdk_display_class_init (GdkDisplayClass *class)
/** /**
* GdkDisplay:rgba: * GdkDisplay:rgba:
* *
* %TRUE if the display supports an alpha channel. See gdk_display_is_rgba() * %TRUE if the display supports an alpha channel.
* for details. *
* See [method@Gdk.Display.is_rgba] for details.
*/ */
props[PROP_RGBA] = props[PROP_RGBA] =
g_param_spec_boolean ("rgba", g_param_spec_boolean ("rgba",
@ -183,8 +179,9 @@ gdk_display_class_init (GdkDisplayClass *class)
/** /**
* GdkDisplay:input-shapes: * GdkDisplay:input-shapes:
* *
* %TRUE if the display supports input shapes. See * %TRUE if the display supports input shapes.
* gdk_display_supports_input_shapes() for details. *
* See [method@Gdk.Display.supports_input_shapes] for details.
*/ */
props[PROP_INPUT_SHAPES] = props[PROP_INPUT_SHAPES] =
g_param_spec_boolean ("input-shapes", g_param_spec_boolean ("input-shapes",
@ -199,8 +196,7 @@ gdk_display_class_init (GdkDisplayClass *class)
* GdkDisplay::opened: * GdkDisplay::opened:
* @display: the object on which the signal is emitted * @display: the object on which the signal is emitted
* *
* The ::opened signal is emitted when the connection to the windowing * Emitted when the connection to the windowing system for @display is opened.
* system for @display is opened.
*/ */
signals[OPENED] = signals[OPENED] =
g_signal_new (g_intern_static_string ("opened"), g_signal_new (g_intern_static_string ("opened"),
@ -216,9 +212,8 @@ gdk_display_class_init (GdkDisplayClass *class)
* @display: the object on which the signal is emitted * @display: the object on which the signal is emitted
* @is_error: %TRUE if the display was closed due to an error * @is_error: %TRUE if the display was closed due to an error
* *
* The ::closed signal is emitted when the connection to the windowing * Emitted when the connection to the windowing system for @display is closed.
* system for @display is closed. */
*/
signals[CLOSED] = signals[CLOSED] =
g_signal_new (g_intern_static_string ("closed"), g_signal_new (g_intern_static_string ("closed"),
G_OBJECT_CLASS_TYPE (object_class), G_OBJECT_CLASS_TYPE (object_class),
@ -235,8 +230,7 @@ gdk_display_class_init (GdkDisplayClass *class)
* @display: the object on which the signal is emitted * @display: the object on which the signal is emitted
* @seat: the seat that was just added * @seat: the seat that was just added
* *
* The ::seat-added signal is emitted whenever a new seat is made * Emitted whenever a new seat is made known to the windowing system.
* known to the windowing system.
*/ */
signals[SEAT_ADDED] = signals[SEAT_ADDED] =
g_signal_new (g_intern_static_string ("seat-added"), g_signal_new (g_intern_static_string ("seat-added"),
@ -251,8 +245,7 @@ gdk_display_class_init (GdkDisplayClass *class)
* @display: the object on which the signal is emitted * @display: the object on which the signal is emitted
* @seat: the seat that was just removed * @seat: the seat that was just removed
* *
* The ::seat-removed signal is emitted whenever a seat is removed * Emitted whenever a seat is removed by the windowing system.
* by the windowing system.
*/ */
signals[SEAT_REMOVED] = signals[SEAT_REMOVED] =
g_signal_new (g_intern_static_string ("seat-removed"), g_signal_new (g_intern_static_string ("seat-removed"),
@ -267,8 +260,7 @@ gdk_display_class_init (GdkDisplayClass *class)
* @display: the object on which the signal is emitted * @display: the object on which the signal is emitted
* @setting: the name of the setting that changed * @setting: the name of the setting that changed
* *
* The ::setting-changed signal is emitted whenever a setting * Emitted whenever a setting changes its value.
* changes its value.
*/ */
signals[SETTING_CHANGED] = signals[SETTING_CHANGED] =
g_signal_new (g_intern_static_string ("setting-changed"), g_signal_new (g_intern_static_string ("setting-changed"),
@ -356,10 +348,11 @@ gdk_display_finalize (GObject *object)
/** /**
* gdk_display_close: * gdk_display_close:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Closes the connection to the windowing system for the given display, * Closes the connection to the windowing system for the given display.
* and cleans up associated resources. *
* This cleans up associated resources.
*/ */
void void
gdk_display_close (GdkDisplay *display) gdk_display_close (GdkDisplay *display)
@ -379,7 +372,7 @@ gdk_display_close (GdkDisplay *display)
/** /**
* gdk_display_is_closed: * gdk_display_is_closed:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Finds out if the display has been closed. * Finds out if the display has been closed.
* *
@ -395,12 +388,12 @@ gdk_display_is_closed (GdkDisplay *display)
/*<private> /*<private>
* gdk_display_get_event: * gdk_display_get_event:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Gets the next #GdkEvent to be processed for @display, fetching events from the * Gets the next `GdkEvent` to be processed for @display, fetching events from the
* windowing system if necessary. * windowing system if necessary.
* *
* Returns: (nullable) (transfer full): the next #GdkEvent to be processed, * Returns: (nullable) (transfer full): the next `GdkEvent` to be processed,
* or %NULL if no events are pending * or %NULL if no events are pending
*/ */
GdkEvent * GdkEvent *
@ -416,8 +409,8 @@ gdk_display_get_event (GdkDisplay *display)
/** /**
* gdk_display_put_event: * gdk_display_put_event:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* @event: (transfer none): a #GdkEvent * @event: (transfer none): a `GdkEvent`
* *
* Appends the given event onto the front of the event * Appends the given event onto the front of the event
* queue for @display. * queue for @display.
@ -853,13 +846,13 @@ gdk_device_grab_info (GdkDisplay *display,
/** /**
* gdk_display_device_is_grabbed: * gdk_display_device_is_grabbed:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* @device: a #GdkDevice * @device: a `GdkDevice`
* *
* Returns %TRUE if there is an ongoing grab on @device for @display. * Returns %TRUE if there is an ongoing grab on @device for @display.
* *
* Returns: %TRUE if there is a grab in effect for @device. * Returns: %TRUE if there is a grab in effect for @device.
**/ */
gboolean gboolean
gdk_display_device_is_grabbed (GdkDisplay *display, gdk_display_device_is_grabbed (GdkDisplay *display,
GdkDevice *device) GdkDevice *device)
@ -879,12 +872,12 @@ gdk_display_device_is_grabbed (GdkDisplay *display,
/** /**
* gdk_display_get_name: * gdk_display_get_name:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Gets the name of the display. * Gets the name of the display.
* *
* Returns: a string representing the display name. This string is owned * Returns: a string representing the display name. This string is owned
* by GDK and should not be modified or freed. * by GDK and should not be modified or freed.
*/ */
const char * const char *
gdk_display_get_name (GdkDisplay *display) gdk_display_get_name (GdkDisplay *display)
@ -896,7 +889,7 @@ gdk_display_get_name (GdkDisplay *display)
/** /**
* gdk_display_beep: * gdk_display_beep:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Emits a short beep on @display * Emits a short beep on @display
*/ */
@ -910,14 +903,15 @@ gdk_display_beep (GdkDisplay *display)
/** /**
* gdk_display_sync: * gdk_display_sync:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Flushes any requests queued for the windowing system and waits until all * Flushes any requests queued for the windowing system and waits until all
* requests have been handled. This is often used for making sure that the * requests have been handled.
* display is synchronized with the current state of the program. Calling *
* gdk_display_sync() before gdk_x11_display_error_trap_pop() makes sure * This is often used for making sure that the display is synchronized
* that any errors generated from earlier requests are handled before the * with the current state of the program. Calling [method@Gdk.Display.sync]
* error trap is removed. * before [method@GdkX11.Display.error_trap_pop] makes sure that any errors
* generated from earlier requests are handled before the error trap is removed.
* *
* This is most useful for X11. On windowing systems where requests are * This is most useful for X11. On windowing systems where requests are
* handled synchronously, this function will do nothing. * handled synchronously, this function will do nothing.
@ -932,12 +926,13 @@ gdk_display_sync (GdkDisplay *display)
/** /**
* gdk_display_flush: * gdk_display_flush:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Flushes any requests queued for the windowing system; this happens automatically * Flushes any requests queued for the windowing system.
* when the main loop blocks waiting for new events, but if your application *
* is drawing without returning control to the main loop, you may need * This happens automatically when the main loop blocks waiting for new events,
* to call this function explicitly. A common case where this function * but if your application is drawing without returning control to the main loop,
* you may need to call this function explicitly. A common case where this function
* needs to be called is when an application is executing drawing commands * needs to be called is when an application is executing drawing commands
* from a thread other than the thread where the main loop is running. * from a thread other than the thread where the main loop is running.
* *
@ -954,7 +949,7 @@ gdk_display_flush (GdkDisplay *display)
/** /**
* gdk_display_get_clipboard: * gdk_display_get_clipboard:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Gets the clipboard used for copy/paste operations. * Gets the clipboard used for copy/paste operations.
* *
@ -973,11 +968,12 @@ gdk_display_get_clipboard (GdkDisplay *display)
/** /**
* gdk_display_get_primary_clipboard: * gdk_display_get_primary_clipboard:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Gets the clipboard used for the primary selection. On backends where the * Gets the clipboard used for the primary selection.
* primary clipboard is not supported natively, GDK emulates this clipboard *
* locally. * On backends where the primary clipboard is not supported natively,
* GDK emulates this clipboard locally.
* *
* Returns: (transfer none): the primary clipboard * Returns: (transfer none): the primary clipboard
*/ */
@ -994,9 +990,11 @@ gdk_display_get_primary_clipboard (GdkDisplay *display)
/** /**
* gdk_display_supports_input_shapes: * gdk_display_supports_input_shapes:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Returns %TRUE if gdk_surface_set_input_region() can * Returns %TRUE if the display supports input shapes.
*
* This means that [method@Gdk.Surface.set_input_region] can
* be used to modify the input shape of surfaces on @display. * be used to modify the input shape of surfaces on @display.
* *
* On modern displays, this value is always %TRUE. * On modern displays, this value is always %TRUE.
@ -1039,12 +1037,12 @@ gdk_display_real_get_app_launch_context (GdkDisplay *display)
/** /**
* gdk_display_get_app_launch_context: * gdk_display_get_app_launch_context:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Returns a #GdkAppLaunchContext suitable for launching * Returns a `GdkAppLaunchContext` suitable for launching
* applications on the given display. * applications on the given display.
* *
* Returns: (transfer full): a new #GdkAppLaunchContext for @display. * Returns: (transfer full): a new `GdkAppLaunchContext` for @display.
* Free with g_object_unref() when done * Free with g_object_unref() when done
*/ */
GdkAppLaunchContext * GdkAppLaunchContext *
@ -1061,7 +1059,7 @@ gdk_display_get_app_launch_context (GdkDisplay *display)
* *
* Opens a display. * Opens a display.
* *
* Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if the * Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL if the
* display could not be opened * display could not be opened
*/ */
GdkDisplay * GdkDisplay *
@ -1079,17 +1077,17 @@ _gdk_display_get_next_serial (GdkDisplay *display)
/** /**
* gdk_display_notify_startup_complete: * gdk_display_notify_startup_complete:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* @startup_id: a startup-notification identifier, for which * @startup_id: a startup-notification identifier, for which
* notification process should be completed * notification process should be completed
* *
* Indicates to the GUI environment that the application has * Indicates to the GUI environment that the application has
* finished loading, using a given identifier. * finished loading, using a given identifier.
* *
* GTK will call this function automatically for #GtkWindow * GTK will call this function automatically for [class@Gtk.Window]
* with custom startup-notification identifier unless * with custom startup-notification identifier unless
* gtk_window_set_auto_startup_notification() is called to * [method@Gtk.Window.set_auto_startup_notification]
* disable that feature. * is called to disable that feature.
*/ */
void void
gdk_display_notify_startup_complete (GdkDisplay *display, gdk_display_notify_startup_complete (GdkDisplay *display,
@ -1102,7 +1100,7 @@ gdk_display_notify_startup_complete (GdkDisplay *display,
/** /**
* gdk_display_get_startup_notification_id: * gdk_display_get_startup_notification_id:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Gets the startup notification ID for a Wayland display, or %NULL * Gets the startup notification ID for a Wayland display, or %NULL
* if no ID has been defined. * if no ID has been defined.
@ -1151,7 +1149,7 @@ gdk_display_create_surface (GdkDisplay *display,
/** /**
* gdk_display_get_keymap: * gdk_display_get_keymap:
* @display: the #GdkDisplay * @display: the `GdkDisplay`
* *
* Returns the #GdkKeymap attached to @display. * Returns the #GdkKeymap attached to @display.
* *
@ -1195,21 +1193,23 @@ gdk_display_set_debug_flags (GdkDisplay *display,
/** /**
* gdk_display_is_composited: * gdk_display_is_composited:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Returns whether surfaces can reasonably be expected to have * Returns whether surfaces can reasonably be expected to have
* their alpha channel drawn correctly on the screen. Check * their alpha channel drawn correctly on the screen.
* gdk_display_is_rgba() for whether the display supports an *
* alpha channel. * Check [method@Gdk.Display.is_rgba] for whether the display
* supports an alpha channel.
* *
* On X11 this function returns whether a compositing manager is * On X11 this function returns whether a compositing manager is
* compositing on @display. * compositing on @display.
* *
* On modern displays, this value is always %TRUE. * On modern displays, this value is always %TRUE.
* *
* Returns: Whether surfaces with RGBA visuals can reasonably be * Returns: Whether surfaces with RGBA visuals can reasonably
* expected to have their alpha channels drawn correctly on the screen. * be expected to have their alpha channels drawn correctly
**/ * on the screen.
*/
gboolean gboolean
gdk_display_is_composited (GdkDisplay *display) gdk_display_is_composited (GdkDisplay *display)
{ {
@ -1234,7 +1234,7 @@ gdk_display_set_composited (GdkDisplay *display,
/** /**
* gdk_display_is_rgba: * gdk_display_is_rgba:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Returns whether surfaces on this @display are created with an * Returns whether surfaces on this @display are created with an
* alpha channel. * alpha channel.
@ -1243,14 +1243,14 @@ gdk_display_set_composited (GdkDisplay *display,
* surface’s alpha channel won’t be honored when displaying the * surface’s alpha channel won’t be honored when displaying the
* surface on the screen: in particular, for X an appropriate * surface on the screen: in particular, for X an appropriate
* windowing manager and compositing manager must be running to * windowing manager and compositing manager must be running to
* provide appropriate display. Use gdk_display_is_composited() * provide appropriate display. Use [method@Gdk.Display.is_composited]
* to check if that is the case. * to check if that is the case.
* *
* On modern displays, this value is always %TRUE. * On modern displays, this value is always %TRUE.
* *
* Returns: %TRUE if surfaces are created with an alpha channel or * Returns: %TRUE if surfaces are created with an alpha channel or
* %FALSE if the display does not support this functionality. * %FALSE if the display does not support this functionality.
**/ */
gboolean gboolean
gdk_display_is_rgba (GdkDisplay *display) gdk_display_is_rgba (GdkDisplay *display)
{ {
@ -1321,9 +1321,9 @@ gdk_display_remove_seat (GdkDisplay *display,
/** /**
* gdk_display_get_default_seat: * gdk_display_get_default_seat:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Returns the default #GdkSeat for this display. * Returns the default `GdkSeat` for this display.
* *
* Note that a display may not have a seat. In this case, * Note that a display may not have a seat. In this case,
* this function will return %NULL. * this function will return %NULL.
@ -1344,12 +1344,12 @@ gdk_display_get_default_seat (GdkDisplay *display)
/** /**
* gdk_display_list_seats: * gdk_display_list_seats:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* *
* Returns the list of seats known to @display. * Returns the list of seats known to @display.
* *
* Returns: (transfer container) (element-type GdkSeat): the * Returns: (transfer container) (element-type GdkSeat): the
* list of seats known to the #GdkDisplay * list of seats known to the `GdkDisplay`
**/ **/
GList * GList *
gdk_display_list_seats (GdkDisplay *display) gdk_display_list_seats (GdkDisplay *display)
@ -1361,17 +1361,17 @@ gdk_display_list_seats (GdkDisplay *display)
/** /**
* gdk_display_get_monitors: * gdk_display_get_monitors:
* @self: a #GdkDisplay * @self: a `GdkDisplay`
* *
* Gets the list of monitors associated with this display. * Gets the list of monitors associated with this display.
* *
* Subsequent calls to this function will always return the same list for the * Subsequent calls to this function will always return the
* same display. * same list for the same display.
* *
* You can listen to the GListModel::items-changed signal on this list * You can listen to the GListModel::items-changed signal on
* to monitor changes to the monitor of this display. * this list to monitor changes to the monitor of this display.
* *
* Returns: (transfer none): a #GListModel of #GdkMonitor * Returns: (transfer none): a #GListModel of `GdkMonitor`
*/ */
GListModel * GListModel *
gdk_display_get_monitors (GdkDisplay *self) gdk_display_get_monitors (GdkDisplay *self)
@ -1383,14 +1383,17 @@ gdk_display_get_monitors (GdkDisplay *self)
/** /**
* gdk_display_get_monitor_at_surface: * gdk_display_get_monitor_at_surface:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* @surface: a #GdkSurface * @surface: a `GdkSurface`
* *
* Gets the monitor in which the largest area of @surface * Gets the monitor in which the largest area of @surface
* resides, or a monitor close to @surface if it is outside * resides.
*
* Returns a monitor close to @surface if it is outside
* of all monitors. * of all monitors.
* *
* Returns: (transfer none): the monitor with the largest overlap with @surface * Returns: (transfer none): the monitor with the largest
* overlap with @surface
*/ */
GdkMonitor * GdkMonitor *
gdk_display_get_monitor_at_surface (GdkDisplay *display, gdk_display_get_monitor_at_surface (GdkDisplay *display,
@ -1448,7 +1451,7 @@ gdk_display_emit_opened (GdkDisplay *display)
/** /**
* gdk_display_get_setting: * gdk_display_get_setting:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* @name: the name of the setting * @name: the name of the setting
* @value: location to store the value of the setting * @value: location to store the value of the setting
* *
@ -1502,23 +1505,24 @@ gdk_display_set_cursor_theme (GdkDisplay *display,
/** /**
* gdk_display_map_keyval: * gdk_display_map_keyval:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* @keyval: a keyval, such as %GDK_KEY_a, %GDK_KEY_Up, %GDK_KEY_Return, etc. * @keyval: a keyval, such as %GDK_KEY_a, %GDK_KEY_Up, %GDK_KEY_Return, etc.
* @keys: (out) (array length=n_keys) (transfer full): return location * @keys: (out) (array length=n_keys) (transfer full): return location
* for an array of #GdkKeymapKey * for an array of `GdkKeymapKey`
* @n_keys: return location for number of elements in returned array * @n_keys: return location for number of elements in returned array
* *
* Obtains a list of keycode/group/level combinations that will * Obtains a list of keycode/group/level combinations that will
* generate @keyval. Groups and levels are two kinds of keyboard mode; * generate @keyval.
* in general, the level determines whether the top or bottom symbol *
* on a key is used, and the group determines whether the left or * Groups and levels are two kinds of keyboard mode; in general, the level
* right symbol is used. * determines whether the top or bottom symbol on a key is used, and the
* group determines whether the left or right symbol is used.
* *
* On US keyboards, the shift key changes the keyboard level, and there * On US keyboards, the shift key changes the keyboard level, and there
* are no groups. A group switch key might convert a keyboard between * are no groups. A group switch key might convert a keyboard between
* Hebrew to English modes, for example. * Hebrew to English modes, for example.
* *
* #GdkEventKey contains a %group field that indicates the active * `GdkEventKey` contains a %group field that indicates the active
* keyboard group. The level is computed from the modifier mask. * keyboard group. The level is computed from the modifier mask.
* *
* The returned array should be freed with g_free(). * The returned array should be freed with g_free().
@ -1539,16 +1543,17 @@ gdk_display_map_keyval (GdkDisplay *display,
/** /**
* gdk_display_map_keycode: * gdk_display_map_keycode:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* @keycode: a keycode * @keycode: a keycode
* @keys: (out) (array length=n_entries) (transfer full) (optional): return * @keys: (out) (array length=n_entries) (transfer full) (optional): return
* location for array of #GdkKeymapKey, or %NULL * location for array of `GdkKeymapKey`, or %NULL
* @keyvals: (out) (array length=n_entries) (transfer full) (optional): return * @keyvals: (out) (array length=n_entries) (transfer full) (optional): return
* location for array of keyvals, or %NULL * location for array of keyvals, or %NULL
* @n_entries: length of @keys and @keyvals * @n_entries: length of @keys and @keyvals
* *
* Returns the keyvals bound to @keycode. The Nth #GdkKeymapKey * Returns the keyvals bound to @keycode.
* in @keys is bound to the Nth keyval in @keyvals. *
* The Nth `GdkKeymapKey` in @keys is bound to the Nth keyval in @keyvals.
* *
* When a keycode is pressed by the user, the keyval from * When a keycode is pressed by the user, the keyval from
* this list of entries is selected by considering the effective * this list of entries is selected by considering the effective
@ -1574,7 +1579,7 @@ gdk_display_map_keycode (GdkDisplay *display,
/** /**
* gdk_display_translate_key: * gdk_display_translate_key:
* @display: a #GdkDisplay * @display: a `GdkDisplay`
* @keycode: a keycode * @keycode: a keycode
* @state: a modifier state * @state: a modifier state
* @group: active keyboard group * @group: active keyboard group
@ -1585,23 +1590,25 @@ gdk_display_map_keycode (GdkDisplay *display,
* @consumed: (out) (optional): return location for modifiers * @consumed: (out) (optional): return location for modifiers
* that were used to determine the group or level, or %NULL * that were used to determine the group or level, or %NULL
* *
* Translates the contents of a #GdkEventKey (ie @keycode, @state, and @group) * Translates the contents of a `GdkEventKey` into a keyval, effective group,
* into a keyval, effective group, and level. Modifiers that affected the * and level.
* translation and are thus unavailable for application use are returned in
* @consumed_modifiers.
* *
* The @effective_group is the group that was actually used for the translation; * Modifiers that affected the translation and are thus unavailable for
* some keys such as Enter are not affected by the active keyboard group. * application use are returned in @consumed_modifiers.
* The @level is derived from @state.
* *
* @consumed_modifiers gives modifiers that should be masked outfrom @state * The @effective_group is the group that was actually used for the
* when comparing this key press to a keyboard shortcut. For instance, on a US * translation; some keys such as Enter are not affected by the active
* keyboard, the `plus` symbol is shifted, so when comparing a key press to a * keyboard group. The @level is derived from @state.
* `<Control>plus` accelerator `<Shift>` should be masked out.
* *
* This function should rarely be needed, since #GdkEventKey already contains * @consumed_modifiers gives modifiers that should be masked out
* the translated keyval. It is exported for the benefit of virtualized test * from @state when comparing this key press to a keyboard shortcut.
* environments. * 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.
*
* This function should rarely be needed, since `GdkEventKey` already
* contains the translated keyval. It is exported for the benefit of
* virtualized test environments.
* *
* Returns: %TRUE if there was a keyval bound to keycode/state/group. * Returns: %TRUE if there was a keyval bound to keycode/state/group.
*/ */

14
gdk/gdkgl.c
View File

@ -301,13 +301,15 @@ gdk_gl_texture_quads (GdkGLContext *paint_context,
* @width: The width of the region to draw * @width: The width of the region to draw
* @height: The height of the region to draw * @height: The height of the region to draw
* *
* This is the main way to draw GL content in GTK. It takes a render buffer ID * The main way to draw GL content in GTK.
* (@source_type == #GL_RENDERBUFFER) or a texture id (@source_type == #GL_TEXTURE)
* and draws it onto @cr with an OVER operation, respecting the current clip.
* The top left corner of the rectangle specified by @x, @y, @width and @height
* will be drawn at the current (0,0) position of the cairo_t.
* *
* This will work for *all* cairo_t, as long as @surface is realized, but the * It takes a render buffer ID (@source_type == #GL_RENDERBUFFER) or a texture
* id (@source_type == #GL_TEXTURE) and draws it onto @cr with an OVER operation,
* respecting the current clip. The top left corner of the rectangle specified
* by @x, @y, @width and @height will be drawn at the current (0,0) position of
* the `cairo_t`.
*
* This will work for *all* `cairo_t`, as long as @surface is realized, but the
* fallback implementation that reads back the pixels from the buffer may be * fallback implementation that reads back the pixels from the buffer may be
* used in the general case. In the case of direct drawing to a surface with * used in the general case. In the case of direct drawing to a surface with
* no special effects applied to @cr it will however use a more efficient * no special effects applied to @cr it will however use a more efficient

8
gdk/gdkkeys.c
View File

@ -135,8 +135,9 @@ gdk_keymap_class_init (GdkKeymapClass *klass)
* GdkKeymap::direction-changed: * GdkKeymap::direction-changed:
* @keymap: the object on which the signal is emitted * @keymap: the object on which the signal is emitted
* *
* The ::direction-changed signal gets emitted when the direction * Emitted when the direction of the keymap changes.
* of the keymap changes. See gdk_keymap_get_direction(). *
* See gdk_keymap_get_direction().
*/ */
signals[DIRECTION_CHANGED] = signals[DIRECTION_CHANGED] =
g_signal_new (g_intern_static_string ("direction-changed"), g_signal_new (g_intern_static_string ("direction-changed"),
@ -147,6 +148,7 @@ gdk_keymap_class_init (GdkKeymapClass *klass)
NULL, NULL,
G_TYPE_NONE, G_TYPE_NONE,
0); 0);
/** /**
* GdkKeymap::keys-changed: * GdkKeymap::keys-changed:
* @keymap: the object on which the signal is emitted * @keymap: the object on which the signal is emitted
@ -305,6 +307,7 @@ gdk_keyval_is_lower (guint keyval)
* @keymap: a #GdkKeymap * @keymap: a #GdkKeymap
* *
* Returns the direction of effective layout of the keymap. * Returns the direction of effective layout of the keymap.
*
* The direction of a layout is the direction of the majority of its * The direction of a layout is the direction of the majority of its
* symbols. See pango_unichar_direction(). * symbols. See pango_unichar_direction().
* *
@ -678,6 +681,7 @@ gdk_keyval_from_name (const char *keyval_name)
* @upper: (out): return location for uppercase version of @symbol * @upper: (out): return location for uppercase version of @symbol
* *
* Obtains the upper- and lower-case versions of the keyval @symbol. * Obtains the upper- and lower-case versions of the keyval @symbol.
*
* Examples of keyvals are #GDK_KEY_a, #GDK_KEY_Enter, #GDK_KEY_F1, etc. * Examples of keyvals are #GDK_KEY_a, #GDK_KEY_Enter, #GDK_KEY_F1, etc.
*/ */
void void

19
gdk/gdkkeyuni.c
View File

@ -880,7 +880,7 @@ static const struct {
* gdk_keyval_to_unicode: * gdk_keyval_to_unicode:
* @keyval: a GDK key symbol * @keyval: a GDK key symbol
* *
* Convert from a GDK key symbol to the corresponding ISO10646 (Unicode) * Convert from a GDK key symbol to the corresponding Unicode
* character. * character.
* *
* Note that the conversion does not take the current locale * Note that the conversion does not take the current locale
@ -888,8 +888,8 @@ static const struct {
* keyvals, such as %GDK_KEY_KP_Decimal. * keyvals, such as %GDK_KEY_KP_Decimal.
* *
* Returns: the corresponding unicode character, or 0 if there * Returns: the corresponding unicode character, or 0 if there
* is no corresponding character. * is no corresponding character.
**/ */
guint32 guint32
gdk_keyval_to_unicode (guint keyval) gdk_keyval_to_unicode (guint keyval)
{ {
@ -1682,14 +1682,13 @@ static const struct {
/** /**
* gdk_unicode_to_keyval: * gdk_unicode_to_keyval:
* @wc: a ISO10646 encoded character * @wc: a Unicode character
* *
* Convert from a ISO10646 character to a key symbol. * Convert from a Unicode character to a key symbol.
* *
* Returns: the corresponding GDK key symbol, if one exists. * Returns: the corresponding GDK key symbol, if one exists.
* or, if there is no corresponding symbol, * or, if there is no corresponding symbol, wc | 0x01000000
* wc | 0x01000000 */
**/
guint guint
gdk_unicode_to_keyval (guint32 wc) gdk_unicode_to_keyval (guint32 wc)
{ {

42
gdk/gdkpango.c
View File

@ -90,31 +90,32 @@ layout_iter_get_line_clip_region (PangoLayoutIter *iter,
/** /**
* gdk_pango_layout_line_get_clip_region: (skip) * gdk_pango_layout_line_get_clip_region: (skip)
* @line: a #PangoLayoutLine * @line: a `PangoLayoutLine`
* @x_origin: X pixel where you intend to draw the layout line with this clip * @x_origin: X pixel where you intend to draw the layout line with this clip
* @y_origin: baseline pixel where you intend to draw the layout line with this clip * @y_origin: baseline pixel where you intend to draw the layout line with this clip
* @index_ranges: (array): array of byte indexes into the layout, * @index_ranges: (array): array of byte indexes into the layout,
* where even members of array are start indexes and odd elements * where even members of array are start indexes and odd elements
* are end indexes * are end indexes
* @n_ranges: number of ranges in @index_ranges, i.e. half the size of @index_ranges * @n_ranges: number of ranges in @index_ranges, i.e. half the size of @index_ranges
* *
* Obtains a clip region which contains the areas where the given * Obtains a clip region which contains the areas where the given
* ranges of text would be drawn. @x_origin and @y_origin are the top left * ranges of text would be drawn.
* position of the layout. @index_ranges *
* should contain ranges of bytes in the layout’s text. The clip * @x_origin and @y_origin are the top left position of the layout.
* region will include space to the left or right of the line (to the * @index_ranges should contain ranges of bytes in the layout’s text.
* layout bounding box) if you have indexes above or below the indexes * The clip region will include space to the left or right of the line
* contained inside the line. This is to draw the selection all the way * (to the layout bounding box) if you have indexes above or below the
* to the side of the layout. However, the clip region is in line coordinates, * indexes contained inside the line. This is to draw the selection all
* not layout coordinates. * the way to the side of the layout. However, the clip region is in line
* coordinates, not layout coordinates.
* *
* Note that the regions returned correspond to logical extents of the text * Note that the regions returned correspond to logical extents of the text
* ranges, not ink extents. So the drawn line may in fact touch areas out of * ranges, not ink extents. So the drawn line may in fact touch areas out of
* the clip region. The clip region is mainly useful for highlightling parts * the clip region. The clip region is mainly useful for highlightling parts
* of text, such as when text is selected. * of text, such as when text is selected.
* *
* Returns: a clip region containing the given ranges * Returns: a clip region containing the given ranges
**/ */
cairo_region_t* cairo_region_t*
gdk_pango_layout_line_get_clip_region (PangoLayoutLine *line, gdk_pango_layout_line_get_clip_region (PangoLayoutLine *line,
int x_origin, int x_origin,
@ -141,24 +142,25 @@ gdk_pango_layout_line_get_clip_region (PangoLayoutLine *line,
/** /**
* gdk_pango_layout_get_clip_region: (skip) * gdk_pango_layout_get_clip_region: (skip)
* @layout: a #PangoLayout * @layout: a `PangoLayout`
* @x_origin: X pixel where you intend to draw the layout with this clip * @x_origin: X pixel where you intend to draw the layout with this clip
* @y_origin: Y pixel where you intend to draw the layout with this clip * @y_origin: Y pixel where you intend to draw the layout with this clip
* @index_ranges: array of byte indexes into the layout, where even members of array are start indexes and odd elements are end indexes * @index_ranges: array of byte indexes into the layout, where even members of array are start indexes and odd elements are end indexes
* @n_ranges: number of ranges in @index_ranges, i.e. half the size of @index_ranges * @n_ranges: number of ranges in @index_ranges, i.e. half the size of @index_ranges
* *
* Obtains a clip region which contains the areas where the given ranges * Obtains a clip region which contains the areas where the given ranges
* of text would be drawn. @x_origin and @y_origin are the top left point * of text would be drawn.
* to center the layout. @index_ranges should contain *
* ranges of bytes in the layout’s text. * @x_origin and @y_origin are the top left point to center the layout.
* * @index_ranges should contain ranges of bytes in the layout’s text.
*
* Note that the regions returned correspond to logical extents of the text * Note that the regions returned correspond to logical extents of the text
* ranges, not ink extents. So the drawn layout may in fact touch areas out of * ranges, not ink extents. So the drawn layout may in fact touch areas out of
* the clip region. The clip region is mainly useful for highlightling parts * the clip region. The clip region is mainly useful for highlightling parts
* of text, such as when text is selected. * of text, such as when text is selected.
* *
* Returns: a clip region containing the given ranges * Returns: a clip region containing the given ranges
**/ */
cairo_region_t* cairo_region_t*
gdk_pango_layout_get_clip_region (PangoLayout *layout, gdk_pango_layout_get_clip_region (PangoLayout *layout,
int x_origin, int x_origin,

28
gdk/gdkpixbuf-drawable.c
View File

@ -30,17 +30,6 @@
#include <gdk-pixbuf/gdk-pixbuf.h> #include <gdk-pixbuf/gdk-pixbuf.h>
/**
* SECTION:pixbufs
* @Short_description: Functions for obtaining pixbufs
* @Title: GdkPixbuf Interaction
*
* Pixbufs are client-side images. For details on how to create
* and manipulate pixbufs, see the #GdkPixbuf API documentation.
*
* The functions described here allow to obtain pixbufs from
* #GdkSurfaces and cairo surfaces.
*/
static cairo_format_t static cairo_format_t
gdk_cairo_format_for_content (cairo_content_t content) gdk_cairo_format_for_content (cairo_content_t content)
@ -157,9 +146,10 @@ convert_no_alpha (guchar *dest_data,
* @width: Width in pixels of region to get * @width: Width in pixels of region to get
* @height: Height in pixels of region to get * @height: Height in pixels of region to get
* *
* Transfers image data from a #cairo_surface_t and converts it to an RGB(A) * Transfers image data from a `cairo_surface_t` and converts it
* representation inside a #GdkPixbuf. This allows you to efficiently read * to a `GdkPixbuf`.
* individual pixels from cairo surfaces. *
* This allows you to efficiently read individual pixels from cairo surfaces.
* *
* This function will create an RGB pixbuf with 8 bits per channel. * This function will create an RGB pixbuf with 8 bits per channel.
* The pixbuf will contain an alpha channel if the @surface contains one. * The pixbuf will contain an alpha channel if the @surface contains one.
@ -227,11 +217,13 @@ gdk_pixbuf_get_from_surface (cairo_surface_t *surface,
/** /**
* gdk_pixbuf_get_from_texture: * gdk_pixbuf_get_from_texture:
* @texture: a #GdkTexture * @texture: a `GdkTexture`
* *
* Creates a new pixbuf from @texture. This should generally not be used * Creates a new pixbuf from @texture.
* in newly written code as later stages will almost certainly convert *
* the pixbuf back into a texture to draw it on screen. * This should generally not be used in newly written code as later
* stages will almost certainly convert the pixbuf back into a texture
* to draw it on screen.
* *
* Returns: (transfer full) (nullable): a new #GdkPixbuf or %NULL * Returns: (transfer full) (nullable): a new #GdkPixbuf or %NULL
* in case of an error * in case of an error

12
gdk/gdktypes.h
View File

@ -148,9 +148,11 @@ typedef enum
* @GDK_HYPER_MASK: the Hyper modifier * @GDK_HYPER_MASK: the Hyper modifier
* @GDK_META_MASK: the Meta modifier * @GDK_META_MASK: the Meta modifier
* *
* A set of bit-flags to indicate the state of modifier keys and mouse buttons * Flags to indicate the state of modifier keys and mouse buttons
* in various event types. Typical modifier keys are Shift, Control, Meta, * in events.
* Super, Hyper, Alt, Compose, Apple, CapsLock or ShiftLock. *
* Typical modifier keys are Shift, Control, Meta, Super, Hyper, Alt, Compose,
* Apple, CapsLock or ShiftLock.
* *
* Note that GDK may add internal values to events which include values outside * Note that GDK may add internal values to events which include values outside
* of this enumeration. Your code should preserve and ignore them. You can use * of this enumeration. Your code should preserve and ignore them. You can use
@ -178,7 +180,7 @@ typedef enum
/** /**
* GDK_MODIFIER_MASK: * GDK_MODIFIER_MASK:
* *
* A mask covering all entries in #GdkModifierType. * A mask covering all entries in `GdkModifierType`.
*/ */
#define GDK_MODIFIER_MASK (GDK_SHIFT_MASK|GDK_LOCK_MASK|GDK_CONTROL_MASK| \ #define GDK_MODIFIER_MASK (GDK_SHIFT_MASK|GDK_LOCK_MASK|GDK_CONTROL_MASK| \
GDK_ALT_MASK|GDK_SUPER_MASK|GDK_HYPER_MASK|GDK_META_MASK| \ GDK_ALT_MASK|GDK_SUPER_MASK|GDK_HYPER_MASK|GDK_META_MASK| \
@ -194,7 +196,7 @@ typedef enum
* @GDK_GL_ERROR_COMPILATION_FAILED: The shader compilation failed * @GDK_GL_ERROR_COMPILATION_FAILED: The shader compilation failed
* @GDK_GL_ERROR_LINK_FAILED: The shader linking failed * @GDK_GL_ERROR_LINK_FAILED: The shader linking failed
* *
* Error enumeration for #GdkGLContext. * Error enumeration for `GdkGLContext`.
*/ */
typedef enum { typedef enum {
GDK_GL_ERROR_NOT_AVAILABLE, GDK_GL_ERROR_NOT_AVAILABLE,