From 51d35750f63c09000aafd766b8ffc9bf6bc3dead Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 29 Oct 2020 07:40:30 -0400 Subject: [PATCH 01/13] Cosmetics Whitespace fix. --- gdk/gdkcursor.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/gdk/gdkcursor.h b/gdk/gdkcursor.h index a2f161bd58..1a0ea5d772 100644 --- a/gdk/gdkcursor.h +++ b/gdk/gdkcursor.h @@ -46,15 +46,15 @@ GType gdk_cursor_get_type (void) G_GNUC_CONST; GDK_AVAILABLE_IN_ALL GdkCursor* gdk_cursor_new_from_texture (GdkTexture *texture, - int hotspot_x, - int hotspot_y, + int hotspot_x, + int hotspot_y, GdkCursor *fallback); GDK_AVAILABLE_IN_ALL -GdkCursor* gdk_cursor_new_from_name (const char *name, +GdkCursor* gdk_cursor_new_from_name (const char *name, GdkCursor *fallback); GDK_AVAILABLE_IN_ALL -GdkCursor * gdk_cursor_get_fallback (GdkCursor *cursor); +GdkCursor * gdk_cursor_get_fallback (GdkCursor *cursor); GDK_AVAILABLE_IN_ALL const char *gdk_cursor_get_name (GdkCursor *cursor); GDK_AVAILABLE_IN_ALL From 29ccd13e155d95feebf70bd1185628c0f08f325b Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 29 Oct 2020 07:40:48 -0400 Subject: [PATCH 02/13] docs: Stop referring to the Quartz backend Its MacOS now. --- gdk/x11/gdkmain-x11.c | 6 +++--- testsuite/gtk/autotestkeywords.cc | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/gdk/x11/gdkmain-x11.c b/gdk/x11/gdkmain-x11.c index b7a7e3b9cd..7c5fbf2763 100644 --- a/gdk/x11/gdkmain-x11.c +++ b/gdk/x11/gdkmain-x11.c @@ -68,10 +68,10 @@ * } * else * #endif - * #ifdef GDK_WINDOWING_QUARTZ - * if (GDK_IS_QUARTZ_DISPLAY (display)) + * #ifdef GDK_WINDOWING_MACOS + * if (GDK_IS_MACOS_DISPLAY (display)) * { - * // make Quartz-specific calls here + * // make MacOS-specific calls here * } * else * #endif diff --git a/testsuite/gtk/autotestkeywords.cc b/testsuite/gtk/autotestkeywords.cc index 04c637ea1e..971fdc50ac 100644 --- a/testsuite/gtk/autotestkeywords.cc +++ b/testsuite/gtk/autotestkeywords.cc @@ -4,9 +4,9 @@ #include #endif -#ifdef GDK_WINDOWING_QUARTZ +#ifdef GDK_WINDOWING_MACOS #if HAVE_OBJC -#include +#include #endif #endif From 3617fbab4236b0356cfb4ab46a180a05685015a9 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 29 Oct 2020 12:35:28 -0400 Subject: [PATCH 03/13] docs: Include GDK_WINDOWING_MACOS We no longer have a Quartz backend, it is called MacOS now. --- docs/reference/gdk/gdk4-overrides.txt | 4 ++-- docs/reference/gdk/gdk4-sections.txt | 2 +- gdk/gdk.c | 6 +++--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/reference/gdk/gdk4-overrides.txt b/docs/reference/gdk/gdk4-overrides.txt index 4123476674..5dab67c7c9 100644 --- a/docs/reference/gdk/gdk4-overrides.txt +++ b/docs/reference/gdk/gdk4-overrides.txt @@ -10,8 +10,8 @@ -GDK_WINDOWING_QUARTZ -#define GDK_WINDOWING_QUARTZ +GDK_WINDOWING_MACOS +#define GDK_WINDOWING_MACOS diff --git a/docs/reference/gdk/gdk4-sections.txt b/docs/reference/gdk/gdk4-sections.txt index 9373f948f3..ac187474cf 100644 --- a/docs/reference/gdk/gdk4-sections.txt +++ b/docs/reference/gdk/gdk4-sections.txt @@ -8,7 +8,7 @@ GDK_WINDOWING_X11 GDK_WINDOWING_WIN32 -GDK_WINDOWING_QUARTZ +GDK_WINDOWING_MACOS GDK_WINDOWING_WAYLAND diff --git a/gdk/gdk.c b/gdk/gdk.c index 1cb48f411b..874e993892 100644 --- a/gdk/gdk.c +++ b/gdk/gdk.c @@ -87,12 +87,12 @@ */ /** - * GDK_WINDOWING_QUARTZ: + * GDK_WINDOWING_MACOS: * - * The #GDK_WINDOWING_QUARTZ macro is defined if the Quartz backend + * The #GDK_WINDOWING_MACOS macro is defined if the MacOS backend * is supported. * - * Use this macro to guard code that is specific to the Quartz backend. + * Use this macro to guard code that is specific to the MacOS backend. */ /** From 574a3a456d48b1645c24564f25b32001952ab397 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 29 Oct 2020 13:06:08 -0400 Subject: [PATCH 04/13] gdk: Drop GdkPoint from the api This typedef was not used in any public APIs, and is only used in the MacOS backend. It is not worth preserving as public API, move it to the only user. --- docs/reference/gdk/gdk4-sections.txt | 5 +---- gdk/gdkrectangle.c | 18 ++++++++++-------- gdk/gdktypes.h | 14 -------------- gdk/macos/GdkMacosWindow.c | 1 + gdk/macos/edgesnapping.h | 1 + gdk/macos/gdkmacosutils-private.h | 8 ++++++++ 6 files changed, 21 insertions(+), 26 deletions(-) diff --git a/docs/reference/gdk/gdk4-sections.txt b/docs/reference/gdk/gdk4-sections.txt index ac187474cf..efbc18fc5b 100644 --- a/docs/reference/gdk/gdk4-sections.txt +++ b/docs/reference/gdk/gdk4-sections.txt @@ -303,11 +303,8 @@ gdk_cairo_draw_from_gl
-Points, Rectangles and Regions +Rectangles and Regions regions -GdkPoint - - GdkRectangle gdk_rectangle_intersect gdk_rectangle_union diff --git a/gdk/gdkrectangle.c b/gdk/gdkrectangle.c index edae510625..8043716044 100644 --- a/gdk/gdkrectangle.c +++ b/gdk/gdkrectangle.c @@ -30,21 +30,23 @@ /** * SECTION:regions - * @Short_description: Simple graphical data types - * @Title: Points and Rectangles + * @Short_description: Simple graphical data type + * @Title: GdkRectangle * - * GDK provides the #GdkPoint and #GdkRectangle data types for representing pixels - * and sets of pixels on the screen. Together with Cairo’s #cairo_region_t data - * type, they make up the central types for representing graphical data. - * - * A #GdkPoint represents an x and y coordinate of a point. + * 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(). * - * #cairo_region_t is usually used for managing clipping of graphical operations. + * #cairo_region_t is usually used for managing clipping of graphical + * operations. + * + * The graphene library has a number of other data types for regions and + * volumes in 2D and 3D. */ diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h index 0a0068e181..da12f125bc 100644 --- a/gdk/gdktypes.h +++ b/gdk/gdktypes.h @@ -53,20 +53,6 @@ G_BEGIN_DECLS */ #define GDK_CURRENT_TIME 0L -/** - * GdkPoint: - * @x: the x coordinate of the point - * @y: the y coordinate of the point - * - * Defines the x and y coordinates of a point. - */ -struct _GdkPoint -{ - int x; - int y; -}; -typedef struct _GdkPoint GdkPoint; - /** * GdkRectangle: * @x: the x coordinate of the top left corner diff --git a/gdk/macos/GdkMacosWindow.c b/gdk/macos/GdkMacosWindow.c index c4a133afcc..fd2ca53b26 100644 --- a/gdk/macos/GdkMacosWindow.c +++ b/gdk/macos/GdkMacosWindow.c @@ -32,6 +32,7 @@ #include "gdkmacossurface-private.h" #include "gdkmacospopupsurface-private.h" #include "gdkmacostoplevelsurface-private.h" +#include "gdkmacosutils-private.h" #include "gdkmonitorprivate.h" #include "gdksurfaceprivate.h" diff --git a/gdk/macos/edgesnapping.h b/gdk/macos/edgesnapping.h index 8769ea7e47..b7ffd8a176 100644 --- a/gdk/macos/edgesnapping.h +++ b/gdk/macos/edgesnapping.h @@ -22,6 +22,7 @@ #define __EDGE_SNAPPING_H__ #include "gdktypes.h" +#include "gdkmacosutils-private.h" G_BEGIN_DECLS diff --git a/gdk/macos/gdkmacosutils-private.h b/gdk/macos/gdkmacosutils-private.h index 678982ba97..6b81fd28ac 100644 --- a/gdk/macos/gdkmacosutils-private.h +++ b/gdk/macos/gdkmacosutils-private.h @@ -33,4 +33,12 @@ queue_contains (GQueue *queue, return queue->head == link_ || link_->prev || link_->next; } +struct _GdkPoint +{ + int x; + int y; +}; +typedef struct _GdkPoint GdkPoint; + + #endif /* __GDK_MACOS_UTILS_PRIVATE_H__ */ From 1f8d593931422567b77d1366a49c5e960b0c62bf Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 29 Oct 2020 13:16:49 -0400 Subject: [PATCH 05/13] docs: Add some detail to GdkTexture docs Minor additions here and there. --- gdk/gdktexture.c | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/gdk/gdktexture.c b/gdk/gdktexture.c index c28bd9575f..d54bb73e16 100644 --- a/gdk/gdktexture.c +++ b/gdk/gdktexture.c @@ -202,7 +202,7 @@ gdk_texture_class_init (GdkTextureClass *klass) /** * GdkTexture:width: * - * The width of the texture. + * The width of the texture, in pixels. */ properties[PROP_WIDTH] = g_param_spec_int ("width", @@ -219,7 +219,7 @@ gdk_texture_class_init (GdkTextureClass *klass) /** * GdkTexture:height: * - * The height of the texture. + * The height of the texture, in pixels. */ properties[PROP_HEIGHT] = g_param_spec_int ("height", @@ -281,7 +281,7 @@ gdk_texture_new_for_surface (cairo_surface_t *surface) * gdk_texture_new_for_pixbuf: * @pixbuf: a #GdkPixbuf * - * Creates a new texture object representing the GdkPixbuf. + * Creates a new texture object representing the #GdkPixbuf. * * Returns: a new #GdkTexture */ @@ -316,7 +316,9 @@ gdk_texture_new_for_pixbuf (GdkPixbuf *pixbuf) * @resource_path: the path of the resource file * * Creates a new texture by loading an image from a resource. - * The file format is detected automatically. + * The file format is detected automatically, and can be any + * format that is supported by the gdk-pixbuf library, such as + * JPEG or PNG. * * It is a fatal error if @resource_path does not specify a valid * image resource and the program will abort if that happens. @@ -349,8 +351,12 @@ gdk_texture_new_from_resource (const char *resource_path) * @file: #GFile to load * @error: Return location for an error * - * Creates a new texture by loading an image from a file. The file format is - * detected automatically. If %NULL is returned, then @error will be set. + * Creates a new texture by loading an image from a file. + * The file format is detected automatically, and can be any + * format that is supported by the gdk-pixbuf library, such as + * JPEG or PNG. + * + * If %NULL is returned, then @error will be set. * * Return value: A newly-created #GdkTexture or %NULL if an error occurred. **/ @@ -384,7 +390,7 @@ gdk_texture_new_from_file (GFile *file, * gdk_texture_get_width: * @texture: a #GdkTexture * - * Returns the width of @texture. + * Returns the width of @texture, in pixels. * * Returns: the width of the #GdkTexture */ @@ -400,7 +406,7 @@ gdk_texture_get_width (GdkTexture *texture) * gdk_texture_get_height: * @texture: a #GdkTexture * - * Returns the height of the @texture. + * Returns the height of the @texture, in pixels. * * Returns: the height of the #GdkTexture */ @@ -573,4 +579,3 @@ gdk_texture_save_to_png (GdkTexture *texture, return result; } - From 838d0924b91b9ac8c43fc16ff3a3f18b81107358 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 29 Oct 2020 13:28:03 -0400 Subject: [PATCH 06/13] docs: Tweak GdkPaintable docs Minor additions here and there. --- gdk/gdkpaintable.c | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/gdk/gdkpaintable.c b/gdk/gdkpaintable.c index 6d1f176b4d..a1726401b0 100644 --- a/gdk/gdkpaintable.c +++ b/gdk/gdkpaintable.c @@ -35,7 +35,7 @@ void gtk_snapshot_pop (GdkSnapshot * @Short_description: An interface for a paintable region * @See_also: #ClutterContent, #GtkImage, #GdkTexture, #GtkSnapshot * - * #GdkPaintable is a simple interface used by GDK and GDK to represent + * #GdkPaintable is a simple interface used by GDK and GTK to represent * objects that can be painted anywhere at any size without requiring any * sort of layout. The interface is inspired by similar concepts elsewhere, * such as [ClutterContent](https://developer.gnome.org/clutter/stable/ClutterContent.html), @@ -347,22 +347,22 @@ gdk_paintable_get_intrinsic_height (GdkPaintable *paintable) * @paintable: a #GdkPaintable * * Gets the preferred aspect ratio the @paintable would like to be displayed at. - * The aspect ration is the width divided by the height, so a value of 0.5 means + * The aspect ratio is the width divided by the height, so a value of 0.5 means * that the @paintable prefers to be displayed twice as high as it is wide. * Consumers of this interface can use this to preserve aspect ratio when displaying - * this paintable. + * the paintable. * * This is a purely informational value and does not in any way limit the values * that may be passed to gdk_paintable_snapshot(). * - * Usually when a @paintable returns non-0 values from + * Usually when a @paintable returns nonzero values from * gdk_paintable_get_intrinsic_width() and gdk_paintable_get_intrinsic_height() * the aspect ratio should conform to those values, though that is not required. * - * If the @paintable does not have a preferred aspect ratio, it returns 0.0. + * If the @paintable does not have a preferred aspect ratio, it returns 0. * Negative values are never returned. * - * Returns: the intrinsic aspect ratio of @paintable or 0.0 if none. + * Returns: the intrinsic aspect ratio of @paintable or 0 if none. */ double gdk_paintable_get_intrinsic_aspect_ratio (GdkPaintable *paintable) @@ -379,9 +379,9 @@ gdk_paintable_get_intrinsic_aspect_ratio (GdkPaintable *paintable) * gdk_paintable_invalidate_contents: * @paintable: a #GdkPaintable * - * Called by implementations of #GdkPaintable to invalidate their contents. + * Called by implementations of #GdkPaintable to invalidate their contents. * Unless the contents are invalidated, implementations must guarantee that - * multiple calls to GdkPaintable::snapshot produce the same output. + * multiple calls of gdk_paintable_snapshot() produce the same output. * * This function will emit the #GdkPaintable::invalidate-contents signal. * @@ -401,9 +401,9 @@ gdk_paintable_invalidate_contents (GdkPaintable *paintable) * gdk_paintable_invalidate_size: * @paintable: a #GdkPaintable * - * Called by implementations of #GdkPaintable to invalidate their size. - * As long as the size is not invalidated, @paintable must return the same values - * for its width, height and intrinsic height. + * Called by implementations of #GdkPaintable to invalidate their size. + * As long as the size is not invalidated, @paintable must return the same + * values for its intrinsic width, height and aspect ratio. * * This function will emit the #GdkPaintable::invalidate-size signal. * @@ -435,7 +435,7 @@ gdk_paintable_invalidate_size (GdkPaintable *paintable) * @concrete_height: (out): will be set to the concrete height * computed. * - * Applies the sizing algorithm outlined in + * Applies the sizing algorithm outlined in * https://drafts.csswg.org/css-images-3/#default-sizing * to the given @paintable. See that link for more details. * From 9f71bdd0459119042049486bf556ba3abf9303ac Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 29 Oct 2020 13:36:26 -0400 Subject: [PATCH 07/13] docs: Cosmetics Make the GdkRGBA heading less repetitive. --- gdk/gdkrgba.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gdk/gdkrgba.c b/gdk/gdkrgba.c index fac9d2efa5..1de2bd45a9 100644 --- a/gdk/gdkrgba.c +++ b/gdk/gdkrgba.c @@ -32,10 +32,10 @@ /** * SECTION:rgba_colors + * @Title: GdkRGBA * @Short_description: RGBA colors - * @Title: RGBA Colors * - * #GdkRGBA is a convenient way to pass rgba colors around. + * #GdkRGBA is a convenient way to pass colors around. * It’s based on cairo’s way to deal with colors and mirrors its behavior. * All values are in the range from 0.0 to 1.0 inclusive. So the color * (0.0, 0.0, 0.0, 0.0) represents transparent black and From 2df382277de0a370adbb3b4b8bc8f81991efc473 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 29 Oct 2020 13:41:10 -0400 Subject: [PATCH 08/13] docs: Small additions for GdkCursor docs --- gdk/gdkcursor.c | 54 +++++++++++++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 22 deletions(-) diff --git a/gdk/gdkcursor.c b/gdk/gdkcursor.c index 354d3e2cd9..8fd33d1d7b 100644 --- a/gdk/gdkcursor.c +++ b/gdk/gdkcursor.c @@ -43,13 +43,13 @@ * * 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 + * to modify them later. 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 + * 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. @@ -59,16 +59,19 @@ * There are multiple ways to create cursors. The platform's own cursors * can be created with 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. + * 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() * 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, - * it will try the fallback cursor. Of course, 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 default cursor will be the ultimate fallback. + * 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 + * default cursor will be the ultimate fallback. */ /** @@ -175,40 +178,40 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class) object_class->finalize = gdk_cursor_finalize; g_object_class_install_property (object_class, - PROP_FALLBACK, - g_param_spec_object ("fallback", + PROP_FALLBACK, + g_param_spec_object ("fallback", P_("Fallback"), P_("Cursor image to fall back to if this cursor cannot be displayed"), GDK_TYPE_CURSOR, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); g_object_class_install_property (object_class, - PROP_HOTSPOT_X, - g_param_spec_int ("hotspot-x", + PROP_HOTSPOT_X, + g_param_spec_int ("hotspot-x", P_("Hotspot X"), P_("Horizontal offset of the cursor hotspot"), 0, G_MAXINT, 0, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); g_object_class_install_property (object_class, - PROP_HOTSPOT_Y, - g_param_spec_int ("hotspot-y", + PROP_HOTSPOT_Y, + g_param_spec_int ("hotspot-y", P_("Hotspot Y"), P_("Vertical offset of the cursor hotspot"), 0, G_MAXINT, 0, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); g_object_class_install_property (object_class, - PROP_NAME, - g_param_spec_string ("name", + PROP_NAME, + g_param_spec_string ("name", P_("Name"), P_("Name of this cursor"), NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); g_object_class_install_property (object_class, - PROP_TEXTURE, - g_param_spec_object ("texture", + PROP_TEXTURE, + g_param_spec_object ("texture", P_("Texture"), P_("The texture displayed by this cursor"), GDK_TYPE_TEXTURE, @@ -345,8 +348,8 @@ gdk_cursor_new_from_name (const char *name, */ GdkCursor * gdk_cursor_new_from_texture (GdkTexture *texture, - int hotspot_x, - int hotspot_y, + int hotspot_x, + int hotspot_y, GdkCursor *fallback) { g_return_val_if_fail (GDK_IS_TEXTURE (texture), NULL); @@ -390,7 +393,7 @@ gdk_cursor_get_fallback (GdkCursor *cursor) * @cursor: a #GdkCursor. * * Returns the name of the cursor. If the cursor is not a named cursor, %NULL - * will be returned and the GdkCursor::texture property will be set. + * will be returned. * * Returns: (transfer none) (nullable): the name of the cursor or %NULL if it is not * a named cursor @@ -408,7 +411,7 @@ gdk_cursor_get_name (GdkCursor *cursor) * @cursor: a #GdkCursor. * * Returns the texture for the cursor. If the cursor is a named cursor, %NULL - * will be returned and the GdkCursor::name property will be set. + * will be returned. * * Returns: (transfer none) (nullable): the texture for cursor or %NULL if it is a * named cursor @@ -428,6 +431,10 @@ gdk_cursor_get_texture (GdkCursor *cursor) * Returns the horizontal offset of the hotspot. The hotspot indicates the * pixel that will be directly above the cursor. * + * Note that named cursors may have a nonzero hotspot, but this function + * will only return the hotspot position for cursors created with + * gdk_cursor_new_from_texture(). + * * Returns: the horizontal offset of the hotspot or 0 for named cursors */ int @@ -445,6 +452,10 @@ gdk_cursor_get_hotspot_x (GdkCursor *cursor) * Returns the vertical offset of the hotspot. The hotspot indicates the * pixel that will be directly above the cursor. * + * Note that named cursors may have a nonzero hotspot, but this function + * will only return the hotspot position for cursors created with + * gdk_cursor_new_from_texture(). + * * Returns: the vertical offset of the hotspot or 0 for named cursors */ int @@ -454,4 +465,3 @@ gdk_cursor_get_hotspot_y (GdkCursor *cursor) return cursor->hotspot_y; } - From d2adbad408936fa9b40c95cfd6ce040d0d2d1360 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 29 Oct 2020 13:57:00 -0400 Subject: [PATCH 09/13] docs: Tweak frame clock docs --- gdk/gdkframeclock.c | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/gdk/gdkframeclock.c b/gdk/gdkframeclock.c index 4d05da780c..5e4492744c 100644 --- a/gdk/gdkframeclock.c +++ b/gdk/gdkframeclock.c @@ -29,11 +29,11 @@ /** * SECTION:gdkframeclock - * @Short_description: Frame clock syncs painting to a window or display - * @Title: Frame clock + * @Title: GdkFrameClock + * @Short_description: Synchronizes painting to a surface * - * A #GdkFrameClock tells the application when to update and repaint a - * window. This may be synced to the vertical refresh rate of the + * A #GdkFrameClock tells the application when to update and repaint + * a surface. This may be synced to the vertical refresh rate of the * monitor, for example. Even when the frame clock uses a simple timer * rather than a hardware-based vertical sync, the frame clock helps * because it ensures everything paints at the same time (reducing the From 3afd5d7a892cedd4d48e9c88e7864e2ca1cb647d Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 29 Oct 2020 13:57:22 -0400 Subject: [PATCH 10/13] docs: Tweak GdkSurface docs Add more details, and refer to the GdkToplevel / GdkPopup docs. --- gdk/gdksurface.c | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/gdk/gdksurface.c b/gdk/gdksurface.c index c32c17262b..43d3371609 100644 --- a/gdk/gdksurface.c +++ b/gdk/gdksurface.c @@ -55,10 +55,17 @@ * SECTION:gdksurface * @Short_description: Onscreen display areas in the target window system * @Title: Surfaces + * @See_also: #GdkToplevel, #GdkPopup * * A #GdkSurface is a (usually) rectangular region on the screen. - * It’s a low-level object, used to implement high-level objects such as - * #GtkWindow on the GTK level. + * It’s a low-level object, used to implement high-level objects + * such as #GtkWindow or #GtkDialog in GTK. + * + * The surfaces you see in practice are either #GdkToplevel or + * #GdkPopup, and those interfaces provide much of the required + * API to interact with these surfaces. Other, more specialized + * surface types exist, but you will rarely interact with them + * directly. */ /** From 94305f248b04285ed3386f74f220c7a8b109424a Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 29 Oct 2020 14:00:13 -0400 Subject: [PATCH 11/13] docs: Tweak GdkPopup docs --- gdk/gdkpopup.c | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/gdk/gdkpopup.c b/gdk/gdkpopup.c index 91772d3c18..375a0fcb92 100644 --- a/gdk/gdkpopup.c +++ b/gdk/gdkpopup.c @@ -27,9 +27,13 @@ * SECTION:gdkpopup * @Short_description: Interface for popup surfaces * @Title: Popups + * @See_also: #GdkToplevel, #GdkSurface * * A #GdkPopup is a surface that is attached to another surface, - * and is positioned relative to it. + * called its #GdkPopup:parent, and is positioned relative to it. + * + * #GdkPopups are typically used to implement menus and similar popups. + * They can be modal, which is indicated by the #GdkPopup:autohide property. */ G_DEFINE_INTERFACE (GdkPopup, gdk_popup, GDK_TYPE_SURFACE) From ce78d0c301bbfba5bf3c4b7a3fccd608a662b60f Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 29 Oct 2020 14:00:24 -0400 Subject: [PATCH 12/13] docs: Tweak GdkToplevel docs --- gdk/gdktoplevel.c | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/gdk/gdktoplevel.c b/gdk/gdktoplevel.c index 38a527c1ba..34328db10d 100644 --- a/gdk/gdktoplevel.c +++ b/gdk/gdktoplevel.c @@ -30,8 +30,14 @@ * SECTION:gdktoplevel * @Short_description: Interface for toplevel surfaces * @Title: Toplevels + * @See_also: #GdkSurface, #GdkPopup * * A #GdkToplevel is a freestanding toplevel surface. + * + * The #GdkToplevel interface provides useful APIs for + * interacting with the windowing system, such as controlling + * maximization and size of the surface, setting icons and + * transient parents for dialogs. */ G_DEFINE_INTERFACE (GdkToplevel, gdk_toplevel, GDK_TYPE_SURFACE) From 3164f328b56488625c13587473b6fbe3000fe55d Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 29 Oct 2020 14:19:12 -0400 Subject: [PATCH 13/13] docs: Some restructuring Give the GDK docs some more structure. --- docs/reference/gdk/gdk4-docs.xml | 35 ++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/docs/reference/gdk/gdk4-docs.xml b/docs/reference/gdk/gdk4-docs.xml index 3e1ed5f974..50b018be9d 100644 --- a/docs/reference/gdk/gdk4-docs.xml +++ b/docs/reference/gdk/gdk4-docs.xml @@ -16,14 +16,16 @@ - + API Reference - +
+ +
@@ -32,16 +34,24 @@ - - +
+ + +
- +
+ +
- +
+ +
- - - +
+ + + +
@@ -50,13 +60,16 @@ - + + + GDK Platform Support + - + Index of all symbols