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 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..efbc18fc5b 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 @@ -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/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. */ /** 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; } - 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 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 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. * 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) 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/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 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. */ /** 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; } - 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) 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 b511233cdf..92cfa622eb 100644 --- a/gdk/macos/GdkMacosWindow.c +++ b/gdk/macos/GdkMacosWindow.c @@ -33,6 +33,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__ */ 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