diff --git a/gdk/gdkapplaunchcontext.c b/gdk/gdkapplaunchcontext.c index b34cdaad80..30e9ee3bd0 100644 --- a/gdk/gdkapplaunchcontext.c +++ b/gdk/gdkapplaunchcontext.c @@ -26,18 +26,17 @@ /** - * SECTION:gdkapplaunchcontext - * @Short_description: Startup notification for applications - * @Title: Application launching + * GdkAppLaunchContext: * - * GdkAppLaunchContext is an implementation of #GAppLaunchContext that - * handles launching an application in a graphical context. It provides - * startup notification and allows to launch applications on a specific - * screen or workspace. + * `GdkAppLaunchContext` handles launching an application in a graphical context. + * + * It is an implementation of `GAppLaunchContext` that provides startup + * notification and allows to launch applications on a specific screen + * or workspace. * * ## Launching an application * - * |[ + * ```c * GdkAppLaunchContext *context; * * context = gdk_display_get_app_launch_context (display); @@ -49,14 +48,7 @@ * g_warning ("Launching failed: %s\n", error->message); * * g_object_unref (context); - * ]| - */ - -/** - * GdkAppLaunchContext: - * - * The GdkAppLaunchContext struct contains only private fields - * and should not be accessed directly. + * ``` */ static void gdk_app_launch_context_finalize (GObject *object); @@ -175,9 +167,9 @@ gdk_app_launch_context_get_display_name (GAppLaunchContext *context, /** * gdk_app_launch_context_get_display: - * @context: a #GdkAppLaunchContext + * @context: a `GdkAppLaunchContext` * - * Gets the #GdkDisplay that @context is for. + * Gets the `GdkDisplay` that @context is for. * * Returns: (transfer none): the display of @context */ @@ -191,11 +183,12 @@ gdk_app_launch_context_get_display (GdkAppLaunchContext *context) /** * gdk_app_launch_context_set_desktop: - * @context: a #GdkAppLaunchContext + * @context: a `GdkAppLaunchContext` * @desktop: the number of a workspace, or -1 * - * Sets the workspace on which applications will be launched when - * using this context when running under a window manager that + * Sets the workspace on which applications will be launched. + * + * This only works when running under a window manager that * supports multiple workspaces, as described in the * [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec). * @@ -214,11 +207,13 @@ gdk_app_launch_context_set_desktop (GdkAppLaunchContext *context, /** * gdk_app_launch_context_set_timestamp: - * @context: a #GdkAppLaunchContext + * @context: a `GdkAppLaunchContext` * @timestamp: a timestamp * - * Sets the timestamp of @context. The timestamp should ideally - * be taken from the event that triggered the launch. + * Sets the timestamp of @context. + * + * The timestamp should ideally be taken from the event that + * triggered the launch. * * Window managers can use this information to avoid moving the * focus to the newly launched application when the user is busy @@ -236,7 +231,7 @@ gdk_app_launch_context_set_timestamp (GdkAppLaunchContext *context, /** * gdk_app_launch_context_set_icon: - * @context: a #GdkAppLaunchContext + * @context: a `GdkAppLaunchContext` * @icon: (allow-none): a #GIcon, or %NULL * * Sets the icon for applications that are launched with this @@ -245,7 +240,7 @@ gdk_app_launch_context_set_timestamp (GdkAppLaunchContext *context, * Window Managers can use this information when displaying startup * notification. * - * See also gdk_app_launch_context_set_icon_name(). + * See also [method@Gdk.AppLaunchContext.set_icon_name]. */ void gdk_app_launch_context_set_icon (GdkAppLaunchContext *context, @@ -266,16 +261,17 @@ gdk_app_launch_context_set_icon (GdkAppLaunchContext *context, /** * gdk_app_launch_context_set_icon_name: - * @context: a #GdkAppLaunchContext + * @context: a `GdkAppLaunchContext` * @icon_name: (allow-none): an icon name, or %NULL * * Sets the icon for applications that are launched with this context. + * * The @icon_name will be interpreted in the same way as the Icon field - * in desktop files. See also gdk_app_launch_context_set_icon(). + * in desktop files. See also [method@Gdk.AppLaunchContext.set_icon()]. * * If both @icon and @icon_name are set, the @icon_name takes priority. * If neither @icon or @icon_name is set, the icon is taken from either - * the file that is passed to launched application or from the #GAppInfo + * the file that is passed to launched application or from the `GAppInfo` * for the launched application itself. */ void diff --git a/gdk/gdkcairocontext.c b/gdk/gdkcairocontext.c index cad9de9833..bfb7c24452 100644 --- a/gdk/gdkcairocontext.c +++ b/gdk/gdkcairocontext.c @@ -27,24 +27,15 @@ #include "gdkcairo.h" #include "gdkinternals.h" -/** - * SECTION:gdkcairocontext - * @Title: GdkCairoContext - * @Short_description: Cairo draw context - * - * #GdkCairoContext is an object representing the platform-specific - * draw context. - * - * #GdkCairoContexts are created for a #GdkDisplay using - * gdk_surface_create_cairo_context(), and the context can then be used - * to draw on that #GdkSurface. - */ - /** * GdkCairoContext: * - * The GdkCairoContext struct contains only private fields and should not - * be accessed directly. + * `GdkCairoContext` is an object representing the platform-specific + * draw context. + * + * `GdkCairoContext`s are created for a surface using + * [method@Gdk.Surface.create_cairo_context], and the context can then be used + * to draw on that surface. */ typedef struct _GdkCairoContextPrivate GdkCairoContextPrivate; @@ -70,15 +61,17 @@ gdk_cairo_context_init (GdkCairoContext *self) * gdk_cairo_context_cairo_create: * @self: a #GdkCairoContext that is currently drawing * - * Retrieves a Cairo context to be used to draw on the #GdkSurface - * of @context. A call to gdk_draw_context_begin_frame() with this + * Retrieves a Cairo context to be used to draw on the `GdkSurface` + * of @context. + * + * A call to [method@Gdk.DrawContext.begin_frame] with this * @context must have been done or this function will return %NULL. * * The returned context is guaranteed to be valid until - * gdk_draw_context_end_frame() is called. + * [method@Gdk.DrawContext.end_frame] is called. * * Returns: (transfer full) (nullable): a Cairo context to be used - * to draw the contents of the #GdkSurface. %NULL is returned + * to draw the contents of the `GdkSurface`. %NULL is returned * when @context is not drawing. */ cairo_t * diff --git a/gdk/gdkclipboard.c b/gdk/gdkclipboard.c index 8ed2acef6b..783bd75a62 100644 --- a/gdk/gdkclipboard.c +++ b/gdk/gdkclipboard.c @@ -32,34 +32,26 @@ #include -/** - * SECTION:gdkclipboard - * @Short_description: Share data between applications for Copy-and-Paste - * @Title: Clipboards - * @See_also: #GdkContentProvider, #GdkContentFormats - * - * The #GdkClipboard object represents a clipboard of data shared - * between different applications or between different parts of - * the same application. - * - * To get a GdkClipboard object, use gdk_display_get_clipboard() or - * gdk_display_get_primary_clipboard(). You can find out about the data that - * is currently available in a clipboard using gdk_clipboard_get_formats(). - * - * To make text or image data available in a clipboard, use gdk_clipboard_set_text() or - * gdk_clipboard_set_texture(). For other data, you can use gdk_clipboard_set_content(), - * which takes a #GdkContentProvider object. - * - * To read textual or image data from a clipboard, use gdk_clipboard_read_text_async() or - * gdk_clipboard_read_texture_async(). For other data, use gdk_clipboard_read_async(), - * which provides a #GInputStream object. - */ - /** * GdkClipboard: * - * The GdkClipboard struct contains only private fields and should not be - * accessed directly. + * The `GdkClipboard` object represents data shared between applications or + * inside an application. + * + * To get a `GdkClipboard` object, use [method@Gdk.Display.get_clipboard] or + * [method@Gdk.Display.get_primary_clipboard]. You can find out about the data + * that is currently available in a clipboard using + * [method@Gdk.Clipboard.get_formats]. + * + * To make text or image data available in a clipboard, use + * [method@Gdk.Clipboard.set_text] or [method@Gdk.Clipboard.set_texture]. + * For other data, you can use [method@Gdk.Clipboard.set_content], which + * takes a [class@Gdk.ContentProvider] object. + * + * To read textual or image data from a clipboard, use + * [method@Gdk.Clipboard.read_text_async] or + * [method@Gdk.Clipboard.read_texture_async]. For other data, use + * [method@Gdk.Clipboard.read_async], which provides a `GInputStream` object. */ typedef struct _GdkClipboardPrivate GdkClipboardPrivate; @@ -362,7 +354,7 @@ gdk_clipboard_class_init (GdkClipboardClass *class) /** * GdkClipboard:display: * - * The #GdkDisplay that the clipboard belongs to. + * The `GdkDisplay` that the clipboard belongs to. */ properties[PROP_DISPLAY] = g_param_spec_object ("display", @@ -405,7 +397,7 @@ gdk_clipboard_class_init (GdkClipboardClass *class) /** * GdkClipboard:content: * - * The #GdkContentProvider or %NULL if the clipboard is empty or contents are + * The `GdkContentProvider` or %NULL if the clipboard is empty or contents are * provided otherwise. */ properties[PROP_CONTENT] = @@ -421,7 +413,7 @@ gdk_clipboard_class_init (GdkClipboardClass *class) * GdkClipboard::changed: * @clipboard: the object on which the signal was emitted * - * The ::changed signal is emitted when the clipboard changes ownership. + * Emitted when the clipboard changes ownership. */ signals[CHANGED] = g_signal_new ("changed", @@ -445,12 +437,12 @@ gdk_clipboard_init (GdkClipboard *clipboard) /** * gdk_clipboard_get_display: - * @clipboard: a #GdkClipboard + * @clipboard: a `GdkClipboard` * - * Gets the #GdkDisplay that the clipboard was created for. + * Gets the `GdkDisplay` that the clipboard was created for. * - * Returns: (transfer none): a #GdkDisplay - **/ + * Returns: (transfer none): a `GdkDisplay` + */ GdkDisplay * gdk_clipboard_get_display (GdkClipboard *clipboard) { @@ -463,12 +455,12 @@ gdk_clipboard_get_display (GdkClipboard *clipboard) /** * gdk_clipboard_get_formats: - * @clipboard: a #GdkClipboard + * @clipboard: a `GdkClipboard` * * Gets the formats that the clipboard can provide its current contents in. * * Returns: (transfer none): The formats of the clipboard - **/ + */ GdkContentFormats * gdk_clipboard_get_formats (GdkClipboard *clipboard) { @@ -481,16 +473,18 @@ gdk_clipboard_get_formats (GdkClipboard *clipboard) /** * gdk_clipboard_is_local: - * @clipboard: a #GdkClipboard + * @clipboard: a `GdkClipboard` * - * Returns if the clipboard is local. A clipboard is considered local if it was - * last claimed by the running application. + * Returns if the clipboard is local. * - * Note that gdk_clipboard_get_content() may return %NULL even on a local - * clipboard. In this case the clipboard is empty. + * A clipboard is considered local if it was last claimed + * by the running application. + * + * Note that [method@Gdk.Clipboard.get_content] may return %NULL + * even on a local clipboard. In this case the clipboard is empty. * * Returns: %TRUE if the clipboard is local - **/ + */ gboolean gdk_clipboard_is_local (GdkClipboard *clipboard) { @@ -503,15 +497,16 @@ gdk_clipboard_is_local (GdkClipboard *clipboard) /** * gdk_clipboard_get_content: - * @clipboard: a #GdkClipboard + * @clipboard: a `GdkClipboard` * - * Returns the #GdkContentProvider currently set on @clipboard. If the - * @clipboard is empty or its contents are not owned by the current process, - * %NULL will be returned. + * Returns the `GdkContentProvider` currently set on @clipboard. + * + * If the @clipboard is empty or its contents are not owned by the + * current process, %NULL will be returned. * * Returns: (transfer none) (nullable): The content of a clipboard or %NULL * if the clipboard does not maintain any content. - **/ + */ GdkContentProvider * gdk_clipboard_get_content (GdkClipboard *clipboard) { @@ -524,20 +519,26 @@ gdk_clipboard_get_content (GdkClipboard *clipboard) /** * gdk_clipboard_store_async: - * @clipboard: a #GdkClipboard - * @io_priority: the [I/O priority][io-priority] - * of the request. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @clipboard: a `GdkClipboard` + * @io_priority: the I/O priority of the request. + * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function * - * Asynchronously instructs the @clipboard to store its contents remotely to - * preserve them for later usage. If the clipboard is not local, this function - * does nothing but report success. + * Asynchronously instructs the @clipboard to store its contents remotely. * - * This function is called automatically when gtk_main() or #GtkApplication - * exit, so you likely don't need to call it. - **/ + * If the clipboard is not local, this function does nothing but report success. + * + * The @callback must call [method@Gdk.Clipboard.store_finish]. + * + * The purpose of this call is to preserve clipboard contents beyond the + * lifetime of an application, so this function is typically called on + * exit. Depending on the platform, the functionality may not be available + * unless a "clipboard manager" is running. + * + * This function is called automatically when a [class@Gtk.Application] is + * shut down, so you likely don't need to call it. + */ void gdk_clipboard_store_async (GdkClipboard *clipboard, int io_priority, @@ -571,15 +572,16 @@ gdk_clipboard_store_async (GdkClipboard *clipboard, /** * gdk_clipboard_store_finish: - * @clipboard: a #GdkClipboard - * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * @clipboard: a `GdkClipboard` + * @result: a `GAsyncResult` + * @error: a `GError` location to store the error occurring, or %NULL to ignore. * - * Finishes an asynchronous clipboard store started with gdk_clipboard_store_async(). + * Finishes an asynchronous clipboard store. + * + * See [method@Gdk.Clipboard.store_async]. * * Returns: %TRUE if storing was successful. - **/ + */ gboolean gdk_clipboard_store_finish (GdkClipboard *clipboard, GAsyncResult *result, @@ -632,22 +634,22 @@ gdk_clipboard_read_internal (GdkClipboard *clipboard, /** * gdk_clipboard_read_async: - * @clipboard: a #GdkClipboard + * @clipboard: a `GdkClipboard` * @mime_types: a %NULL-terminated array of mime types to choose from - * @io_priority: the [I/O priority][io-priority] - * of the request. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @io_priority: the I/O priority of the request + * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously requests an input stream to read the @clipboard's - * contents from. When the operation is finished @callback will be called. - * You can then call gdk_clipboard_read_finish() to get the result of the - * operation. + * contents from. + * + * When the operation is finished @callback will be called. You must then + * call [method@Gdk.Clipboard.read_finish] to get the result of the operation. * * The clipboard will choose the most suitable mime type from the given list - * to fulfill the request, preferring the ones listed first. - **/ + * to fulfill the request, preferring the ones listed first. + */ void gdk_clipboard_read_async (GdkClipboard *clipboard, const char **mime_types, @@ -672,17 +674,18 @@ gdk_clipboard_read_async (GdkClipboard *clipboard, /** * gdk_clipboard_read_finish: - * @clipboard: a #GdkClipboard - * @result: a #GAsyncResult + * @clipboard: a `GdkClipboard` + * @result: a `GAsyncResult` * @out_mime_type: (out) (allow-none) (transfer none): pointer to store * the chosen mime type in or %NULL - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * @error: a `GError` location to store the error occurring, or %NULL to ignore. * - * Finishes an asynchronous clipboard read started with gdk_clipboard_read_async(). + * Finishes an asynchronous clipboard read. * - * Returns: (transfer full) (nullable): a #GInputStream or %NULL on error. - **/ + * See [method@Gdk.Clipboard.read_async]. + * + * Returns: (transfer full) (nullable): a `GInputStream` or %NULL on error. + */ GInputStream * gdk_clipboard_read_finish (GdkClipboard *clipboard, GAsyncResult *result, @@ -827,23 +830,23 @@ gdk_clipboard_read_value_internal (GdkClipboard *clipboard, /** * gdk_clipboard_read_value_async: - * @clipboard: a #GdkClipboard - * @type: a #GType to read - * @io_priority: the [I/O priority][io-priority] - * of the request. + * @clipboard: a `GdkClipboard` + * @type: a `GType` to read + * @io_priority: the I/O priority of the request * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously request the @clipboard contents converted to the given - * @type. When the operation is finished @callback will be called. - * You can then call gdk_clipboard_read_value_finish() to get the resulting - * #GValue. + * @type. * - * For local clipboard contents that are available in the given #GType, the - * value will be copied directly. Otherwise, GDK will try to use - * gdk_content_deserialize_async() to convert the clipboard's data. - **/ + * When the operation is finished @callback will be called. You must then call + * [method@Gdk.Clipboard.read_value_finish] to get the resulting `GValue`. + * + * For local clipboard contents that are available in the given `GType`, + * the value will be copied directly. Otherwise, GDK will try to use + * [func@content_deserialize_async] to convert the clipboard's data. + */ void gdk_clipboard_read_value_async (GdkClipboard *clipboard, GType type, @@ -867,16 +870,16 @@ gdk_clipboard_read_value_async (GdkClipboard *clipboard, /** * gdk_clipboard_read_value_finish: - * @clipboard: a #GdkClipboard - * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * @clipboard: a `GdkClipboard` + * @result: a `GAsyncResult` + * @error: a GError` location to store the error occurring, or %NULL to ignore * - * Finishes an asynchronous clipboard read started with - * gdk_clipboard_read_value_async(). + * Finishes an asynchronous clipboard read. * - * Returns: (transfer none): a #GValue containing the result. - **/ + * See [method@Gdk.Clipboard.read_value_async]. + * + * Returns: (transfer none): a `GValue` containing the result. + */ const GValue * gdk_clipboard_read_value_finish (GdkClipboard *clipboard, GAsyncResult *result, @@ -891,19 +894,20 @@ gdk_clipboard_read_value_finish (GdkClipboard *clipboard, /** * gdk_clipboard_read_texture_async: - * @clipboard: a #GdkClipboard - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @clipboard: a `GdkClipboard` + * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function * - * Asynchronously request the @clipboard contents converted to a #GdkPixbuf. - * When the operation is finished @callback will be called. You can then - * call gdk_clipboard_read_texture_finish() to get the result. + * Asynchronously request the @clipboard contents converted to a `GdkPixbuf`. * - * This is a simple wrapper around gdk_clipboard_read_value_async(). Use - * that function or gdk_clipboard_read_async() directly if you need more - * control over the operation. - **/ + * When the operation is finished @callback will be called. You must then + * call [method@Gdk.Clipboard.read_texture_finish] to get the result. + * + * This is a simple wrapper around [method@Gdk.Clipboard.read_value_async]. + * Use that function or [methos@Gdk.Clipboard.read_async] directly if you + * need more control over the operation. + */ void gdk_clipboard_read_texture_async (GdkClipboard *clipboard, GCancellable *cancellable, @@ -925,16 +929,16 @@ gdk_clipboard_read_texture_async (GdkClipboard *clipboard, /** * gdk_clipboard_read_texture_finish: - * @clipboard: a #GdkClipboard - * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * @clipboard: a `GdkClipboard` + * @result: a `GAsyncResult` + * @error: a `GError` location to store the error occurring, or %NULL to ignore * - * Finishes an asynchronous clipboard read started with - * gdk_clipboard_read_texture_async(). + * Finishes an asynchronous clipboard read. * - * Returns: (transfer full) (nullable): a new #GdkTexture or %NULL on error. - **/ + * See [method@Gdk.Clipboard.read_texture_async]. + * + * Returns: (transfer full) (nullable): a new `GdkTexture` or %NULL on error + */ GdkTexture * gdk_clipboard_read_texture_finish (GdkClipboard *clipboard, GAsyncResult *result, @@ -955,19 +959,20 @@ gdk_clipboard_read_texture_finish (GdkClipboard *clipboard, /** * gdk_clipboard_read_text_async: - * @clipboard: a #GdkClipboard - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @clipboard: a `GdkClipboard` + * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously request the @clipboard contents converted to a string. - * When the operation is finished @callback will be called. You can then - * call gdk_clipboard_read_text_finish() to get the result. * - * This is a simple wrapper around gdk_clipboard_read_value_async(). Use - * that function or gdk_clipboard_read_async() directly if you need more - * control over the operation. - **/ + * When the operation is finished @callback will be called. You must then + * call [method@Gdk.Clipboard.read_text_finish] to get the result. + * + * This is a simple wrapper around [method@Gdk.Clipboard.read_value_async]. + * Use that function or [method@Gdk.Clipboard.read_async] directly if you + * need more control over the operation. + */ void gdk_clipboard_read_text_async (GdkClipboard *clipboard, GCancellable *cancellable, @@ -989,16 +994,16 @@ gdk_clipboard_read_text_async (GdkClipboard *clipboard, /** * gdk_clipboard_read_text_finish: - * @clipboard: a #GdkClipboard - * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * @clipboard: a `GdkClipboard` + * @result: a `GAsyncResult` + * @error: a `GError` location to store the error occurring, or %NULL to ignore * - * Finishes an asynchronous clipboard read started with - * gdk_clipboard_read_text_async(). + * Finishes an asynchronous clipboard read. * - * Returns: (transfer full) (nullable): a new string or %NULL on error. - **/ + * See [method@Gdk.Clipboard.read_text_async]. + * + * Returns: (transfer full) (nullable): a new string or %NULL on error + */ char * gdk_clipboard_read_text_finish (GdkClipboard *clipboard, GAsyncResult *result, @@ -1188,13 +1193,14 @@ gdk_clipboard_claim_remote (GdkClipboard *clipboard, /** * gdk_clipboard_set_content: - * @clipboard: a #GdkClipboard + * @clipboard: a `GdkClipboard` * @provider: (transfer none) (allow-none): the new contents of @clipboard or * %NULL to clear the clipboard * - * Sets a new content provider on @clipboard. The clipboard will claim the - * #GdkDisplay's resources and advertise these new contents to other - * applications. + * Sets a new content provider on @clipboard. + * + * The clipboard will claim the `GdkDisplay`'s resources and advertise + * these new contents to other applications. * * In the rare case of a failure, this function will return %FALSE. The * clipboard will then continue reporting its old contents and ignore @@ -1205,7 +1211,7 @@ gdk_clipboard_claim_remote (GdkClipboard *clipboard, * transfer the contents and then request that format from @provider. * * Returns: %TRUE if setting the clipboard succeeded - **/ + */ gboolean gdk_clipboard_set_content (GdkClipboard *clipboard, GdkContentProvider *provider) @@ -1242,16 +1248,19 @@ gdk_clipboard_set_content (GdkClipboard *clipboard, /** * gdk_clipboard_set: - * @clipboard: a #GdkClipboard + * @clipboard: a `GdkClipboard` * @type: type of value to set * @...: value contents conforming to @type * - * Sets the clipboard to contain the value collected from the given - * varargs. - **/ + * Sets the clipboard to contain the value collected from the given varargs. + * + * ```c + * gdk_clipboard_set (clipboard, GTK_TYPE_TEXT_BUFFER, buffer); + * ``` + */ void -gdk_clipboard_set (GdkClipboard *clipboard, - GType type, +gdk_clipboard_set (GdkClipboard *clipboard, + GType type, ...) { va_list args; @@ -1265,13 +1274,12 @@ gdk_clipboard_set (GdkClipboard *clipboard, /** * gdk_clipboard_set_valist: (skip) - * @clipboard: a #GdkClipboard + * @clipboard: a `GdkClipboard` * @type: type of value to set * @args: varargs containing the value of @type * - * Sets the clipboard to contain the value collected from the given - * @args. - **/ + * Sets the clipboard to contain the value collected from the given @args. + */ void gdk_clipboard_set_valist (GdkClipboard *clipboard, GType type, @@ -1301,11 +1309,11 @@ gdk_clipboard_set_valist (GdkClipboard *clipboard, /** * gdk_clipboard_set_value: (rename-to gdk_clipboard_set) - * @clipboard: a #GdkClipboard - * @value: a #GValue to set + * @clipboard: a `GdkClipboard` + * @value: a `GValue` to set * * Sets the @clipboard to contain the given @value. - **/ + */ void gdk_clipboard_set_value (GdkClipboard *clipboard, const GValue *value) @@ -1323,11 +1331,11 @@ gdk_clipboard_set_value (GdkClipboard *clipboard, /** * gdk_clipboard_set_text: (skip) - * @clipboard: a #GdkClipboard + * @clipboard: a `GdkClipboard` * @text: Text to put into the clipboard * * Puts the given @text into the clipboard. - **/ + */ void gdk_clipboard_set_text (GdkClipboard *clipboard, const char *text) @@ -1339,11 +1347,11 @@ gdk_clipboard_set_text (GdkClipboard *clipboard, /** * gdk_clipboard_set_texture: (skip) - * @clipboard: a #GdkClipboard - * @texture: a #GdkTexture to put into the clipboard + * @clipboard: a `GdkClipboard` + * @texture: a `GdkTexture` to put into the clipboard * * Puts the given @texture into the clipboard. - **/ + */ void gdk_clipboard_set_texture (GdkClipboard *clipboard, GdkTexture *texture) @@ -1353,4 +1361,3 @@ gdk_clipboard_set_texture (GdkClipboard *clipboard, gdk_clipboard_set (clipboard, GDK_TYPE_TEXTURE, texture); } - diff --git a/gdk/gdkcontentdeserializer.c b/gdk/gdkcontentdeserializer.c index a61f933273..42f77c0078 100644 --- a/gdk/gdkcontentdeserializer.c +++ b/gdk/gdkcontentdeserializer.c @@ -30,13 +30,19 @@ /** - * SECTION:gdkcontentdeserializer - * @Short_description: Deserialize content for transfer - * @Title: GdkContentDeserializer - * @See_also: #GdkContentSerializer + * GdkContentDeserializer: * - * A GdkContentDeserializer is used to deserialize content received via + * A `GdkContentDeserializer` is used to deserialize content received via * inter-application data transfers. + * + * The `GdkContentDeserializer` transforms serialized content that is + * identified by a mime type into an object identified by a GType. + * + * GTK provides serializers and deserializers for common data types + * such as text, colors, images or file lists. To register your own + * deserialization functions, use [func@content_register_deserializer]. + * + * Also see [class@Gdk.ContentSerializer]. */ typedef struct _Deserializer Deserializer; @@ -166,7 +172,7 @@ gdk_content_deserializer_run (const char *mime_type, /** * gdk_content_deserializer_get_mime_type: - * @deserializer: a #GdkContentDeserializer + * @deserializer: a `GdkContentDeserializer` * * Gets the mime type to deserialize from. * @@ -182,7 +188,7 @@ gdk_content_deserializer_get_mime_type (GdkContentDeserializer *deserializer) /** * gdk_content_deserializer_get_gtype: - * @deserializer: a #GdkContentDeserializer + * @deserializer: a `GdkContentDeserializer` * * Gets the GType to create an instance of. * @@ -198,11 +204,11 @@ gdk_content_deserializer_get_gtype (GdkContentDeserializer *deserializer) /** * gdk_content_deserializer_get_value: - * @deserializer: a #GdkContentDeserializer + * @deserializer: a `GdkContentDeserializer` * - * Gets the #GValue to store the deserialized object in. + * Gets the `GValue` to store the deserialized object in. * - * Returns: (transfer none): the #GValue for the current operation + * Returns: (transfer none): the `GValue` for the current operation */ GValue * gdk_content_deserializer_get_value (GdkContentDeserializer *deserializer) @@ -214,9 +220,11 @@ gdk_content_deserializer_get_value (GdkContentDeserializer *deserializer) /** * gdk_content_deserializer_get_input_stream: - * @deserializer: a #GdkContentDeserializer + * @deserializer: a `GdkContentDeserializer` * - * Gets the input stream that was passed to gdk_content_deserialize_async(). + * Gets the input stream for the current operation. + * + * This is the stream that was passed to [func@content_deserialize_async]. * * Returns: (transfer none): the input stream for the current operation */ @@ -230,11 +238,13 @@ gdk_content_deserializer_get_input_stream (GdkContentDeserializer *deserializer) /** * gdk_content_deserializer_get_priority: - * @deserializer: a #GdkContentDeserializer + * @deserializer: a `GdkContentDeserializer` * - * Gets the io priority that was passed to gdk_content_deserialize_async(). + * Gets the I/O priority for the current operation. * - * Returns: the io priority for the current operation + * This is the priority that was passed to [funccontent_deserialize_async]. + * + * Returns: the I/O priority for the current operation */ int gdk_content_deserializer_get_priority (GdkContentDeserializer *deserializer) @@ -246,9 +256,11 @@ gdk_content_deserializer_get_priority (GdkContentDeserializer *deserializer) /** * gdk_content_deserializer_get_cancellable: - * @deserializer: a #GdkContentDeserializer + * @deserializer: a `GdkContentDeserializer` * - * Gets the cancellable that was passed to gdk_content_deserialize_async(). + * Gets the cancellable for the current operation. + * + * This is the `GCancellable` that was passed to [func@content_deserialize_async]. * * Returns: (transfer none): the cancellable for the current operation */ @@ -262,7 +274,7 @@ gdk_content_deserializer_get_cancellable (GdkContentDeserializer *deserializer) /** * gdk_content_deserializer_get_user_data: - * @deserializer: a #GdkContentDeserializer + * @deserializer: a `GdkContentDeserializer` * * Gets the user data that was passed when the deserializer was registered. * @@ -278,7 +290,7 @@ gdk_content_deserializer_get_user_data (GdkContentDeserializer *deserializer) /** * gdk_content_deserializer_set_task_data: - * @deserializer: a #GdkContentDeserializer + * @deserializer: a `GdkContentDeserializer` * @data: data to associate with this operation * @notify: destroy notify for @data * @@ -300,9 +312,11 @@ gdk_content_deserializer_set_task_data (GdkContentDeserializer *deserializer, /** * gdk_content_deserializer_get_task_data: - * @deserializer: a #GdkContentDeserializer + * @deserializer: a `GdkContentDeserializer` * - * Gets the data that was associated with @deserializer via gdk_content_deserializer_set_task_data(). + * Gets the data that was associated with the current operation. + * + * See [method@Gdk.ContentDeserializer.set_task_data]. * * Returns: (transfer none): the task data for @deserializer */ @@ -329,7 +343,7 @@ gdk_content_deserializer_emit_callback (gpointer data) /** * gdk_content_deserializer_return_success: - * @deserializer: a #GdkContentDeserializer + * @deserializer: a `GdkContentDeserializer` * * Indicate that the deserialization has been successfully completed. */ @@ -349,10 +363,11 @@ gdk_content_deserializer_return_success (GdkContentDeserializer *deserializer) /** * gdk_content_deserializer_return_error: - * @deserializer: a #GdkContentDeserializer - * @error: a #GError + * @deserializer: a `GdkContentDeserializer` + * @error: a `GError` * * Indicate that the deserialization has ended with an error. + * * This function consumes @error. */ void @@ -376,8 +391,7 @@ gdk_content_deserializer_return_error (GdkContentDeserializer *deserializer, * @data: data that @deserialize can access * @notify: destroy notify for @data * - * Registers a function to create objects of a given @type from - * a serialized representation with the given mime type. + * Registers a function to deserialize object of a given type. */ void gdk_content_register_deserializer (const char *mime_type, @@ -424,18 +438,18 @@ lookup_deserializer (const char *mime_type, deserializer->type == type) return deserializer; } - + return NULL; } /** * gdk_content_formats_union_deserialize_gtypes: - * @formats: (transfer full): a #GdkContentFormats + * @formats: (transfer full): a `GdkContentFormats` * * Add GTypes for mime types in @formats for which deserializers are * registered. * - * Return: a new #GdkContentFormats + * Return: a new `GdkContentFormats` */ GdkContentFormats * gdk_content_formats_union_deserialize_gtypes (GdkContentFormats *formats) @@ -465,12 +479,12 @@ gdk_content_formats_union_deserialize_gtypes (GdkContentFormats *formats) /** * gdk_content_formats_union_deserialize_mime_types: - * @formats: (transfer full): a #GdkContentFormats + * @formats: (transfer full): a `GdkContentFormats` * * Add mime types for GTypes in @formats for which deserializers are * registered. * - * Return: a new #GdkContentFormats + * Return: a new `GdkContentFormats` */ GdkContentFormats * gdk_content_formats_union_deserialize_mime_types (GdkContentFormats *formats) @@ -511,17 +525,21 @@ deserialize_not_found (GdkContentDeserializer *deserializer) /** * gdk_content_deserialize_async: - * @stream: a #GInputStream to read the serialized content from + * @stream: a `GInputStream` to read the serialized content from * @mime_type: the mime type to deserialize from * @type: the GType to deserialize from - * @io_priority: the io priority of the operation - * @cancellable: (nullable): optional #GCancellable object + * @io_priority: the I/O priority of the operation + * @cancellable: (nullable): optional `GCancellable` object * @callback: (scope async): callback to call when the operation is done * @user_data: (closure): data to pass to the callback function * * Read content from the given input stream and deserialize it, asynchronously. - * When the operation is finished, @callback will be called. You can then - * call gdk_content_deserialize_finish() to get the result of the operation. + * + * The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers + * indicate a higher priority. + * + * When the operation is finished, @callback will be called. You must then + * call [func@content_deserialize_finish] to get the result of the operation. */ void gdk_content_deserialize_async (GInputStream *stream, @@ -553,14 +571,15 @@ gdk_content_deserialize_async (GInputStream *stream, /** * gdk_content_deserialize_finish: - * @result: the #GAsyncResult + * @result: the `GAsyncResult` * @value: return location for the result of the operation * @error: return location for an error * * Finishes a content deserialization operation. * - * Returns: %TRUE if the operation was successful. In this case, @value is set. - * %FALSE if an error occurred. In this case, @error is set + * Returns: %TRUE if the operation was successful. In this case, + * @value is set. %FALSE if an error occurred. In this case, + * @error is set */ gboolean gdk_content_deserialize_finish (GAsyncResult *result, diff --git a/gdk/gdkcontentdeserializer.h b/gdk/gdkcontentdeserializer.h index 2b3fda4d81..4ff7028424 100644 --- a/gdk/gdkcontentdeserializer.h +++ b/gdk/gdkcontentdeserializer.h @@ -32,11 +32,6 @@ G_BEGIN_DECLS #define GDK_CONTENT_DESERIALIZER(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_CONTENT_DESERIALIZER, GdkContentDeserializer)) #define GDK_IS_CONTENT_DESERIALIZER(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_CONTENT_DESERIALIZER)) -/** - * GdkContentDeserializer: - * - * Should not be accessed directly. - */ typedef struct _GdkContentDeserializer GdkContentDeserializer; /** @@ -44,6 +39,7 @@ typedef struct _GdkContentDeserializer GdkContentDeserializer; * @deserializer: a #GdkContentDeserializer * * The type of a function that can be registered with gdk_content_register_deserializer(). + * * When the function gets called to operate on content, it can call functions on the * @deserializer object to obtain the mime type, input stream, user data, etc. for its * operation. diff --git a/gdk/gdkcontentformats.c b/gdk/gdkcontentformats.c index 005d387b7c..d8e590e14f 100644 --- a/gdk/gdkcontentformats.c +++ b/gdk/gdkcontentformats.c @@ -16,46 +16,40 @@ */ /** - * SECTION:gdkcontentformats - * @Title: Content Formats - * @Short_description: Advertising and negotiating of content - * exchange formats - * @See_also: #GdkDrag, #GdkDrop, #GdkClipboard, #GdkContentProvider + * GdkContentFormats: * - * This section describes the #GdkContentFormats structure that is used to - * advertise and negotiate the format of content passed between different - * widgets, windows or applications using for example the clipboard or - * drag'n'drop. + * The `GdkContentFormats` structure is used to advertise and negotiate the + * format of content. * - * GDK supports content in 2 forms: #GType and mime type. - * Using #GTypes is meant only for in-process content transfers. Mime types + * You will encounter `GdkContentFormats` when interacting with objects + * controlling operations that pass data between different widgets, window + * or application, like [class@Gdk.Drag], [class@Gdk.Drop], + * [class@Gdk.Clipboard] or [class@Gdk.ContentProvider]. + * + * GDK supports content in 2 forms: `GType` and mime type. + * Using `GTypes` is meant only for in-process content transfers. Mime types * are meant to be used for data passing both in-process and out-of-process. * The details of how data is passed is described in the documentation of - * the actual implementations. + * the actual implementations. To transform between the two forms, + * [class@Gdk.ContentSerializer] and [class@Gdk.ContentDeserializer] are used. * - * A #GdkContentFormats describes a set of possible formats content can be - * exchanged in. It is assumed that this set is ordered. #GTypes are more - * important than mime types. Order between different #GTypes or mime types + * A `GdkContentFormats` describes a set of possible formats content can be + * exchanged in. It is assumed that this set is ordered. `GTypes` are more + * important than mime types. Order between different `GTypes` or mime types * is the order they were added in, most important first. Functions that - * care about order, such as gdk_content_formats_union() will describe in - * their documentation how they interpret that order, though in general the + * care about order, such as [method@Gdk.ContentFormats.union], will describe + * in their documentation how they interpret that order, though in general the * order of the first argument is considered the primary order of the result, * followed by the order of further arguments. * - * For debugging purposes, the function gdk_content_formats_to_string() exists. - * It will print a comma-seperated formats of formats from most important to least - * important. + * For debugging purposes, the function [method@Gdk.ContentFormats.to_string] + * exists. It will print a comma-separated list of formats from most important + * to least important. * - * #GdkContentFormats is an immutable struct. After creation, you cannot change - * the types it represents. Instead, new #GdkContentFormats have to be created. - * The #GdkContentFormatsBuilder structure is meant to help in this endeavor. - */ - -/** - * GdkContentFormats: - * - * A #GdkContentFormats struct is a reference counted struct - * and should be treated as opaque. + * `GdkContentFormats` is an immutable struct. After creation, you cannot change + * the types it represents. Instead, new `GdkContentFormats` have to be created. + * The [struct@Gdk.ContentFormatsBuilder]` structure is meant to help in this + * endeavor. */ #include "config.h" @@ -92,7 +86,7 @@ G_DEFINE_BOXED_TYPE (GdkContentFormats, gdk_content_formats, * * Returns: An interned string for the canonicalized mime type * or %NULL if the string wasn't a valid mime type - **/ + */ const char * gdk_intern_mime_type (const char *string) { @@ -134,15 +128,15 @@ gdk_content_formats_new_take (GType * gtypes, * @mime_types: (array length=n_mime_types) (allow-none): Pointer to an * array of mime types * @n_mime_types: number of entries in @mime_types. - * - * Creates a new #GdkContentFormats from an array of mime types. + * + * Creates a new `GdkContentFormats` from an array of mime types. * * The mime types must be valid and different from each other or the * behavior of the return value is undefined. If you cannot guarantee - * this, use #GdkContentFormatsBuilder instead. - * - * Returns: (transfer full): the new #GdkContentFormats. - **/ + * this, use `GdkContentFormatsBuilder` instead. + * + * Returns: (transfer full): the new `GdkContentFormats`. + */ GdkContentFormats * gdk_content_formats_new (const char **mime_types, guint n_mime_types) @@ -165,12 +159,12 @@ gdk_content_formats_new (const char **mime_types, /** * gdk_content_formats_new_for_gtype: - * @type: a $GType + * @type: a `GType` * - * Creates a new #GdkContentFormats for a given #GType. + * Creates a new `GdkContentFormats` for a given `GType`. * - * Returns: a new #GdkContentFormats - **/ + * Returns: a new `GdkContentFormats` + */ GdkContentFormats * gdk_content_formats_new_for_gtype (GType type) { @@ -187,12 +181,12 @@ gdk_content_formats_new_for_gtype (GType type) /** * gdk_content_formats_ref: - * @formats: a #GdkContentFormats - * - * Increases the reference count of a #GdkContentFormats by one. + * @formats: a `GdkContentFormats` * - * Returns: the passed in #GdkContentFormats. - **/ + * Increases the reference count of a `GdkContentFormats` by one. + * + * Returns: the passed in `GdkContentFormats`. + */ GdkContentFormats * gdk_content_formats_ref (GdkContentFormats *formats) { @@ -205,12 +199,13 @@ gdk_content_formats_ref (GdkContentFormats *formats) /** * gdk_content_formats_unref: - * @formats: a #GdkContentFormats - * - * Decreases the reference count of a #GdkContentFormats by one. + * @formats: a `GdkContentFormats` + * + * Decreases the reference count of a `GdkContentFormats` by one. + * * If the resulting reference count is zero, frees the formats. - **/ -void + */ +void gdk_content_formats_unref (GdkContentFormats *formats) { g_return_if_fail (formats != NULL); @@ -227,15 +222,16 @@ gdk_content_formats_unref (GdkContentFormats *formats) /** * gdk_content_formats_print: - * @formats: a #GdkContentFormats - * @string: a #GString to print into + * @formats: a `GdkContentFormats` + * @string: a `GString` to print into * * Prints the given @formats into a string for human consumption. + * * This is meant for debugging and logging. * * The form of the representation may change at any time and is * not guaranteed to stay identical. - **/ + */ void gdk_content_formats_print (GdkContentFormats *formats, GString *string) @@ -263,14 +259,15 @@ gdk_content_formats_print (GdkContentFormats *formats, /** * gdk_content_formats_to_string: - * @formats: a #GdkContentFormats + * @formats: a `GdkContentFormats` * * Prints the given @formats into a human-readable string. - * This is a small wrapper around gdk_content_formats_print() to help - * when debugging. + * + * This is a small wrapper around [method@Gdk.ContentFormats.print] + * to help when debugging. * * Returns: (transfer full): a new string - **/ + */ char * gdk_content_formats_to_string (GdkContentFormats *formats) { @@ -286,13 +283,13 @@ gdk_content_formats_to_string (GdkContentFormats *formats) /** * gdk_content_formats_union: - * @first: (transfer full): the #GdkContentFormats to merge into - * @second: (transfer none): the #GdkContentFormats to merge from + * @first: (transfer full): the `GdkContentFormats` to merge into + * @second: (transfer none): the `GdkContentFormats` to merge from * * Append all missing types from @second to @first, in the order * they had in @second. * - * Returns: a new #GdkContentFormats + * Returns: a new `GdkContentFormats` */ GdkContentFormats * gdk_content_formats_union (GdkContentFormats *first, @@ -329,8 +326,8 @@ gdk_content_formats_contain_interned_mime_type (const GdkContentFormats *formats /** * gdk_content_formats_match: - * @first: the primary #GdkContentFormats to intersect - * @second: the #GdkContentFormats to intersect with + * @first: the primary `GdkContentFormats` to intersect + * @second: the `GdkContentFormats` to intersect with * * Checks if @first and @second have any matching formats. * @@ -349,15 +346,16 @@ gdk_content_formats_match (const GdkContentFormats *first, /** * gdk_content_formats_match_gtype: - * @first: the primary #GdkContentFormats to intersect - * @second: the #GdkContentFormats to intersect with + * @first: the primary `GdkContentFormats` to intersect + * @second: the `GdkContentFormats` to intersect with * - * Finds the first #GType from @first that is also contained - * in @second. If no matching #GType is found, %G_TYPE_INVALID - * is returned. + * Finds the first `GType` from @first that is also contained + * in @second. * - * Returns: The first common #GType or %G_TYPE_INVALID if none. - **/ + * If no matching `GType` is found, %G_TYPE_INVALID is returned. + * + * Returns: The first common `GType` or %G_TYPE_INVALID if none. + */ GType gdk_content_formats_match_gtype (const GdkContentFormats *first, const GdkContentFormats *second) @@ -378,15 +376,16 @@ gdk_content_formats_match_gtype (const GdkContentFormats *first, /** * gdk_content_formats_match_mime_type: - * @first: the primary #GdkContentFormats to intersect - * @second: the #GdkContentFormats to intersect with + * @first: the primary `GdkContentFormats` to intersect + * @second: the `GdkContentFormats` to intersect with * * Finds the first mime type from @first that is also contained - * in @second. If no matching mime type is found, %NULL is - * returned. + * in @second. + * + * If no matching mime type is found, %NULL is returned. * * Returns: (nullable): The first common mime type or %NULL if none. - **/ + */ const char * gdk_content_formats_match_mime_type (const GdkContentFormats *first, const GdkContentFormats *second) @@ -407,13 +406,13 @@ gdk_content_formats_match_mime_type (const GdkContentFormats *first, /** * gdk_content_formats_contain_gtype: - * @formats: a #GdkContentFormats - * @type: the #GType to search for + * @formats: a `GdkContentFormats` + * @type: the `GType` to search for * - * Checks if a given #GType is part of the given @formats. + * Checks if a given `GType` is part of the given @formats. * * Returns: %TRUE if the #GType was found - **/ + */ gboolean gdk_content_formats_contain_gtype (const GdkContentFormats *formats, GType type) @@ -433,13 +432,13 @@ gdk_content_formats_contain_gtype (const GdkContentFormats *formats, /** * gdk_content_formats_contain_mime_type: - * @formats: a #GdkContentFormats + * @formats: a `GdkContentFormats` * @mime_type: the mime type to search for * * Checks if a given mime type is part of the given @formats. * * Returns: %TRUE if the mime_type was found - **/ + */ gboolean gdk_content_formats_contain_mime_type (const GdkContentFormats *formats, const char *mime_type) @@ -453,18 +452,19 @@ gdk_content_formats_contain_mime_type (const GdkContentFormats *formats, /** * gdk_content_formats_get_gtypes: - * @formats: a #GdkContentFormats + * @formats: a `GdkContentFormats` * @n_gtypes: (out) (optional): optional pointer to take the * number of #GTypes contained in the return value * - * Gets the #GTypes included in @formats. Note that @formats may not - * contain any #GTypes, in particular when they are empty. In that - * case %NULL will be returned. + * Gets the `GTypes` included in @formats. + * + * Note that @formats may not contain any #GTypes, in particular when + * they are empty. In that case %NULL will be returned. * * Returns: (transfer none) (nullable) (array length=n_gtypes): * %G_TYPE_INVALID-terminated array of types included in @formats or * %NULL if none. - **/ + */ const GType * gdk_content_formats_get_gtypes (const GdkContentFormats *formats, gsize *n_gtypes) @@ -479,18 +479,19 @@ gdk_content_formats_get_gtypes (const GdkContentFormats *formats, /** * gdk_content_formats_get_mime_types: - * @formats: a #GdkContentFormats + * @formats: a `GdkContentFormats` * @n_mime_types: (out) (allow-none): optional pointer to take the * number of mime types contained in the return value * - * Gets the mime types included in @formats. Note that @formats may not - * contain any mime types, in particular when they are empty. In that - * case %NULL will be returned. + * Gets the mime types included in @formats. * - * Returns: (transfer none) (nullable): %NULL-terminated array of + * Note that @formats may not contain any mime types, in particular + * when they are empty. In that case %NULL will be returned. + * + * Returns: (transfer none) (nullable): %NULL-terminated array of * interned strings of mime types included in @formats or %NULL * if none. - **/ + */ const char * const * gdk_content_formats_get_mime_types (const GdkContentFormats *formats, gsize *n_mime_types) @@ -506,9 +507,8 @@ gdk_content_formats_get_mime_types (const GdkContentFormats *formats, /** * GdkContentFormatsBuilder: * - * A #GdkContentFormatsBuilder struct is an opaque struct. It is meant to - * not be kept around and only be used to create new #GdkContentFormats - * objects. + * A `GdkContentFormatsBuilder` is an auxiliary struct used to create + * new `GdkContentFormats`, and should not be kept around. */ struct _GdkContentFormatsBuilder @@ -532,12 +532,13 @@ G_DEFINE_BOXED_TYPE (GdkContentFormatsBuilder, /** * gdk_content_formats_builder_new: * - * Create a new #GdkContentFormatsBuilder object. The resulting builder - * would create an empty #GdkContentFormats. Use addition functions to add - * types to it. + * Create a new `GdkContentFormatsBuilder` object. * - * Returns: a new #GdkContentFormatsBuilder - **/ + * The resulting builder would create an empty `GdkContentFormats`. + * Use addition functions to add types to it. + * + * Returns: a new `GdkContentFormatsBuilder` + */ GdkContentFormatsBuilder * gdk_content_formats_builder_new (void) { @@ -551,15 +552,15 @@ gdk_content_formats_builder_new (void) /** * gdk_content_formats_builder_ref: - * @builder: a #GdkContentFormatsBuilder + * @builder: a `GdkContentFormatsBuilder` * * Acquires a reference on the given @builder. * - * This function is intended primarily for bindings. #GdkContentFormatsBuilder objects - * should not be kept around. + * This function is intended primarily for bindings. + * `GdkContentFormatsBuilder` objects should not be kept around. * - * Returns: (transfer none): the given #GdkContentFormatsBuilder with - * its reference count increased + * Returns: (transfer none): the given `GdkContentFormatsBuilder` + * with its reference count increased */ GdkContentFormatsBuilder * gdk_content_formats_builder_ref (GdkContentFormatsBuilder *builder) @@ -581,7 +582,7 @@ gdk_content_formats_builder_clear (GdkContentFormatsBuilder *builder) /** * gdk_content_formats_builder_unref: - * @builder: a #GdkContentFormatsBuilder + * @builder: a `GdkContentFormatsBuilder` * * Releases a reference on the given @builder. */ @@ -602,12 +603,12 @@ gdk_content_formats_builder_unref (GdkContentFormatsBuilder *builder) /** * gdk_content_formats_builder_free_to_formats: (skip) - * @builder: a #GdkContentFormatsBuilder + * @builder: a `GdkContentFormatsBuilder` * - * Creates a new #GdkContentFormats from the current state of the + * Creates a new `GdkContentFormats` from the current state of the * given @builder, and frees the @builder instance. * - * Returns: (transfer full): the newly created #GdkContentFormats + * Returns: (transfer full): the newly created `GdkContentFormats` * with all the formats added to @builder */ GdkContentFormats * @@ -626,17 +627,17 @@ gdk_content_formats_builder_free_to_formats (GdkContentFormatsBuilder *builder) /** * gdk_content_formats_builder_to_formats: - * @builder: a #GdkContentFormatsBuilder + * @builder: a `GdkContentFormats`Builder * - * Creates a new #GdkContentFormats from the given @builder. + * Creates a new `GdkContentFormats` from the given @builder. * - * The given #GdkContentFormatsBuilder is reset once this function returns; + * The given `GdkContentFormatsBuilder` is reset once this function returns; * you cannot call this function multiple times on the same @builder instance. * * This function is intended primarily for bindings. C code should use - * gdk_content_formats_builder_free_to_formats(). + * [method@Gdk.ContentFormatsBuilder.free_to_formats]. * - * Returns: (transfer full): the newly created #GdkContentFormats + * Returns: (transfer full): the newly created `GdkContentFormats` * with all the formats added to @builder */ GdkContentFormats * @@ -674,12 +675,12 @@ gdk_content_formats_builder_to_formats (GdkContentFormatsBuilder *builder) /** * gdk_content_formats_builder_add_formats: - * @builder: a #GdkContentFormatsBuilder + * @builder: a `GdkContentFormatsBuilder` * @formats: the formats to add * * Appends all formats from @formats to @builder, skipping those that * already exist. - **/ + */ void gdk_content_formats_builder_add_formats (GdkContentFormatsBuilder *builder, const GdkContentFormats *formats) @@ -698,10 +699,10 @@ gdk_content_formats_builder_add_formats (GdkContentFormatsBuilder *builder, /** * gdk_content_formats_builder_add_gtype: - * @builder: a #GdkContentFormatsBuilder - * @type: a #GType + * @builder: a `GdkContentFormats`Builder + * @type: a `GType` * - * Appends @gtype to @builder if it has not already been added. + * Appends @type to @builder if it has not already been added. **/ void gdk_content_formats_builder_add_gtype (GdkContentFormatsBuilder *builder, @@ -719,11 +720,11 @@ gdk_content_formats_builder_add_gtype (GdkContentFormatsBuilder *builder, /** * gdk_content_formats_builder_add_mime_type: - * @builder: a #GdkContentFormatsBuilder + * @builder: a `GdkContentFormatsBuilder` * @mime_type: a mime type * * Appends @mime_type to @builder if it has not already been added. - **/ + */ void gdk_content_formats_builder_add_mime_type (GdkContentFormatsBuilder *builder, const char *mime_type) diff --git a/gdk/gdkcontentprovider.c b/gdk/gdkcontentprovider.c index 4253ea4203..5e7b2f8818 100644 --- a/gdk/gdkcontentprovider.c +++ b/gdk/gdkcontentprovider.c @@ -25,20 +25,17 @@ #include "gdkintl.h" /** - * SECTION:gdkcontentprovider - * @Short_description: Provides content for data transfer between applications - * @Title: GdkContentProvider - * @See_also: #GdkContentSerializer, #GdkContentDeserializer + * GdkContentProvider: * - * A GdkContentProvider is used to provide content for the clipboard in - * a number of formats. + * A `GdkContentProvider` is used to provide content for the clipboard or + * for drag-and-drop operations in a number of formats. * - * To create a GdkContentProvider, use gdk_content_provider_new_for_value() or - * gdk_content_provider_new_for_bytes(). + * To create a `GdkContentProvider`, use [ctor@Gdk.ContentProvider.new_for_value] + * or [ctor@Gdk.ContentProvider.new_for_bytes]. * * GDK knows how to handle common text and image formats out-of-the-box. See - * #GdkContentSerializer and #GdkContentDeserializer if you want to add support - * for application-specific data formats. + * [class@Gdk.ContentSerializer] and [class@Gdk.ContentDeserializer] if you want + * to add support for application-specific data formats. */ typedef struct _GdkContentProviderPrivate GdkContentProviderPrivate; @@ -226,7 +223,7 @@ gdk_content_provider_init (GdkContentProvider *provider) * Gets the formats that the provider can provide its current contents in. * * Returns: (transfer full): The formats of the provider - **/ + */ GdkContentFormats * gdk_content_provider_ref_formats (GdkContentProvider *provider) { @@ -240,13 +237,14 @@ gdk_content_provider_ref_formats (GdkContentProvider *provider) * @provider: a #GdkContentProvider * * Gets the formats that the provider suggests other applications to store - * the data in. + * the data in. + * * An example of such an application would be a clipboard manager. * - * This can be assumed to be a subset of gdk_content_provider_ref_formats(). + * This can be assumed to be a subset of [method@Gdk.ContentProvider.ref_formats]. * * Returns: (transfer full): The storable formats of the provider - **/ + */ GdkContentFormats * gdk_content_provider_ref_storable_formats (GdkContentProvider *provider) { @@ -257,9 +255,9 @@ gdk_content_provider_ref_storable_formats (GdkContentProvider *provider) /** * gdk_content_provider_content_changed: - * @provider: a #GdkContentProvider + * @provider: a `GdkContentProvider` * - * Emits the #GdkContentProvider::content-changed signal. + * Emits the ::content-changed signal. */ void gdk_content_provider_content_changed (GdkContentProvider *provider) @@ -273,26 +271,27 @@ gdk_content_provider_content_changed (GdkContentProvider *provider) /** * gdk_content_provider_write_mime_type_async: - * @provider: a #GdkContentProvider + * @provider: a `GdkContentProvider` * @mime_type: the mime type to provide the data in - * @stream: the #GOutputStream to write to - * @io_priority: the [I/O priority][io-priority] - * of the request. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @stream: the `GOutputStream` to write to + * @io_priority: I/O priority of the request. + * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously writes the contents of @provider to @stream in the given - * @mime_type. When the operation is finished @callback will be called. You - * can then call gdk_content_provider_write_mime_type_finish() to get the - * result of the operation. + * @mime_type. + * + * When the operation is finished @callback will be called. You must then call + * [method@Gdk.ContentProvider.write_mime_type_finish] to get the result + * of the operation. * * The given mime type does not need to be listed in the formats returned by - * gdk_content_provider_ref_formats(). However, if the given #GType is not - * supported, #G_IO_ERROR_NOT_SUPPORTED will be reported. + * [method@Gdk.ContentProvider.ref_formats]. However, if the given `GType` is + * not supported, #G_IO_ERROR_NOT_SUPPORTED will be reported. * * The given @stream will not be closed. - **/ + */ void gdk_content_provider_write_mime_type_async (GdkContentProvider *provider, const char *mime_type, @@ -318,17 +317,17 @@ gdk_content_provider_write_mime_type_async (GdkContentProvider *provider, /** * gdk_content_provider_write_mime_type_finish: - * @provider: a #GdkContentProvider - * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * @provider: a `GdkContentProvider` + * @result: a `GAsyncResult` + * @error: a `GError` location to store the error occurring, or %NULL to ignore * - * Finishes an asynchronous write operation started with - * gdk_content_provider_write_mime_type_async(). + * Finishes an asynchronous write operation. + * + * See [method@Gdk.ContentProvider.write_mime_type_async]. * * Returns: %TRUE if the operation was completed successfully. Otherwise * @error will be set to describe the failure. - **/ + */ gboolean gdk_content_provider_write_mime_type_finish (GdkContentProvider *provider, GAsyncResult *result, @@ -342,22 +341,21 @@ gdk_content_provider_write_mime_type_finish (GdkContentProvider *provider, /** * gdk_content_provider_get_value: - * @provider: a #GdkContentProvider - * @value: the #GValue to fill - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * @provider: a `GdkContentProvider` + * @value: the `GValue` to fill + * @error: a `GError` location to store the error occurring, or %NULL to ignore * * Gets the contents of @provider stored in @value. * - * The @value will have been initialized to the #GType the value should be - * provided in. This given #GType does not need to be listed in the formats - * returned by gdk_content_provider_ref_formats(). However, if the given - * #GType is not supported, this operation can fail and + * The @value will have been initialized to the `GType` the value should be + * provided in. This given `GType` does not need to be listed in the formats + * returned by [method@Gdk.ContentProvider.ref_formats]. However, if the + * given `GType` is not supported, this operation can fail and * #G_IO_ERROR_NOT_SUPPORTED will be reported. * * Returns: %TRUE if the value was set successfully. Otherwise * @error will be set to describe the failure. - **/ + */ gboolean gdk_content_provider_get_value (GdkContentProvider *provider, GValue *value, diff --git a/gdk/gdkcontentprovider.h b/gdk/gdkcontentprovider.h index f1f558ab74..f4be04238e 100644 --- a/gdk/gdkcontentprovider.h +++ b/gdk/gdkcontentprovider.h @@ -38,12 +38,6 @@ G_BEGIN_DECLS typedef struct _GdkContentProviderClass GdkContentProviderClass; -/** - * GdkContentProvider: - * - * Should not be directly accessed. - */ - struct _GdkContentProvider { GObject parent; diff --git a/gdk/gdkcontentserializer.c b/gdk/gdkcontentserializer.c index 7a3e4c3d22..cf8e7c88cf 100644 --- a/gdk/gdkcontentserializer.c +++ b/gdk/gdkcontentserializer.c @@ -32,13 +32,20 @@ /** - * SECTION:gdkcontentserializer - * @Short_description: Serialize content for transfer - * @Title: GdkContentSerializer - * @See_also: #GdkContentDeserializer, #GdkContentProvider + * GdkContentSerializer: * - * A GdkContentSerializer is used to serialize content for inter-application - * data transfers. + * A `GdkContentSerializer` is used to serialize content for + * inter-application data transfers. + * + * The `GdkContentSerializer` transforms an object that is identified + * by a GType into a serialized form (i.e. a byte stream) that is + * identified by a mime type. + * + * GTK provides serializers and deserializers for common data types + * such as text, colors, images or file lists. To register your own + * serialization functions, use [func@content_register_serializer]. + * + * Also see [class@Gdk.ContentDeserializer]. */ typedef struct _Serializer Serializer; @@ -169,7 +176,7 @@ gdk_content_serializer_run (const char *mime_type, /** * gdk_content_serializer_get_mime_type: - * @serializer: a #GdkContentSerializer + * @serializer: a `GdkContentSerializer` * * Gets the mime type to serialize to. * @@ -185,11 +192,11 @@ gdk_content_serializer_get_mime_type (GdkContentSerializer *serializer) /** * gdk_content_serializer_get_gtype: - * @serializer: a #GdkContentSerializer + * @serializer: a `GdkContentSerializer` * - * Gets the GType to of the object to serialize. + * Gets the `GType` to of the object to serialize. * - * Returns: the GType for the current operation + * Returns: the `GType` for the current operation */ GType gdk_content_serializer_get_gtype (GdkContentSerializer *serializer) @@ -201,11 +208,11 @@ gdk_content_serializer_get_gtype (GdkContentSerializer *serializer) /** * gdk_content_serializer_get_value: - * @serializer: a #GdkContentSerializer + * @serializer: a `GdkContentSerializer` * - * Gets the #GValue to read the object to serialize from. + * Gets the `GValue` to read the object to serialize from. * - * Returns: (transfer none): the #GValue for the current operation + * Returns: (transfer none): the `GValue` for the current operation */ const GValue * gdk_content_serializer_get_value (GdkContentSerializer *serializer) @@ -217,9 +224,11 @@ gdk_content_serializer_get_value (GdkContentSerializer *serializer) /** * gdk_content_serializer_get_output_stream: - * @serializer: a #GdkContentSerializer + * @serializer: a `GdkContentSerializer` * - * Gets the output stream that was passed to gdk_content_serialize_async(). + * Gets the output stream for the current operation. + * + * This is the stream that was passed to [func@content_serialize_async]. * * Returns: (transfer none): the output stream for the current operation */ @@ -233,11 +242,13 @@ gdk_content_serializer_get_output_stream (GdkContentSerializer *serializer) /** * gdk_content_serializer_get_priority: - * @serializer: a #GdkContentSerializer + * @serializer: a `GdkContentSerializer` * - * Gets the io priority that was passed to gdk_content_serialize_async(). + * Gets the I/O priority for the current operation. * - * Returns: the io priority for the current operation + * This is the priority that was passed to [func@content_serialize_async]. + * + * Returns: the I/O priority for the current operation */ int gdk_content_serializer_get_priority (GdkContentSerializer *serializer) @@ -249,9 +260,11 @@ gdk_content_serializer_get_priority (GdkContentSerializer *serializer) /** * gdk_content_serializer_get_cancellable: - * @serializer: a #GdkContentSerializer + * @serializer: a `GdkContentSerializer` * - * Gets the cancellable that was passed to gdk_content_serialize_async(). + * Gets the cancellable for the current operation. + * + * This is the `GCancellable` that was passed to [content_serialize_async]. * * Returns: (transfer none): the cancellable for the current operation */ @@ -265,7 +278,7 @@ gdk_content_serializer_get_cancellable (GdkContentSerializer *serializer) /** * gdk_content_serializer_get_user_data: - * @serializer: a #GdkContentSerializer + * @serializer: a `GdkContentSerializer` * * Gets the user data that was passed when the serializer was registered. * @@ -281,7 +294,7 @@ gdk_content_serializer_get_user_data (GdkContentSerializer *serializer) /** * gdk_content_serializer_set_task_data: - * @serializer: a #GdkContentSerializer + * @serializer: a `GdkContentSerializer` * @data: data to associate with this operation * @notify: destroy notify for @data * @@ -303,9 +316,11 @@ gdk_content_serializer_set_task_data (GdkContentSerializer *serializer, /** * gdk_content_serializer_get_task_data: - * @serializer: a #GdkContentSerializer + * @serializer: a `GdkContentSerializer` * - * Gets the data that was associated with @serializer via gdk_content_serializer_set_task_data(). + * Gets the data that was associated with the current operation. + * + * See [method@Gdk.ContentSerializer.set_task_data]. * * Returns: (transfer none): the task data for @serializer */ @@ -332,7 +347,7 @@ gdk_content_serializer_emit_callback (gpointer data) /** * gdk_content_serializer_return_success: - * @serializer: a #GdkContentSerializer + * @serializer: a `GdkContentSerializer` * * Indicate that the serialization has been successfully completed. */ @@ -352,10 +367,11 @@ gdk_content_serializer_return_success (GdkContentSerializer *serializer) /** * gdk_content_serializer_return_error: - * @serializer: a #GdkContentSerializer - * @error: a #GError + * @serializer: a `GdkContentSerializer` + * @error: a `GError` * * Indicate that the serialization has ended with an error. + * * This function consumes @error. */ void @@ -379,8 +395,7 @@ gdk_content_serializer_return_error (GdkContentSerializer *serializer, * @data: data that @serialize can access * @notify: destroy notify for @data * - * Registers a function to convert objects of the given @type to - * a serialized representation with the given mime type. + * Registers a function to serialize objects of a given type. */ void gdk_content_register_serializer (GType type, @@ -433,12 +448,12 @@ lookup_serializer (const char *mime_type, /** * gdk_content_formats_union_serialize_gtypes: - * @formats: (transfer full): a #GdkContentFormats + * @formats: (transfer full): a `GdkContentFormats` * * Add GTypes for the mime types in @formats for which serializers are * registered. * - * Return: a new #GdkContentFormats + * Return: a new `GdkContentFormats` */ GdkContentFormats * gdk_content_formats_union_serialize_gtypes (GdkContentFormats *formats) @@ -468,12 +483,12 @@ gdk_content_formats_union_serialize_gtypes (GdkContentFormats *formats) /** * gdk_content_formats_union_serialize_mime_types: - * @formats: (transfer full): a #GdkContentFormats + * @formats: (transfer full): a `GdkContentFormats` * * Add mime types for GTypes in @formats for which serializers are * registered. * - * Return: a new #GdkContentFormats + * Return: a new `GdkContentFormats` */ GdkContentFormats * gdk_content_formats_union_serialize_mime_types (GdkContentFormats *formats) @@ -514,17 +529,21 @@ serialize_not_found (GdkContentSerializer *serializer) /** * gdk_content_serialize_async: - * @stream: a #GOutputStream to write the serialized content to + * @stream: a `GOutputStream` to write the serialized content to * @mime_type: the mime type to serialize to * @value: the content to serialize - * @io_priority: the io priority of the operation + * @io_priority: the I/O priority of the operation * @cancellable: (nullable): optional #GCancellable object * @callback: (scope async): callback to call when the operation is done * @user_data: (closure): data to pass to the callback function * * Serialize content and write it to the given output stream, asynchronously. - * When the operation is finished, @callback will be called. You can then - * call gdk_content_serialize_finish() to get the result of the operation. + * + * The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers + * indicate a higher priority. + * + * When the operation is finished, @callback will be called. You must then + * call [func@content_serialize_finish] to get the result of the operation. */ void gdk_content_serialize_async (GOutputStream *stream, @@ -556,7 +575,7 @@ gdk_content_serialize_async (GOutputStream *stream, /** * gdk_content_serialize_finish: - * @result: the #GAsyncResult + * @result: the `GAsyncResult` * @error: return location for an error * * Finishes a content serialization operation. diff --git a/gdk/gdkcontentserializer.h b/gdk/gdkcontentserializer.h index 82b4f909a7..17b5c7c36e 100644 --- a/gdk/gdkcontentserializer.h +++ b/gdk/gdkcontentserializer.h @@ -32,11 +32,6 @@ G_BEGIN_DECLS #define GDK_CONTENT_SERIALIZER(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_CONTENT_SERIALIZER, GdkContentSerializer)) #define GDK_IS_CONTENT_SERIALIZER(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_CONTENT_SERIALIZER)) -/** - * GdkContentSerializer: - * - * Should not be accessed directly. - */ typedef struct _GdkContentSerializer GdkContentSerializer; /** @@ -44,6 +39,7 @@ typedef struct _GdkContentSerializer GdkContentSerializer; * @serializer: a #GdkContentSerializer * * The type of a function that can be registered with gdk_content_register_serializer(). + * * When the function gets called to operate on content, it can call functions on the * @serializer object to obtain the mime type, output stream, user data, etc. for its * operation. diff --git a/gdk/gdkcursor.c b/gdk/gdkcursor.c index ebb87c5c7b..700f458573 100644 --- a/gdk/gdkcursor.c +++ b/gdk/gdkcursor.c @@ -37,19 +37,19 @@ #include /** - * SECTION:gdkcursor - * @Short_description: Named and texture cursors - * @Title: Cursors + * GdkCursor: * - * `GdkCursor` is used to create and destroy cursors. Cursors are immutable - * objects, so once you created them, there is no way to modify them later. - * You should create a new cursor when you want to change something about - * it. + * `GdkCursor` is used to create and destroy cursors. + * + * Cursors are immutable objects, so once you created them, there is no way + * to modify them later. You should create a new cursor when you want to change + * something about it. * * Cursors by themselves are not very interesting: they must be bound to a * window for users to see them. This is done with [method@Gdk.Surface.set_cursor] * or [method@Gdk.Surface.set_device_cursor]. Applications will typically - * use higher-level GTK functions such as `gtk_widget_set_cursor()` instead. + * use higher-level GTK functions such as [method@Gtk.Widget.set_cursor]` + * instead. * * Cursors are not bound to a given [class@Gdk.Display], so they can be shared. * However, the appearance of cursors may vary when used on different @@ -68,20 +68,11 @@ * and provide an image to use for the cursor. * * To ease work with unsupported cursors, a fallback cursor can be provided. - * If a [class@Gdk.Surface] cannot use a cursor because of the reasons mentioned above, - * it will try the fallback cursor. Fallback cursors can themselves have fallback - * cursors again, so it is possible to provide a chain of progressively easier - * to support cursors. If none of the provided cursors can be supported, the - * default cursor will be the ultimate fallback. - */ - -/** - * GdkCursor: - * - * A #GdkCursor represents a cursor. Its contents are private. - * - * Cursors are immutable objects, so they can not change after - * they have been constructed. + * If a [class@Gdk.Surface] cannot use a cursor because of the reasons mentioned + * above, it will try the fallback cursor. Fallback cursors can themselves have + * fallback cursors again, so it is possible to provide a chain of progressively + * easier to support cursors. If none of the provided cursors can be supported, + * the default cursor will be the ultimate fallback. */ enum { @@ -178,6 +169,11 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class) object_class->set_property = gdk_cursor_set_property; object_class->finalize = gdk_cursor_finalize; + /** + * GdkCursor:fallback: + * + * Cursor to fall back to if this cursor cannot be displayed. + */ g_object_class_install_property (object_class, PROP_FALLBACK, g_param_spec_object ("fallback", @@ -186,6 +182,12 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class) GDK_TYPE_CURSOR, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); + + /** + * GdkCursor:hotspot-x: + * + * X position of the cursor hotspot in the cursor image. + */ g_object_class_install_property (object_class, PROP_HOTSPOT_X, g_param_spec_int ("hotspot-x", @@ -194,6 +196,12 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class) 0, G_MAXINT, 0, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); + + /** + * GdkCursor:hotspot-y: + * + * Y position of the cursor hotspot in the cursor image. + */ g_object_class_install_property (object_class, PROP_HOTSPOT_Y, g_param_spec_int ("hotspot-y", @@ -202,6 +210,14 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class) 0, G_MAXINT, 0, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); + + /** + * GdkCursor:name: + * + * Name of this this cursor. + * + * The name will be %NULL if the cursor was created from a texture. + */ g_object_class_install_property (object_class, PROP_NAME, g_param_spec_string ("name", @@ -210,6 +226,14 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class) NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); + + /** + * GdkCursor:texture: + * + * The texture displayed by this cursor. + * + * The texture will be %NULL if the cursor was created from a name. + */ g_object_class_install_property (object_class, PROP_TEXTURE, g_param_spec_object ("texture", @@ -274,7 +298,7 @@ gdk_cursor_equal (gconstpointer a, /** * gdk_cursor_new_from_name: * @name: the name of the cursor - * @fallback: (allow-none): %NULL or the #GdkCursor to fall back to when + * @fallback: (allow-none): %NULL or the `GdkCursor` to fall back to when * this one cannot be supported * * Creates a new cursor by looking up @name in the current cursor @@ -282,6 +306,7 @@ gdk_cursor_equal (gconstpointer a, * * A recommended set of cursor names that will work across different * platforms can be found in the CSS specification: + * * - "none" * - ![](default_cursor.png) "default" * - ![](help_cursor.png) "help" @@ -319,7 +344,7 @@ gdk_cursor_equal (gconstpointer a, * - ![](zoom_out_cursor.png) "zoom-out" * * - * Returns: (nullable): a new #GdkCursor, or %NULL if there is no + * Returns: (nullable): a new `GdkCursor`, or %NULL if there is no * cursor with the given name */ GdkCursor * @@ -340,12 +365,12 @@ gdk_cursor_new_from_name (const char *name, * @texture: the texture providing the pixel data * @hotspot_x: the horizontal offset of the “hotspot” of the cursor * @hotspot_y: the vertical offset of the “hotspot” of the cursor - * @fallback: (allow-none): %NULL or the #GdkCursor to fall back to when + * @fallback: (allow-none): %NULL or the `GdkCursor` to fall back to when * this one cannot be supported * - * Creates a new cursor from a #GdkTexture. + * Creates a new cursor from a `GdkTexture`. * - * Returns: a new #GdkCursor. + * Returns: a new `GdkCursor` */ GdkCursor * gdk_cursor_new_from_texture (GdkTexture *texture, @@ -368,18 +393,18 @@ gdk_cursor_new_from_texture (GdkTexture *texture, /** * gdk_cursor_get_fallback: - * @cursor: a #GdkCursor. + * @cursor: a `GdkCursor` * - * Returns the fallback for this @cursor. The fallback will be used if this - * cursor is not available on a given #GdkDisplay. + * Returns the fallback for this @cursor. * - * For named cursors, this can happen when using nonstandard names or when - * using an incomplete cursor theme. - * For textured cursors, this can happen when the texture is too large or - * when the #GdkDisplay it is used on does not support textured cursors. + * The fallback will be used if this cursor is not available on a given + * `GdkDisplay`. For named cursors, this can happen when using nonstandard + * names or when using an incomplete cursor theme. For textured cursors, + * this can happen when the texture is too large or when the `GdkDisplay` + * it is used on does not support textured cursors. * - * Returns: (transfer none) (nullable): the fallback of the cursor or %NULL to use - * the default cursor as fallback. + * Returns: (transfer none) (nullable): the fallback of the cursor or %NULL + * to use the default cursor as fallback. */ GdkCursor * gdk_cursor_get_fallback (GdkCursor *cursor) @@ -391,13 +416,14 @@ gdk_cursor_get_fallback (GdkCursor *cursor) /** * gdk_cursor_get_name: - * @cursor: a #GdkCursor. + * @cursor: a `GdkCursor` * - * Returns the name of the cursor. If the cursor is not a named cursor, %NULL - * will be returned. + * Returns the name of the cursor. * - * Returns: (transfer none) (nullable): the name of the cursor or %NULL if it is not - * a named cursor + * If the cursor is not a named cursor, %NULL will be returned. + * + * Returns: (transfer none) (nullable): the name of the cursor or %NULL + * if it is not a named cursor */ const char * gdk_cursor_get_name (GdkCursor *cursor) @@ -411,11 +437,12 @@ gdk_cursor_get_name (GdkCursor *cursor) * gdk_cursor_get_texture: * @cursor: a #GdkCursor. * - * Returns the texture for the cursor. If the cursor is a named cursor, %NULL - * will be returned. + * Returns the texture for the cursor. * - * Returns: (transfer none) (nullable): the texture for cursor or %NULL if it is a - * named cursor + * If the cursor is a named cursor, %NULL will be returned. + * + * Returns: (transfer none) (nullable): the texture for cursor or %NULL + * if it is a named cursor */ GdkTexture * gdk_cursor_get_texture (GdkCursor *cursor) @@ -427,14 +454,15 @@ gdk_cursor_get_texture (GdkCursor *cursor) /** * gdk_cursor_get_hotspot_x: - * @cursor: a #GdkCursor. + * @cursor: a `GdkCursor` * - * Returns the horizontal offset of the hotspot. The hotspot indicates the - * pixel that will be directly above the 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(). + * [ctor@Gdk.Cursor.new_from_texture]. * * Returns: the horizontal offset of the hotspot or 0 for named cursors */ @@ -448,14 +476,15 @@ gdk_cursor_get_hotspot_x (GdkCursor *cursor) /** * gdk_cursor_get_hotspot_y: - * @cursor: a #GdkCursor. + * @cursor: a `GdkCursor` * - * Returns the vertical offset of the hotspot. The hotspot indicates the - * pixel that will be directly above the 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(). + * [ctor@Gdk.Cursor.new_from_texture]. * * Returns: the vertical offset of the hotspot or 0 for named cursors */ diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c index f96dbc5e65..e4d24016fd 100644 --- a/gdk/gdkdevice.c +++ b/gdk/gdkdevice.c @@ -26,24 +26,14 @@ #include "gdkintl.h" #include "gdkkeysprivate.h" -/** - * SECTION:gdkdevice - * @Short_description: Object representing an input device - * @Title: GdkDevice - * @See_also: #GdkSeat - * - * The #GdkDevice object represents a single input device, such - * as a keyboard, a mouse, a touchpad, etc. - * - * See the #GdkSeat documentation for more information about the - * various kinds of devices, and their relationships. - */ - /** * GdkDevice: * - * The GdkDevice struct contains only private fields and - * should not be accessed directly. + * The `GdkDevice` object represents an input device, such + * as a keyboard, a mouse, or a touchpad. + * + * See the [class@Gdk.Seat] documentation for more information + * about the various kinds of devices, and their relationships. */ typedef struct _GdkAxisInfo GdkAxisInfo; @@ -182,7 +172,9 @@ gdk_device_class_init (GdkDeviceClass *klass) /** * GdkDevice:vendor-id: * - * Vendor ID of this device, see gdk_device_get_vendor_id(). + * Vendor ID of this device. + * + * See [method@Gdk.Device.get_vendor_id]. */ device_props[PROP_VENDOR_ID] = g_param_spec_string ("vendor-id", @@ -195,7 +187,9 @@ gdk_device_class_init (GdkDeviceClass *klass) /** * GdkDevice:product-id: * - * Product ID of this device, see gdk_device_get_product_id(). + * Product ID of this device. + * + * See [method@Gdk.Device.get_product_id]. */ device_props[PROP_PRODUCT_ID] = g_param_spec_string ("product-id", @@ -208,7 +202,7 @@ gdk_device_class_init (GdkDeviceClass *klass) /** * GdkDevice:seat: * - * #GdkSeat of this device. + * `GdkSeat` of this device. */ device_props[PROP_SEAT] = g_param_spec_object ("seat", @@ -222,6 +216,7 @@ gdk_device_class_init (GdkDeviceClass *klass) * GdkDevice:num-touches: * * The maximal number of concurrent touches on a touch device. + * * Will be 0 if the device is not a touch device or if the number * of touches is unknown. */ @@ -234,6 +229,11 @@ gdk_device_class_init (GdkDeviceClass *klass) G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS); + /** + * GdkDevice:tool: + * + * The `GdkDeviceTool` that is currently used with this device. + */ device_props[PROP_TOOL] = g_param_spec_object ("tool", P_("Tool"), @@ -241,6 +241,13 @@ gdk_device_class_init (GdkDeviceClass *klass) GDK_TYPE_DEVICE_TOOL, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + /** + * GdkDevice:direction: + * + * The direction of the current layout. + * + * This is only relevant for keyboard devices. + */ device_props[PROP_DIRECTION] = g_param_spec_enum ("direction", P_("Direction"), @@ -248,6 +255,13 @@ gdk_device_class_init (GdkDeviceClass *klass) PANGO_TYPE_DIRECTION, PANGO_DIRECTION_NEUTRAL, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + /** + * GdkDevice:direction: + * + * Whether the device has both right-to-left and left-to-right layouts. + * + * This is only relevant for keyboard devices. + */ device_props[PROP_HAS_BIDI_LAYOUTS] = g_param_spec_boolean ("has-bidi-layouts", P_("Has bidi layouts"), @@ -255,6 +269,13 @@ gdk_device_class_init (GdkDeviceClass *klass) FALSE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + /** + * GdkDevice:caps-lock-state: + * + * Whether Caps Lock is on. + * + * This is only relevant for keyboard devices. + */ device_props[PROP_CAPS_LOCK_STATE] = g_param_spec_boolean ("caps-lock-state", P_("Caps lock state"), @@ -262,6 +283,13 @@ gdk_device_class_init (GdkDeviceClass *klass) FALSE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + /** + * GdkDevice:num-lock-state: + * + * Whether Num Lock is on. + * + * This is only relevant for keyboard devices. + */ device_props[PROP_NUM_LOCK_STATE] = g_param_spec_boolean ("num-lock-state", P_("Num lock state"), @@ -269,6 +297,13 @@ gdk_device_class_init (GdkDeviceClass *klass) FALSE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + /** + * GdkDevice:scroll-lock-state: + * + * Whether Scroll Lock is on. + * + * This is only relevant for keyboard devices. + */ device_props[PROP_SCROLL_LOCK_STATE] = g_param_spec_boolean ("scroll-lock-state", P_("Scroll lock state"), @@ -276,6 +311,13 @@ gdk_device_class_init (GdkDeviceClass *klass) FALSE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + /** + * GdkDevice:modifier-state: + * + * The current modifier state of the device. + * + * This is only relevant for keyboard devices. + */ device_props[PROP_MODIFIER_STATE] = g_param_spec_flags ("modifier-state", P_("Modifier state"), @@ -287,11 +329,11 @@ gdk_device_class_init (GdkDeviceClass *klass) /** * GdkDevice::changed: - * @device: the #GdkDevice that changed. + * @device: the `GdkDevice` * - * The ::changed signal is emitted either when the #GdkDevice - * has changed the number of either axes or keys. For example - * on X11 this will normally happen when the physical device + * Emitted either when the the number of either axes or keys changes. + * + * On X11 this will normally happen when the physical device * routing events through the logical device changes (for * example, user switches from the USB mouse to a tablet); in * that case the logical device will change to reflect the axes @@ -307,11 +349,10 @@ gdk_device_class_init (GdkDeviceClass *klass) /** * GdkDevice::tool-changed: - * @device: the #GdkDevice that changed. + * @device: the `GdkDevice` * @tool: The new current tool * - * The ::tool-changed signal is emitted on pen/eraser - * #GdkDevices whenever tools enter or leave proximity. + * Emitted on pen/eraser devices whenever tools enter or leave proximity. */ signals[TOOL_CHANGED] = g_signal_new (g_intern_static_string ("tool-changed"), @@ -478,19 +519,21 @@ gdk_device_get_property (GObject *object, /** * gdk_device_get_surface_at_position: - * @device: pointer #GdkDevice to query info to. + * @device: pointer `GdkDevice` to query info to * @win_x: (out) (allow-none): return location for the X coordinate of the device location, * relative to the surface origin, or %NULL. * @win_y: (out) (allow-none): return location for the Y coordinate of the device location, * relative to the surface origin, or %NULL. * - * Obtains the surface underneath @device, returning the location of the device in @win_x and @win_y in - * double precision. Returns %NULL if the surface tree under @device is not known to GDK (for example, - * belongs to another application). + * Obtains the surface underneath @device, returning the location of the + * device in @win_x and @win_y * - * Returns: (nullable) (transfer none): the #GdkSurface under the - * device position, or %NULL. - **/ + * Returns %NULL if the surface tree under @device is not known to GDK + * (for example, belongs to another application). + * + * Returns: (nullable) (transfer none): the `GdkSurface` under the + * device position, or %NULL + */ GdkSurface * gdk_device_get_surface_at_position (GdkDevice *device, double *win_x, @@ -514,13 +557,12 @@ gdk_device_get_surface_at_position (GdkDevice *device, /** * gdk_device_get_name: - * @device: a #GdkDevice + * @device: a GdkDevice` * - * Determines the name of the device, suitable - * for showing in a user interface. + * The name of the device, suitable for showing in a user interface. * * Returns: a name - **/ + */ const char * gdk_device_get_name (GdkDevice *device) { @@ -531,14 +573,15 @@ gdk_device_get_name (GdkDevice *device) /** * gdk_device_get_has_cursor: - * @device: a #GdkDevice + * @device: a `GdkDevice` * * Determines whether the pointer follows device motion. + * * This is not meaningful for keyboard devices, which * don't have a pointer. * * Returns: %TRUE if the pointer follows device motion - **/ + */ gboolean gdk_device_get_has_cursor (GdkDevice *device) { @@ -549,12 +592,12 @@ gdk_device_get_has_cursor (GdkDevice *device) /** * gdk_device_get_source: - * @device: a #GdkDevice + * @device: a `GdkDevice` * * Determines the type of the device. * - * Returns: a #GdkInputSource - **/ + * Returns: a `GdkInputSource` + */ GdkInputSource gdk_device_get_source (GdkDevice *device) { @@ -565,13 +608,13 @@ gdk_device_get_source (GdkDevice *device) /** * gdk_device_get_axis_use: - * @device: a pointer #GdkDevice. - * @index_: the index of the axis. + * @device: a pointer `GdkDevice` + * @index_: the index of the axi. * * Returns the axis use for @index_. * - * Returns: a #GdkAxisUse specifying how the axis is used. - **/ + * Returns: a `GdkAxisUse` specifying how the axis is used. + */ GdkAxisUse gdk_device_get_axis_use (GdkDevice *device, guint index_) @@ -589,13 +632,12 @@ gdk_device_get_axis_use (GdkDevice *device, /** * gdk_device_get_display: - * @device: a #GdkDevice + * @device: a `GdkDevice` * - * Returns the #GdkDisplay to which @device pertains. + * Returns the `GdkDisplay` to which @device pertains. * - * Returns: (transfer none): a #GdkDisplay. This memory is owned - * by GTK, and must not be freed or unreffed. - **/ + * Returns: (transfer none): a `GdkDisplay` + */ GdkDisplay * gdk_device_get_display (GdkDevice *device) { @@ -616,13 +658,13 @@ _gdk_device_set_associated_device (GdkDevice *device, /* * gdk_device_list_physical_devices: - * @device: a logical #GdkDevice + * @device: a logical `GdkDevice` * * Returns the list of physical devices attached to the given logical - * #GdkDevice. + * `GdkDevice`. * * Returns: (nullable) (transfer container) (element-type GdkDevice): - * the list of physical devices attached to a logical #GdkDevice + * the list of physical devices attached to a logical `GdkDevice` */ GList * gdk_device_list_physical_devices (GdkDevice *device) @@ -655,12 +697,12 @@ _gdk_device_remove_physical_device (GdkDevice *device, /* * gdk_device_get_n_axes: - * @device: a pointer #GdkDevice + * @device: a pointer `GdkDevice` * * Returns the number of axes the device currently has. * * Returns: the number of axes. - **/ + */ int gdk_device_get_n_axes (GdkDevice *device) { @@ -672,16 +714,16 @@ gdk_device_get_n_axes (GdkDevice *device) /* * gdk_device_get_axis: (skip) - * @device: a #GdkDevice + * @device: a `GdkDevice` * @axes: (array): pointer to an array of axes * @use: the use to look for - * @value: (out): location to store the found value. + * @value: (out): location to store the found value * - * Interprets an array of double as axis values for a given device, - * and locates the value in the array for a given axis use. + * Interprets an array of `double` as axis values and get the value + * for a given axis use. * * Returns: %TRUE if the given axis use was found, otherwise %FALSE - **/ + */ gboolean gdk_device_get_axis (GdkDevice *device, double *axes, @@ -1073,16 +1115,17 @@ _gdk_device_surface_at_position (GdkDevice *device, /** * gdk_device_get_vendor_id: - * @device: a physical #GdkDevice + * @device: a physical `GdkDevice` * - * Returns the vendor ID of this device, or %NULL if this information couldn't - * be obtained. This ID is retrieved from the device, and is thus constant for - * it. + * Returns the vendor ID of this device. * - * This function, together with gdk_device_get_product_id(), can be used to eg. - * compose #GSettings paths to store settings for this device. + * This ID is retrieved from the device, and does not change. * - * |[ + * This function, together with [method@Gdk.Device.get_product_id], + * can be used to eg. compose `GSettings` paths to store settings + * for this device. + * + * ```c * static GSettings * * get_device_settings (GdkDevice *device) * { @@ -1100,7 +1143,7 @@ _gdk_device_surface_at_position (GdkDevice *device, * * return settings; * } - * ]| + * ``` * * Returns: (nullable): the vendor ID, or %NULL */ @@ -1114,11 +1157,12 @@ gdk_device_get_vendor_id (GdkDevice *device) /** * gdk_device_get_product_id: - * @device: a physical #GdkDevice + * @device: a physical `GdkDevice` * - * Returns the product ID of this device, or %NULL if this information couldn't - * be obtained. This ID is retrieved from the device, and is thus constant for - * it. See gdk_device_get_vendor_id() for more information. + * Returns the product ID of this device. + * + * This ID is retrieved from the device, and does not change. + * See [method@Gdk.Device.get_vendor_id] for more information. * * Returns: (nullable): the product ID, or %NULL */ @@ -1148,10 +1192,10 @@ gdk_device_set_seat (GdkDevice *device, * gdk_device_get_seat: * @device: A #GdkDevice * - * Returns the #GdkSeat the device belongs to. + * Returns the `GdkSeat` the device belongs to. * - * Returns: (transfer none): a #GdkSeat - **/ + * Returns: (transfer none): a `GdkSeat` + */ GdkSeat * gdk_device_get_seat (GdkDevice *device) { @@ -1175,7 +1219,7 @@ gdk_device_update_tool (GdkDevice *device, /** * gdk_device_get_num_touches: - * @device: a #GdkDevice + * @device: a `GdkDevice` * * Retrieves the number of touch points associated to @device. * @@ -1191,11 +1235,11 @@ gdk_device_get_num_touches (GdkDevice *device) /** * gdk_device_get_device_tool: - * @device: a #GdkDevice + * @device: a `GdkDevice` * - * Retrieves the #GdkDeviceTool associated to @device. + * Retrieves the current tool for @device. * - * Returns: (transfer none): the #GdkDeviceTool + * Returns: (transfer none): the `GdkDeviceTool`, or %NULL */ GdkDeviceTool * gdk_device_get_device_tool (GdkDevice *device) @@ -1207,10 +1251,11 @@ gdk_device_get_device_tool (GdkDevice *device) /** * gdk_device_get_caps_lock_state: - * @device: a #GdkDevice + * @device: a `GdkDevice` * - * Retrieves whether the Caps Lock modifier of the - * keyboard is locked, if @device is a keyboard device. + * Retrieves whether the Caps Lock modifier of the keyboard is locked. + * + * This is only relevant for keyboard devices. * * Returns: %TRUE if Caps Lock is on for @device */ @@ -1227,10 +1272,11 @@ gdk_device_get_caps_lock_state (GdkDevice *device) /** * gdk_device_get_num_lock_state: - * @device: a #GdkDevice + * @device: a ``GdkDevice` * - * Retrieves whether the Num Lock modifier of the - * keyboard is locked, if @device is a keyboard device. + * Retrieves whether the Num Lock modifier of the keyboard is locked. + * + * This is only relevant for keyboard devices. * * Returns: %TRUE if Num Lock is on for @device */ @@ -1247,10 +1293,11 @@ gdk_device_get_num_lock_state (GdkDevice *device) /** * gdk_device_get_scroll_lock_state: - * @device: a #GdkDevice + * @device: a `GdkDevice` * - * Retrieves whether the Scroll Lock modifier of the - * keyboard is locked, if @device is a keyboard device. + * Retrieves whether the Scroll Lock modifier of the keyboard is locked. + * + * This is only relevant for keyboard devices. * * Returns: %TRUE if Scroll Lock is on for @device */ @@ -1267,10 +1314,11 @@ gdk_device_get_scroll_lock_state (GdkDevice *device) /** * gdk_device_get_modifier_state: - * @device: a #GdkDevice + * @device: a `GdkDevice` * - * Retrieves the current modifier state of the keyboard, - * if @device is a keyboard device. + * Retrieves the current modifier state of the keyboard. + * + * This is only relevant for keyboard devices. * * Returns: the current modifier state */ @@ -1287,13 +1335,14 @@ gdk_device_get_modifier_state (GdkDevice *device) /** * gdk_device_get_direction: - * @device: a #GdkDevice + * @device: a `GdkDevice` * - * Returns the direction of effective layout of the keyboard, - * if @device is a keyboard device. + * Returns the direction of effective layout of the keyboard. + * + * This is only relevant for keyboard devices. * * The direction of a layout is the direction of the majority - * of its symbols. See pango_unichar_direction(). + * of its symbols. See [func@Pango.unichar_direction]. * * Returns: %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL * if it can determine the direction. %PANGO_DIRECTION_NEUTRAL @@ -1312,11 +1361,12 @@ gdk_device_get_direction (GdkDevice *device) /** * gdk_device_has_bidi_layouts: - * @device: a #GdkDevice + * @device: a `GdkDevice` * - * Determines if keyboard layouts for both right-to-left and - * left-to-right languages are in use on the keyboard, if - * @device is a keyboard device. + * Determines if layouts for both right-to-left and + * left-to-right languages are in use on the keyboard. + * + * This is only relevant for keyboard devices. * * Returns: %TRUE if there are layouts with both directions, * %FALSE otherwise diff --git a/gdk/gdkdevicepad.c b/gdk/gdkdevicepad.c index 7e108e9c97..ac25d0a873 100644 --- a/gdk/gdkdevicepad.c +++ b/gdk/gdkdevicepad.c @@ -18,33 +18,24 @@ */ /** - * SECTION:gdkdevicepad - * @Short_description: Pad device interface - * @Title: GtkDevicePad + * 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 * by the pad device. * * Tablet pads may contain one or more groups, each containing a subset - * of the buttons/rings/strips available. gdk_device_pad_get_n_groups() - * can be used to obtain the number of groups, gdk_device_pad_get_n_features() - * and gdk_device_pad_get_feature_group() can be combined to find out the - * number of buttons/rings/strips the device has, and how are they grouped. + * of the buttons/rings/strips available. [method@Gdk.DevicePad.get_n_groups] + * can be used to obtain the number of groups, [method@Gdk.DevicePad.get_n_features] + * and [method@Gdk.DevicePad.get_feature_group] can be combined to find out + * the number of buttons/rings/strips the device has, and how are they grouped. * * Each of those groups have different modes, which may be used to map each * individual pad feature to multiple actions. Only one mode is effective * (current) for each given group, different groups may have different * current modes. The number of available modes in a group can be found - * out through gdk_device_pad_get_group_n_modes(), and the current mode for - * a given group will be notified through events of type #GDK_PAD_GROUP_MODE. - */ - -/** - * GdkDevicePad: - * - * The GdkDevicePad struct contains only private fields and - * should not be accessed directly. + * out through [method@Gdk.DevicePad.get_group_n_modes], and the current mode + * for a given group will be notified through events of type #GDK_PAD_GROUP_MODE. */ #include "config.h" @@ -62,15 +53,16 @@ gdk_device_pad_default_init (GdkDevicePadInterface *pad) /** * gdk_device_pad_get_n_groups: - * @pad: a #GdkDevicePad + * @pad: a `GdkDevicePad` * - * Returns the number of groups this pad device has. Pads have - * at least one group. A pad group is a subcollection of + * Returns the number of groups this pad device has. + * + * Pads have at least one group. A pad group is a subcollection of * buttons/strip/rings that is affected collectively by a same * current mode. * * Returns: The number of button/ring/strip groups in the pad. - **/ + */ int gdk_device_pad_get_n_groups (GdkDevicePad *pad) { @@ -83,13 +75,13 @@ gdk_device_pad_get_n_groups (GdkDevicePad *pad) /** * gdk_device_pad_get_group_n_modes: - * @pad: a #GdkDevicePad + * @pad: a `GdkDevicePad` * @group_idx: group to get the number of available modes from * * Returns the number of modes that @group may have. * * Returns: The number of modes available in @group. - **/ + */ int gdk_device_pad_get_group_n_modes (GdkDevicePad *pad, int group_idx) @@ -104,13 +96,13 @@ gdk_device_pad_get_group_n_modes (GdkDevicePad *pad, /** * gdk_device_pad_get_n_features: - * @pad: a #GdkDevicePad + * @pad: a `GdkDevicePad` * @feature: a pad feature * * Returns the number of features a tablet pad has. * * Returns: The amount of elements of type @feature that this pad has. - **/ + */ int gdk_device_pad_get_n_features (GdkDevicePad *pad, GdkDevicePadFeature feature) @@ -124,15 +116,16 @@ gdk_device_pad_get_n_features (GdkDevicePad *pad, /** * gdk_device_pad_get_feature_group: - * @pad: a #GdkDevicePad + * @pad: a `GdkDevicePad` * @feature: the feature type to get the group from * @feature_idx: the index of the feature to get the group from * - * Returns the group the given @feature and @idx belong to, - * or -1 if feature/index do not exist in @pad. + * Returns the group the given @feature and @idx belong to. + * + * f the feature or index do not exist in @pad, -1 is returned. * * Returns: The group number of the queried pad feature. - **/ + */ int gdk_device_pad_get_feature_group (GdkDevicePad *pad, GdkDevicePadFeature feature, diff --git a/gdk/gdkdevicetool.c b/gdk/gdkdevicetool.c index 0cfcf800bf..fba863bb7c 100644 --- a/gdk/gdkdevicetool.c +++ b/gdk/gdkdevicetool.c @@ -23,6 +23,11 @@ #include "gdkinternals.h" #include "gdkintl.h" +/** + * GdkDeviceTool: + * + * A physical tool associated to a `GdkDevice`. + */ G_DEFINE_TYPE (GdkDeviceTool, gdk_device_tool, G_TYPE_OBJECT) @@ -101,6 +106,11 @@ gdk_device_tool_class_init (GdkDeviceToolClass *klass) object_class->set_property = gdk_device_tool_set_property; object_class->get_property = gdk_device_tool_get_property; + /** + * GdkDeviceTool:serial: + * + * The serial number of the tool. + */ tool_props[TOOL_PROP_SERIAL] = g_param_spec_uint64 ("serial", "Serial", "Serial number", @@ -108,6 +118,12 @@ gdk_device_tool_class_init (GdkDeviceToolClass *klass) G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS); + + /** + * GdkDeviceTool:tool-type: + * + * The type of the tool. + */ tool_props[TOOL_PROP_TOOL_TYPE] = g_param_spec_enum ("tool-type", "Tool type", "Tool type", @@ -116,12 +132,24 @@ gdk_device_tool_class_init (GdkDeviceToolClass *klass) G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS); + + /** + * GdkDeviceTool:axes: + * + * The axes of the tool. + */ tool_props[TOOL_PROP_AXES] = g_param_spec_flags ("axes", "Axes", "Tool axes", GDK_TYPE_AXIS_FLAGS, 0, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY); + + /** + * GdkDeviceTool:hardware-id: + * + * The hardware ID of the tool. + */ tool_props[TOOL_PROP_HARDWARE_ID] = g_param_spec_uint64 ("hardware-id", "Hardware ID", "Hardware ID", @@ -154,13 +182,15 @@ gdk_device_tool_new (guint64 serial, /** * gdk_device_tool_get_serial: - * @tool: a #GdkDeviceTool + * @tool: a `GdkDeviceTool` * - * Gets the serial of this tool, this value can be used to identify a - * physical tool (eg. a tablet pen) across program executions. + * Gets the serial number of this tool. + * + * This value can be used to identify a physical tool + * (eg. a tablet pen) across program executions. * * Returns: The serial ID for this tool - **/ + */ guint64 gdk_device_tool_get_serial (GdkDeviceTool *tool) { @@ -171,20 +201,22 @@ gdk_device_tool_get_serial (GdkDeviceTool *tool) /** * gdk_device_tool_get_hardware_id: - * @tool: a #GdkDeviceTool + * @tool: a `GdkDeviceTool` * - * Gets the hardware ID of this tool, or 0 if it's not known. When - * non-zero, the identificator is unique for the given tool model, + * Gets the hardware ID of this tool, or 0 if it's not known. + * + * When non-zero, the identificator is unique for the given tool model, * meaning that two identical tools will share the same @hardware_id, - * but will have different serial numbers (see gdk_device_tool_get_serial()). + * but will have different serial numbers (see + * [method@Gdk.DeviceTool.get_serial]). * * This is a more concrete (and device specific) method to identify - * a #GdkDeviceTool than gdk_device_tool_get_tool_type(), as a tablet - * may support multiple devices with the same #GdkDeviceToolType, - * but having different hardware identificators. + * a `GdkDeviceTool` than [method@Gdk.DeviceTool.get_tool_type], + * as a tablet may support multiple devices with the same + * `GdkDeviceToolType`, but different hardware identificators. * * Returns: The hardware identificator of this tool. - **/ + */ guint64 gdk_device_tool_get_hardware_id (GdkDeviceTool *tool) { @@ -195,13 +227,14 @@ gdk_device_tool_get_hardware_id (GdkDeviceTool *tool) /** * gdk_device_tool_get_tool_type: - * @tool: a #GdkDeviceTool + * @tool: a `GdkDeviceTool` * - * Gets the #GdkDeviceToolType of the tool. + * Gets the `GdkDeviceToolType` of the tool. * - * Returns: The physical type for this tool. This can be used to figure out what - * sort of pen is being used, such as an airbrush or a pencil. - **/ + * Returns: The physical type for this tool. This can be used to + * figure out what sort of pen is being used, such as an airbrush + * or a pencil. + */ GdkDeviceToolType gdk_device_tool_get_tool_type (GdkDeviceTool *tool) { @@ -212,7 +245,7 @@ gdk_device_tool_get_tool_type (GdkDeviceTool *tool) /** * gdk_device_tool_get_axes: - * @tool: a #GdkDeviceTool + * @tool: a `GdkDeviceTool` * * Gets the axes of the tool. * diff --git a/gdk/gdkdevicetool.h b/gdk/gdkdevicetool.h index 16f5b3b30b..1a6a90d756 100644 --- a/gdk/gdkdevicetool.h +++ b/gdk/gdkdevicetool.h @@ -32,11 +32,6 @@ G_BEGIN_DECLS #define GDK_DEVICE_TOOL(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_DEVICE_TOOL, GdkDeviceTool)) #define GDK_IS_DEVICE_TOOL(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_DEVICE_TOOL)) -/** - * GdkDeviceTool: - * - * A physical tool associated to a #GdkDevice. - */ typedef struct _GdkDeviceTool GdkDeviceTool; /** diff --git a/gdk/gdkdisplaymanager.c b/gdk/gdkdisplaymanager.c index 41d9728288..f1fbad2897 100644 --- a/gdk/gdkdisplaymanager.c +++ b/gdk/gdkdisplaymanager.c @@ -54,23 +54,26 @@ #endif /** - * SECTION:gdkdisplaymanager - * @Short_description: Maintains a list of all open GdkDisplays - * @Title: GdkDisplayManager + * GdkDisplayManager: * - * The purpose of the #GdkDisplayManager singleton object is to offer - * notification when displays appear or disappear or the default display - * changes. + * A singleton object that offers notification when displays appear or + * disappear. * - * You can use gdk_display_manager_get() to obtain the #GdkDisplayManager + * You can use [func@Gdk.DisplayManager.get] to obtain the `GdkDisplayManager` * singleton, but that should be rarely necessary. Typically, initializing * GTK opens a display that you can work with without ever accessing the - * #GdkDisplayManager. + * `GdkDisplayManager`. * * The GDK library can be built with support for multiple backends. - * The #GdkDisplayManager object determines which backend is used + * The `GdkDisplayManager` object determines which backend is used * at runtime. * + * In the rare case that you need to influence which of the backends + * is being used, you can use [func@Gdk.set_allowed_backends]. Note + * that you need to call this function before initializing GTK. + * + * ## Backend-specific code + * * When writing backend-specific code that is supposed to work with * multiple GDK backends, you have to consider both compile time and * runtime. At compile time, use the #GDK_WINDOWING_X11, #GDK_WINDOWING_WIN32 @@ -78,9 +81,7 @@ * you are building your application against. At runtime, use type-check * macros like GDK_IS_X11_DISPLAY() to find out which backend is in use: * - * ## Backend-specific code ## {#backend-specific} - * - * |[ + * ```c * #ifdef GDK_WINDOWING_X11 * if (GDK_IS_X11_DISPLAY (display)) * { @@ -96,14 +97,7 @@ * else * #endif * g_error ("Unsupported GDK backend"); - * ]| - */ - -/** - * GdkDisplayManager: - * - * The GdkDisplayManager struct contains only private fields and - * should not be accessed directly. + * ``` */ enum { @@ -142,7 +136,7 @@ gdk_display_manager_class_init (GdkDisplayManagerClass *klass) * @manager: the object on which the signal is emitted * @display: the opened display * - * The ::display-opened signal is emitted when a display is opened. + * Emitted when a display is opened. */ signals[DISPLAY_OPENED] = g_signal_new (g_intern_static_string ("display-opened"), @@ -155,6 +149,11 @@ gdk_display_manager_class_init (GdkDisplayManagerClass *klass) 1, GDK_TYPE_DISPLAY); + /** + * GdkDisplayManager:default-display: + * + * The default display. + */ g_object_class_install_property (object_class, PROP_DEFAULT_DISPLAY, g_param_spec_object ("default-display", @@ -218,25 +217,31 @@ static const char *allowed_backends; * * By default, GDK tries all included backends. * - * For example, - * |[ - * gdk_set_allowed_backends ("wayland,quartz,*"); - * ]| - * instructs GDK to try the Wayland backend first, - * followed by the Quartz backend, and then all - * others. + * For example: * - * If the `GDK_BACKEND` environment variable - * is set, it determines what backends are tried in what - * order, while still respecting the set of allowed backends - * that are specified by this function. + * ```c + * gdk_set_allowed_backends ("wayland,macos,*"); + * ``` * - * The possible backend names are x11, win32, quartz, - * broadway, wayland. You can also include a * in the - * list to try all remaining backends. + * instructs GDK to try the Wayland backend first, followed by the + * MacOs backend, and then all others. * - * This call must happen prior to gdk_display_open(), - * gtk_init(), or gtk_init_check() + * If the `GDK_BACKEND` environment variable is set, it determines + * what backends are tried in what order, while still respecting the + * set of allowed backends that are specified by this function. + * + * The possible backend names are: + * + * - `broadway` + * - `macos` + * - `wayland`. + * - `win32` + * - `x11` + * + * You can also include a `*` in the list to try all remaining backends. + * + * This call must happen prior to functions that open a display, such + * as [func@Gdk.Display.open], `gtk_init()`, or `gtk_init_check()` * in order to take effect. */ void @@ -275,16 +280,18 @@ static GdkBackend gdk_backends[] = { /** * gdk_display_manager_get: * - * Gets the singleton #GdkDisplayManager object. + * Gets the singleton `GdkDisplayManager` object. * * When called for the first time, this function consults the - * `GDK_BACKEND` environment variable to find out which - * of the supported GDK backends to use (in case GDK has been compiled - * with multiple backends). Applications can use gdk_set_allowed_backends() - * to limit what backends can be used. + * `GDK_BACKEND` environment variable to find out which of the + * supported GDK backends to use (in case GDK has been compiled + * with multiple backends). * - * Returns: (transfer none): The global #GdkDisplayManager singleton - **/ + * Applications can use [func@set_allowed_backends] to limit what + * backends wil be used. + * + * Returns: (transfer none): The global `GdkDisplayManager` singleton + */ GdkDisplayManager* gdk_display_manager_get (void) { @@ -298,11 +305,11 @@ gdk_display_manager_get (void) /** * gdk_display_manager_get_default_display: - * @manager: a #GdkDisplayManager + * @manager: a `GdkDisplayManager` * - * Gets the default #GdkDisplay. + * Gets the default `GdkDisplay`. * - * Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if + * Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL if * there is no default display. */ GdkDisplay * @@ -314,12 +321,13 @@ gdk_display_manager_get_default_display (GdkDisplayManager *manager) /** * gdk_display_get_default: * - * Gets the default #GdkDisplay. This is a convenience - * function for: + * Gets the default `GdkDisplay`. + * + * This is a convenience function for: * `gdk_display_manager_get_default_display (gdk_display_manager_get ())`. * - * Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if - * there is no default display. + * Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL if + * there is no default display */ GdkDisplay * gdk_display_get_default (void) @@ -329,11 +337,11 @@ gdk_display_get_default (void) /** * gdk_display_manager_set_default_display: - * @manager: a #GdkDisplayManager - * @display: a #GdkDisplay + * @manager: a `GdkDisplayManager` + * @display: a `GdkDisplay` * * Sets @display as the default display. - **/ + */ void gdk_display_manager_set_default_display (GdkDisplayManager *manager, GdkDisplay *display) @@ -348,14 +356,14 @@ gdk_display_manager_set_default_display (GdkDisplayManager *manager, /** * gdk_display_manager_list_displays: - * @manager: a #GdkDisplayManager + * @manager: a `GdkDisplayManager` * * List all currently open displays. * * Returns: (transfer container) (element-type GdkDisplay): a newly - * allocated #GSList of #GdkDisplay objects. Free with g_slist_free() + * allocated `GSList` of `GdkDisplay` objects. Free with g_slist_free() * when you are done with it. - **/ + */ GSList * gdk_display_manager_list_displays (GdkDisplayManager *manager) { @@ -364,13 +372,13 @@ gdk_display_manager_list_displays (GdkDisplayManager *manager) /** * gdk_display_manager_open_display: - * @manager: a #GdkDisplayManager + * @manager: a `GdkDisplayManager` * @name: the name of the display to open * * Opens a display. * - * Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if the - * display could not be opened + * Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL + * if the display could not be opened */ GdkDisplay * gdk_display_manager_open_display (GdkDisplayManager *manager, diff --git a/gdk/gdkdrag.c b/gdk/gdkdrag.c index 9b54924c56..4fd6bd6452 100644 --- a/gdk/gdkdrag.c +++ b/gdk/gdkdrag.c @@ -23,15 +23,12 @@ */ /** - * SECTION:gdkdrag - * @Title: Drag And Drop - * @Short_description: Functions for controlling drag and drop handling + * GdkDrag: * - * These functions provide a low-level interface for drag and drop. + * The `GdkDrag` object represents the source of an ongoing DND operation. * - * The `GdkDrag` object represents the source side of an ongoing DND operation. - * It is created when a drag is started, and stays alive for duration of - * the DND operation. After a drag has been started with [method@Gdk.Drag.begin], + * A `GdkDrag` is created when a drag is started, and stays alive for duration of + * the DND operation. After a drag has been started with [func@Gdk.Drag.begin], * the caller gets informed about the status of the ongoing drag operation * with signals on the `GdkDrag` object. * @@ -106,21 +103,14 @@ static GList *drags = NULL; G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GdkDrag, gdk_drag, G_TYPE_OBJECT) -/** - * GdkDrag: - * - * The GdkDrag struct contains only private fields and - * should not be accessed directly. - */ - /** * gdk_drag_get_display: - * @drag: a #GdkDrag + * @drag: a `GdkDrag` * - * Gets the #GdkDisplay that the drag object was created for. + * Gets the `GdkDisplay` that the drag object was created for. * - * Returns: (transfer none): a #GdkDisplay - **/ + * Returns: (transfer none): a `GdkDisplay` + */ GdkDisplay * gdk_drag_get_display (GdkDrag *drag) { @@ -133,12 +123,12 @@ gdk_drag_get_display (GdkDrag *drag) /** * gdk_drag_get_formats: - * @drag: a #GdkDrag + * @drag: a `GdkDrag` * - * Retrieves the formats supported by this GdkDrag object. + * Retrieves the formats supported by this `GdkDrag` object. * - * Returns: (transfer none): a #GdkContentFormats - **/ + * Returns: (transfer none): a `GdkContentFormats` + */ GdkContentFormats * gdk_drag_get_formats (GdkDrag *drag) { @@ -151,12 +141,12 @@ gdk_drag_get_formats (GdkDrag *drag) /** * gdk_drag_get_actions: - * @drag: a #GdkDrag + * @drag: a `GdkDrag` * * Determines the bitmask of possible actions proposed by the source. * - * Returns: the #GdkDragAction flags - **/ + * Returns: the `GdkDragAction` flags + */ GdkDragAction gdk_drag_get_actions (GdkDrag *drag) { @@ -169,12 +159,12 @@ gdk_drag_get_actions (GdkDrag *drag) /** * gdk_drag_get_selected_action: - * @drag: a #GdkDrag + * @drag: a `GdkDrag` * * Determines the action chosen by the drag destination. * - * Returns: a #GdkDragAction value - **/ + * Returns: a `GdkDragAction` value + */ GdkDragAction gdk_drag_get_selected_action (GdkDrag *drag) { @@ -187,12 +177,12 @@ gdk_drag_get_selected_action (GdkDrag *drag) /** * gdk_drag_get_device: - * @drag: a #GdkDrag + * @drag: a `GdkDrag` * - * Returns the #GdkDevice associated to the GdkDrag object. + * Returns the `GdkDevice` associated to the `GdkDrag` object. * - * Returns: (transfer none): The #GdkDevice associated to @drag. - **/ + * Returns: (transfer none): The `GdkDevice` associated to @drag. + */ GdkDevice * gdk_drag_get_device (GdkDrag *drag) { @@ -205,12 +195,12 @@ gdk_drag_get_device (GdkDrag *drag) /** * gdk_drag_get_content: - * @drag: a #GdkDrag + * @drag: a `GdkDrag` * - * Returns the #GdkContentProvider associated to the GdkDrag object. + * Returns the `GdkContentProvider` associated to the `GdkDrag` object. * - * Returns: (transfer none): The #GdkContentProvider associated to @drag. - **/ + * Returns: (transfer none): The `GdkContentProvider` associated to @drag. + */ GdkContentProvider * gdk_drag_get_content (GdkDrag *drag) { @@ -223,12 +213,12 @@ gdk_drag_get_content (GdkDrag *drag) /** * gdk_drag_get_surface: - * @drag: a #GdkDrag + * @drag: a `GdkDrag` * - * Returns the #GdkSurface where the drag originates. + * Returns the `GdkSurface` where the drag originates. * - * Returns: (transfer none): The #GdkSurface where the drag originates - **/ + * Returns: (transfer none): The `GdkSurface` where the drag originates + */ GdkSurface * gdk_drag_get_surface (GdkDrag *drag) { @@ -386,7 +376,7 @@ gdk_drag_class_init (GdkDragClass *klass) /** * GdkDrag:content: * - * The #GdkContentProvider. + * The `GdkContentProvider`. */ properties[PROP_CONTENT] = g_param_spec_object ("content", @@ -401,7 +391,7 @@ gdk_drag_class_init (GdkDragClass *klass) /** * GdkDrag:device: * - * The #GdkDevice that is performing the drag. + * The `GdkDevice` that is performing the drag. */ properties[PROP_DEVICE] = g_param_spec_object ("device", @@ -416,7 +406,7 @@ gdk_drag_class_init (GdkDragClass *klass) /** * GdkDrag:display: * - * The #GdkDisplay that the drag belongs to. + * The `GdkDisplay` that the drag belongs to. */ properties[PROP_DISPLAY] = g_param_spec_object ("display", @@ -442,6 +432,11 @@ gdk_drag_class_init (GdkDragClass *klass) G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY); + /** + * GdkDrag:selected-action: + * + * The currently selected action of the drag. + */ properties[PROP_SELECTED_ACTION] = g_param_spec_flags ("selected-action", "Selected action", @@ -452,6 +447,11 @@ gdk_drag_class_init (GdkDragClass *klass) G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY); + /** + * GdkDrag:actions: + * + * The possible actions of this drag. + */ properties[PROP_ACTIONS] = g_param_spec_flags ("actions", "Actions", @@ -462,6 +462,11 @@ gdk_drag_class_init (GdkDragClass *klass) G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY); + /** + * GdkDrag:surface: + * + * The surface where the drag originates. + */ properties[PROP_SURFACE] = g_param_spec_object ("surface", "Surface", @@ -477,7 +482,7 @@ gdk_drag_class_init (GdkDragClass *klass) * @drag: The object on which the signal is emitted * @reason: The reason the drag was cancelled * - * The drag operation was cancelled. + * Emitted when the drag operation is cancelled. */ signals[CANCEL] = g_signal_new (g_intern_static_string ("cancel"), @@ -492,7 +497,7 @@ gdk_drag_class_init (GdkDragClass *klass) * GdkDrag::drop-performed: * @drag: The object on which the signal is emitted * - * The drag operation was performed on an accepting client. + * Emitted when the drop operation is performed on an accepting client. */ signals[DROP_PERFORMED] = g_signal_new (g_intern_static_string ("drop-performed"), @@ -507,9 +512,9 @@ gdk_drag_class_init (GdkDragClass *klass) * GdkDrag::dnd-finished: * @drag: The object on which the signal is emitted * - * The drag operation was finished, the destination - * finished reading all data. The drag object can now - * free all miscellaneous data. + * Emitted when the destination side has finished reading all data. + * + * The drag object can now free all miscellaneous data. */ signals[DND_FINISHED] = g_signal_new (g_intern_static_string ("dnd-finished"), @@ -677,14 +682,15 @@ gdk_drag_set_selected_action (GdkDrag *drag, /** * gdk_drag_get_drag_surface: - * @drag: a #GdkDrag + * @drag: a `GdkDrag` * * Returns the surface on which the drag icon should be rendered - * during the drag operation. Note that the surface may not be - * available until the drag operation has begun. GDK will move - * the surface in accordance with the ongoing drag operation. - * The surface is owned by @drag and will be destroyed when - * the drag operation is over. + * during the drag operation. + * + * Note that the surface may not be available until the drag operation + * has begun. GDK will move the surface in accordance with the ongoing + * drag operation. The surface is owned by @drag and will be destroyed + * when the drag operation is over. * * Returns: (nullable) (transfer none): the drag surface, or %NULL */ @@ -701,13 +707,14 @@ gdk_drag_get_drag_surface (GdkDrag *drag) /** * gdk_drag_set_hotspot: - * @drag: a #GdkDrag + * @drag: a `GdkDrag` * @hot_x: x coordinate of the drag surface hotspot * @hot_y: y coordinate of the drag surface hotspot * * Sets the position of the drag surface that will be kept - * under the cursor hotspot. Initially, the hotspot is at the - * top left corner of the drag surface. + * under the cursor hotspot. + * + * Initially, the hotspot is at the top left corner of the drag surface. */ void gdk_drag_set_hotspot (GdkDrag *drag, @@ -722,17 +729,18 @@ gdk_drag_set_hotspot (GdkDrag *drag, /** * gdk_drag_drop_done: - * @drag: a #GdkDrag + * @drag: a `GdkDrag` * @success: whether the drag was ultimatively successful * - * Inform GDK if the drop ended successfully. Passing %FALSE - * for @success may trigger a drag cancellation animation. + * Informs GDK that the drop ended. * - * This function is called by the drag source, and should - * be the last call before dropping the reference to the - * @drag. + * Passing %FALSE for @success may trigger a drag cancellation + * animation. * - * The #GdkDrag will only take the first gdk_drag_drop_done() + * This function is called by the drag source, and should be the + * last call before dropping the reference to the @drag. + * + * The `GdkDrag` will only take the first [method@Gdk.Drag.drop_done] * call as effective, if this function is called multiple times, * all subsequent calls will be ignored. */ @@ -804,22 +812,22 @@ gdk_drag_get_cursor (GdkDrag *drag, if (drag_cursors[i].cursor == NULL) drag_cursors[i].cursor = gdk_cursor_new_from_name (drag_cursors[i].name, NULL); - + return drag_cursors[i].cursor; } /** * gdk_drag_action_is_unique: - * @action: a #GdkDragAction + * @action: a `GdkDragAction` * - * Checks if @action represents a single action or if it - * includes multiple flags that can be selected from. + * Checks if @action represents a single action or includes + * multiple actions. * * When @action is 0 - ie no action was given, %TRUE * is returned. * * Returns: %TRUE if exactly one action was given - **/ + */ gboolean gdk_drag_action_is_unique (GdkDragAction action) { diff --git a/gdk/gdkdrag.h b/gdk/gdkdrag.h index 070b0f812d..9133e0793b 100644 --- a/gdk/gdkdrag.h +++ b/gdk/gdkdrag.h @@ -45,7 +45,7 @@ G_BEGIN_DECLS * @GDK_DRAG_CANCEL_USER_CANCELLED: Drag cancelled by the user * @GDK_DRAG_CANCEL_ERROR: Unspecified error. * - * Used in #GdkDrag to the reason of a cancelled DND operation. + * Used in `GdkDrag` to the reason of a cancelled DND operation. */ typedef enum { GDK_DRAG_CANCEL_NO_TARGET, diff --git a/gdk/gdkdragsurface.c b/gdk/gdkdragsurface.c index 5e41b4bbe7..7000337551 100644 --- a/gdk/gdkdragsurface.c +++ b/gdk/gdkdragsurface.c @@ -26,14 +26,13 @@ /** * GdkDragSurface: * - * A #GdkDragSurface is an interface implemented by #GdkSurfaces used - * during a DND operation. + * A #GdkDragSurface is an interface for surfaces used during DND. */ /** * GdkDragSurfaceInterface: * - * The #GdkDragSurfaceInterface implementation is private to GDK. + * The `GdkDragSurfaceInterface` implementation is private to GDK. */ G_DEFINE_INTERFACE (GdkDragSurface, gdk_drag_surface, GDK_TYPE_SURFACE) @@ -54,7 +53,7 @@ gdk_drag_surface_default_init (GdkDragSurfaceInterface *iface) /** * gdk_drag_surface_present: - * @drag_surface: the #GdkDragSurface to show + * @drag_surface: the `GdkDragSurface` to show * @width: the unconstrained drag_surface width to layout * @height: the unconstrained drag_surface height to layout * diff --git a/gdk/gdkdrawcontext.c b/gdk/gdkdrawcontext.c index d0ea519e18..451b7499ab 100644 --- a/gdk/gdkdrawcontext.c +++ b/gdk/gdkdrawcontext.c @@ -27,24 +27,17 @@ #include "gdkprofilerprivate.h" /** - * SECTION:gdkdrawcontext - * @Title: GdkDrawContext - * @Short_description: Base class for draw contexts + * GdkDrawContext: * - * #GdkDrawContext is the base object used by contexts implementing different - * rendering methods, such as #GdkGLContext or #GdkVulkanContext. It provides - * shared functionality between those contexts. + * Base class for objects implementing different rendering methods. + * + * `GdkDrawContext` is the base object used by contexts implementing different + * rendering methods, such as [class@Gdk.CairoContext] or [class@Gdk.GLContext]. + * It provides shared functionality between those contexts. * * You will always interact with one of those subclasses. * - * A GdkDrawContext is always associated with a single toplevel surface. - */ - -/** - * GdkDrawContext: - * - * The GdkDrawContext struct contains only private fields and should not - * be accessed directly. + * A `GdkDrawContext` is always associated with a single toplevel surface. */ typedef struct _GdkDrawContextPrivate GdkDrawContextPrivate; @@ -148,7 +141,7 @@ gdk_draw_context_class_init (GdkDrawContextClass *klass) /** * GdkDrawContext:display: * - * The #GdkDisplay used to create the #GdkDrawContext. + * The `GdkDisplay` used to create the `GdkDrawContext`. */ pspecs[PROP_DISPLAY] = g_param_spec_object ("display", @@ -161,7 +154,7 @@ gdk_draw_context_class_init (GdkDrawContextClass *klass) /** * GdkDrawContext:surface: * - * The #GdkSurface the context is bound to. + * The `GdkSurface` the context is bound to. */ pspecs[PROP_SURFACE] = g_param_spec_object ("surface", @@ -186,16 +179,16 @@ gdk_draw_context_init (GdkDrawContext *self) /** * gdk_draw_context_is_in_frame: - * @context: a #GdkDrawContext + * @context: a `GdkDrawContext` * - * Returns %TRUE if @context is in the process of drawing to its surface - * after a call to gdk_draw_context_begin_frame() and not yet having called - * gdk_draw_context_end_frame(). - * In this situation, drawing commands may be effecting the contents of a - * @context's surface. + * Returns %TRUE if @context is in the process of drawing to its surface. * - * Returns: %TRUE if the context is between gdk_draw_context_begin_frame() - * and gdk_draw_context_end_frame() calls. + * This is the case between calls to [method@Gdk.DrawContext.begin_frame] + * and [method@Gdk.DrawContext.end_frame]. In this situation, drawing commands + * may be effecting the contents of the @context's surface. + * + * Returns: %TRUE if the context is between [method@Gdk.DrawContext.begin_frame] + * and [method@Gdk.DrawContext.end_frame] calls. */ gboolean gdk_draw_context_is_in_frame (GdkDrawContext *context) @@ -209,9 +202,9 @@ gdk_draw_context_is_in_frame (GdkDrawContext *context) /*< private > * gdk_draw_context_surface_resized: - * @context: a #GdkDrawContext + * @context: a `GdkDrawContext` * - * Called by the #GdkSurface the @context belongs to when the size of the surface + * Called by the surface the @context belongs to when the size of the surface * changes. */ void @@ -222,11 +215,11 @@ gdk_draw_context_surface_resized (GdkDrawContext *context) /** * gdk_draw_context_get_display: - * @context: a #GdkDrawContext + * @context: a `GdkDrawContext` * - * Retrieves the #GdkDisplay the @context is created for + * Retrieves the `GdkDisplay` the @context is created for * - * Returns: (nullable) (transfer none): a #GdkDisplay or %NULL + * Returns: (nullable) (transfer none): a `GdkDisplay` or %NULL */ GdkDisplay * gdk_draw_context_get_display (GdkDrawContext *context) @@ -240,9 +233,9 @@ gdk_draw_context_get_display (GdkDrawContext *context) /** * gdk_draw_context_get_surface: - * @context: a #GdkDrawContext + * @context: a `GdkDrawContext` * - * Retrieves the #GdkSurface used by the @context. + * Retrieves the surface that @context is bound to. * * Returns: (nullable) (transfer none): a #GdkSurface or %NULL */ @@ -258,7 +251,7 @@ gdk_draw_context_get_surface (GdkDrawContext *context) /** * gdk_draw_context_begin_frame: - * @context: the context used to draw the frame + * @context: the `GdkDrawContext` used to draw the frame * @region: minimum region that should be drawn * * Indicates that you are beginning the process of redrawing @region @@ -267,23 +260,24 @@ gdk_draw_context_get_surface (GdkDrawContext *context) * Calling this function begins a drawing operation using @context on the * surface that @context was created from. The actual requirements and * guarantees for the drawing operation vary for different implementations - * of drawing, so a #GdkCairoContext and a #GdkGLContext need to be treated - * differently. + * of drawing, so a [class@Gdk.CairoContext] and a [class@Gdk.GLContext] + * need to be treated differently. * - * A call to this function is a requirement for drawing and must be followed - * by a call to gdk_draw_context_end_frame(), which will complete the - * drawing operation and ensure the contents become visible on screen. + * A call to this function is a requirement for drawing and must be + * followed by a call to [method@Gdk.DrawContext.end_frame], which will + * complete the drawing operation and ensure the contents become visible + * on screen. * * Note that the @region passed to this function is the minimum region that * needs to be drawn and depending on implementation, windowing system and * hardware in use, it might be necessary to draw a larger region. Drawing - * implementation must use gdk_draw_context_get_frame_region() to query the - * region that must be drawn. + * implementation must use [method@Gdk.DrawContext.get_frame_region() to + * query the region that must be drawn. * * When using GTK, the widget system automatically places calls to * gdk_draw_context_begin_frame() and gdk_draw_context_end_frame() via the - * use of #GskRenderers, so application code does not need to call these - * functions explicitly. + * use of [class@Gsk.Renderer]s, so application code does not need to call + * these functions explicitly. */ void gdk_draw_context_begin_frame (GdkDrawContext *context, @@ -342,13 +336,14 @@ region_get_pixels (cairo_region_t *region) /** * gdk_draw_context_end_frame: - * @context: a #GdkDrawContext + * @context: a `GdkDrawContext` * - * Ends a drawing operation started with gdk_draw_context_begin_frame() - * and makes the drawing available on screen. See that function for more - * details about drawing. + * Ends a drawing operation started with gdk_draw_context_begin_frame(). * - * When using a #GdkGLContext, this function may call `glFlush()` + * This makes the drawing available on screen. + * See [method@Gdk.DrawContext.begin_frame] for more details about drawing. + * + * When using a [class@Gdk.GLContext], this function may call `glFlush()` * implicitly before returning; it is not recommended to call `glFlush()` * explicitly before calling this function. */ @@ -389,14 +384,14 @@ gdk_draw_context_end_frame (GdkDrawContext *context) * gdk_draw_context_get_frame_region: * @context: a #GdkDrawContext * - * Retrieves the region that is currently in the process of being repainted. + * Retrieves the region that is currently being repainted. * - * After a call to gdk_draw_context_begin_frame() this function will return - * a union of the region passed to that function and the area of the surface - * that the @context determined needs to be repainted. + * After a call to [method@Gdk.DrawContext.begin_frame] this function will + * return a union of the region passed to that function and the area of the + * surface that the @context determined needs to be repainted. * - * If @context is not in between calls to gdk_draw_context_begin_frame() and - * gdk_draw_context_end_frame(), %NULL will be returned. + * If @context is not in between calls to [method@Gdk.DrawContext.begin_frame] + * and [method@Gdk.DrawContext.end_frame], %NULL will be returned. * * Returns: (transfer none) (nullable): a Cairo region or %NULL if not drawing * a frame. diff --git a/gdk/gdkdrop.c b/gdk/gdkdrop.c index 289c30ee5d..143f1ce5d7 100644 --- a/gdk/gdkdrop.c +++ b/gdk/gdkdrop.c @@ -18,17 +18,14 @@ */ /** - * SECTION:gdkdrop - * @Title: Drag And Drop - * @Short_description: Functions for controlling drag and drop handling + * GdkDrop: * - * These functions provide a low-level interface for drag and drop. + * The `GdkDrop` object represents the target of an ongoing DND operation. * - * The `GdkDrop` object represents the target side of an ongoing DND operation. - * Possible drop sites get informed about the status of the ongoing drag operation - * with events of type %GDK_DRAG_ENTER, %GDK_DRAG_LEAVE, %GDK_DRAG_MOTION and - * %GDK_DROP_START. The `GdkDrop` object can be obtained from these - * [class@Gdk.Event] types using [method@Gdk.DndEvent.get_drop]. + * Possible drop sites get informed about the status of the ongoing drag + * operation with events of type %GDK_DRAG_ENTER, %GDK_DRAG_LEAVE, + * %GDK_DRAG_MOTION and %GDK_DROP_START. The `GdkDrop` object can be obtained + * from these [class@Gdk.Event] types using [method@Gdk.DNDEvent.get_drop]. * * The actual data transfer is initiated from the target side via an async * read, using one of the `GdkDrop` methods for this purpose: @@ -88,13 +85,6 @@ static GParamSpec *properties[N_PROPERTIES] = { NULL, }; G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GdkDrop, gdk_drop, G_TYPE_OBJECT) -/** - * GdkDrop: - * - * The GdkDrop struct contains only private fields and - * should not be accessed directly. - */ - static void gdk_drop_default_status (GdkDrop *self, GdkDragAction actions, @@ -345,7 +335,7 @@ gdk_drop_class_init (GdkDropClass *klass) /** * GdkDrop:device: * - * The #GdkDevice performing the drop + * The `GdkDevice` performing the drop */ properties[PROP_DEVICE] = g_param_spec_object ("device", @@ -360,7 +350,7 @@ gdk_drop_class_init (GdkDropClass *klass) /** * GdkDrop:display: * - * The #GdkDisplay that the drop belongs to. + * The `GdkDisplay` that the drop belongs to. */ properties[PROP_DISPLAY] = g_param_spec_object ("display", @@ -374,7 +364,7 @@ gdk_drop_class_init (GdkDropClass *klass) /** * GdkDrop:drag: * - * The #GdkDrag that initiated this drop + * The `GdkDrag` that initiated this drop */ properties[PROP_DRAG] = g_param_spec_object ("drag", @@ -404,7 +394,7 @@ gdk_drop_class_init (GdkDropClass *klass) /** * GdkDrop:surface: * - * The #GdkSurface the drop happens on + * The `GdkSurface` the drop happens on */ properties[PROP_SURFACE] = g_param_spec_object ("surface", @@ -426,12 +416,12 @@ gdk_drop_init (GdkDrop *self) /** * gdk_drop_get_display: - * @self: a #GdkDrop + * @self: a `GdkDrop` * - * Gets the #GdkDisplay that @self was created for. + * Gets the `GdkDisplay` that @self was created for. * - * Returns: (transfer none): a #GdkDisplay - **/ + * Returns: (transfer none): a `GdkDisplay` + */ GdkDisplay * gdk_drop_get_display (GdkDrop *self) { @@ -444,12 +434,12 @@ gdk_drop_get_display (GdkDrop *self) /** * gdk_drop_get_device: - * @self: a #GdkDrop + * @self: a `GdkDrop` * - * Returns the #GdkDevice performing the drop. + * Returns the `GdkDevice` performing the drop. * - * Returns: (transfer none): The #GdkDevice performing the drop. - **/ + * Returns: (transfer none): The `GdkDevice` performing the drop. + */ GdkDevice * gdk_drop_get_device (GdkDrop *self) { @@ -462,13 +452,13 @@ gdk_drop_get_device (GdkDrop *self) /** * gdk_drop_get_formats: - * @self: a #GdkDrop + * @self: a `GdkDrop` * - * Returns the #GdkContentFormats that the drop offers the data + * Returns the `GdkContentFormats` that the drop offers the data * to be read in. * - * Returns: (transfer none): The possible #GdkContentFormats - **/ + * Returns: (transfer none): The possible `GdkContentFormats` + */ GdkContentFormats * gdk_drop_get_formats (GdkDrop *self) { @@ -481,12 +471,12 @@ gdk_drop_get_formats (GdkDrop *self) /** * gdk_drop_get_surface: - * @self: a #GdkDrop + * @self: a `GdkDrop` * - * Returns the #GdkSurface performing the drop. + * Returns the `GdkSurface` performing the drop. * - * Returns: (transfer none): The #GdkSurface performing the drop. - **/ + * Returns: (transfer none): The `GdkSurface` performing the drop. + */ GdkSurface * gdk_drop_get_surface (GdkDrop *self) { @@ -499,23 +489,25 @@ gdk_drop_get_surface (GdkDrop *self) /** * gdk_drop_get_actions: - * @self: a #GdkDrop + * @self: a `GdkDrop` * - * Returns the possible actions for this #GdkDrop. If this value - * contains multiple actions - ie gdk_drag_action_is_unique() - * returns %FALSE for the result - gdk_drop_finish() must choose - * the action to use when accepting the drop. This will only - * happen if you passed %GDK_ACTION_ASK as one of the possible - * actions in gdk_drop_status(). %GDK_ACTION_ASK itself will not + * Returns the possible actions for this `GdkDrop`. + * + * If this value contains multiple actions - i.e. + * [func@Gdk.DragAction.is_unique] returns %FALSE for the result - + * [method@Gdk.Drop.finish] must choose the action to use when + * accepting the drop. This will only happen if you passed + * %GDK_ACTION_ASK as one of the possible actions in + * [method@Gdk.Drop.status]. %GDK_ACTION_ASK itself will not * be included in the actions returned by this function. * - * This value may change over the lifetime of the #GdkDrop both - * as a response to source side actions as well as to calls to - * gdk_drop_status() or gdk_drop_finish(). The source side will - * not change this value anymore once a drop has started. + * This value may change over the lifetime of the [class@Gdk.Drop] + * both as a response to source side actions as well as to calls to + * [method@Gdk.Drop.status] or [method@Gdk.Drop.finish]. The source + * side will not change this value anymore once a drop has started. * - * Returns: The possible #GdkDragActions - **/ + * Returns: The possible `GdkDragActions` + */ GdkDragAction gdk_drop_get_actions (GdkDrop *self) { @@ -546,15 +538,15 @@ gdk_drop_set_actions (GdkDrop *self, /** * gdk_drop_get_drag: - * @self: a #GdkDrop + * @self: a `GdkDrop` * - * If this is an in-app drag-and-drop operation, returns the #GdkDrag + * If this is an in-app drag-and-drop operation, returns the `GdkDrag` * that corresponds to this drop. * * If it is not, %NULL is returned. * - * Returns: (transfer none) (nullable): the corresponding #GdkDrag - **/ + * Returns: (transfer none) (nullable): the corresponding `GdkDrag` + */ GdkDrag * gdk_drop_get_drag (GdkDrop *self) { @@ -567,16 +559,16 @@ gdk_drop_get_drag (GdkDrop *self) /** * gdk_drop_status: - * @self: a #GdkDrop + * @self: a `GdkDrop` * @actions: Supported actions of the destination, or 0 to indicate * that a drop will not be accepted * @preferred: A unique action that's a member of @actions indicating the - * preferred action. + * preferred action * * Selects all actions that are potentially supported by the destination. * * When calling this function, do not restrict the passed in actions to - * the ones provided by gdk_drop_get_actions(). Those actions may + * the ones provided by [method@Gdk.Drop.get_actions]. Those actions may * change in the future, even depending on the actions you provide here. * * The @preferred action is a hint to the drag'n'drop mechanism about which @@ -606,15 +598,14 @@ gdk_drop_status (GdkDrop *self, /** * gdk_drop_finish: - * @self: a #GdkDrop - * @action: the action performed by the destination or 0 if the drop - * failed + * @self: a `GdkDrop` + * @action: the action performed by the destination or 0 if the drop failed * * Ends the drag operation after a drop. - * + * * The @action must be a single action selected from the actions - * available via gdk_drop_get_actions(). - **/ + * available via [method@Gdk.Drop.get_actions]. + */ void gdk_drop_finish (GdkDrop *self, GdkDragAction action) @@ -664,17 +655,17 @@ gdk_drop_read_internal (GdkDrop *self, /** * gdk_drop_read_async: - * @self: a #GdkDrop + * @self: a `GdkDrop` * @mime_types: (array zero-terminated=1) (element-type utf8): * pointer to an array of mime types - * @io_priority: the io priority for the read operation - * @cancellable: (allow-none): optional #GCancellable object, + * @io_priority: the I/O priority for the read operation + * @cancellable: (allow-none): optional `GCancellable` object, * %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when + * @callback: (scope async): a `GAsyncReadyCallback` to call when * the request is satisfied * @user_data: (closure): the data to pass to @callback * - * Asynchronously read the dropped data from a #GdkDrop + * Asynchronously read the dropped data from a `GdkDrop` * in a format that complies with one of the mime types. */ void @@ -701,14 +692,16 @@ gdk_drop_read_async (GdkDrop *self, /** * gdk_drop_read_finish: - * @self: a #GdkDrop - * @result: a #GAsyncResult + * @self: a `GdkDrop` + * @result: a `GAsyncResult` * @out_mime_type: (out) (type utf8): return location for the used mime type * @error: (allow-none): location to store error information on failure, or %NULL * - * Finishes an async drop read operation, see gdk_drop_read_async(). + * Finishes an async drop read operation. * - * Returns: (nullable) (transfer full): the #GInputStream, or %NULL + * See [method@Gdk.Drop.read_async]. + * + * Returns: (nullable) (transfer full): the `GInputStream`, or %NULL */ GInputStream * gdk_drop_read_finish (GdkDrop *self, @@ -851,23 +844,24 @@ gdk_drop_read_value_internal (GdkDrop *self, /** * gdk_drop_read_value_async: - * @self: a #GdkDrop - * @type: a #GType to read - * @io_priority: the [I/O priority][io-priority] - * of the request. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @self: a `GdkDrop` + * @type: a `GType` to read + * @io_priority: the I/O priority of the request. + * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function * - * Asynchronously request the drag operation's contents converted to the given - * @type. When the operation is finished @callback will be called. - * You can then call gdk_drop_read_value_finish() to get the resulting - * #GValue. + * Asynchronously request the drag operation's contents converted + * to the given @type. * - * For local drag'n'drop operations that are available in the given #GType, the - * value will be copied directly. Otherwise, GDK will try to use - * gdk_content_deserialize_async() to convert the data. - **/ + * When the operation is finished @callback will be called. You must + * then call [method@Gdk.Drop.read_value_finish] to get the resulting + * `GValue`. + * + * For local drag'n'drop operations that are available in the given + * `GType`, the value will be copied directly. Otherwise, GDK will + * try to use [func@Gdk.content_deserialize_async] to convert the data. + */ void gdk_drop_read_value_async (GdkDrop *self, GType type, @@ -891,16 +885,16 @@ gdk_drop_read_value_async (GdkDrop *self, /** * gdk_drop_read_value_finish: - * @self: a #GdkDrop - * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * @self: a `GdkDrop` + * @result: a `GAsyncResult` + * @error: a `GError` location to store the error occurring, or %NULL to ignore * - * Finishes an async drop read started with - * gdk_drop_read_value_async(). + * Finishes an async drop read. * - * Returns: (transfer none): a #GValue containing the result. - **/ + * See [method@Gdk.Drop.read_value_async]. + * + * Returns: (transfer none): a `GValue` containing the result. + */ const GValue * gdk_drop_read_value_finish (GdkDrop *self, GAsyncResult *result, @@ -1019,4 +1013,3 @@ gdk_drop_emit_drop_event (GdkDrop *self, gdk_drop_do_emit_event (event, dont_queue); } - diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c index c4548aa227..eb39c95976 100644 --- a/gdk/gdkevents.c +++ b/gdk/gdkevents.c @@ -41,8 +41,8 @@ /** * GdkEvent: (ref-func gdk_event_ref) (unref-func gdk_event_unref) * - * `GdkEvent` and its derived types are immutable data structures, - * created by GTK itself to represent windowing system events. + * `GdkEvent`s are immutable data structures, created by GDK to + * represent windowing system events. * * In GTK applications the events are handled automatically by toplevel * widgets and passed on to the event controllers of appropriate widgets, @@ -52,7 +52,7 @@ /** * GdkEventSequence: * - * GdkEventSequence is an opaque type representing a sequence + * `GdkEventSequence` is an opaque type representing a sequence * of related touch events. */ @@ -338,9 +338,9 @@ static GType gdk_event_types[GDK_EVENT_LAST]; /*< private > * GDK_EVENT_TYPE_SLOT: - * @ETYPE: a #GdkEventType + * @ETYPE: a `GdkEvent`Type * - * Associates a #GdkEvent type with the given #GdkEventType enumeration. + * Associates a `GdkEvent` type with the given `GdkEvent`Type enumeration. * * This macro can only be used with %GDK_DEFINE_EVENT_TYPE. */ @@ -350,10 +350,10 @@ static GType gdk_event_types[GDK_EVENT_LAST]; * GDK_DEFINE_EVENT_TYPE: * @TypeName: the type name, in camel case * @type_name: the type name, in snake case - * @type_info: the address of the #GdkEventTypeInfo for the event type + * @type_info: the address of the `GdkEvent`TypeInfo for the event type * @_C_: custom code to call after registering the event type * - * Registers a new #GdkEvent subclass with the given @TypeName and @type_info. + * Registers a new `GdkEvent` subclass with the given @TypeName and @type_info. * * Similarly to %G_DEFINE_TYPE_WITH_CODE, this macro will generate a `get_type()` * function that registers the event type. @@ -381,15 +381,15 @@ type_name ## _get_type (void) \ /*< private > * gdk_event_alloc: - * @event_type: the #GdkEventType to allocate + * @event_type: the `GdkEvent`Type to allocate * @surface: (nullable): the #GdkSurface of the event * @device: (nullable): the #GdkDevice of the event * @time_: the event serial * - * Allocates a #GdkEvent for the given @event_type, and sets its + * Allocates a `GdkEvent` for the given @event_type, and sets its * common fields with the given parameters. * - * Returns: (transfer full): the newly allocated #GdkEvent instance + * Returns: (transfer full): the newly allocated `GdkEvent` instance */ static gpointer gdk_event_alloc (GdkEventType event_type, @@ -820,7 +820,7 @@ _gdk_event_queue_flush (GdkDisplay *display) /** * gdk_event_ref: - * @event: a #GdkEvent + * @event: a `GdkEvent` * * Increase the ref count of @event. * @@ -838,10 +838,11 @@ gdk_event_ref (GdkEvent *event) /** * gdk_event_unref: - * @event: (transfer full): a #GdkEvent + * @event: (transfer full): a `GdkEvent` * - * Decrease the ref count of @event, and free it - * if the last reference is dropped. + * Decrease the ref count of @event. + * + * If the last reference is dropped, the structure is freed. */ void gdk_event_unref (GdkEvent *event) @@ -854,10 +855,11 @@ gdk_event_unref (GdkEvent *event) /** * gdk_event_get_pointer_emulated: - * @event: a #GdkEvent + * @event: a `GdkEvent` * - * Returns whether this event is an 'emulated' pointer event (typically - * from a touch event), as opposed to a real one. + * Returns whether this event is an 'emulated' pointer event. + * + * Emulated pointer events typically originate from a touch events. * * Returns: %TRUE if this event is emulated */ @@ -893,7 +895,7 @@ gdk_event_get_pointer_emulated (GdkEvent *event) /** * gdk_event_get_axis: - * @event: a #GdkEvent + * @event: a `GdkEvent` * @axis_use: the axis use to look for * @value: (out): location to store the value found * @@ -901,7 +903,7 @@ gdk_event_get_pointer_emulated (GdkEvent *event) * an event structure. * * Returns: %TRUE if the specified axis was found, otherwise %FALSE - **/ + */ gboolean gdk_event_get_axis (GdkEvent *event, GdkAxisUse axis_use, @@ -936,17 +938,18 @@ gdk_event_get_axis (GdkEvent *event, /** * gdk_event_triggers_context_menu: - * @event: a #GdkEvent, currently only button events are meaningful values + * @event: a `GdkEvent`, currently only button events are meaningful values * - * This function returns whether a #GdkEvent should trigger a - * context menu, according to platform conventions. The right - * mouse button always triggers context menus. + * Returns whether a `GdkEvent` should trigger a context menu, + * according to platform conventions. + * + * The right mouse button typically triggers context menus. * * This function should always be used instead of simply checking for * event->button == %GDK_BUTTON_SECONDARY. * * Returns: %TRUE if the event should trigger a context menu. - **/ + */ gboolean gdk_event_triggers_context_menu (GdkEvent *event) { @@ -997,12 +1000,14 @@ gdk_events_get_axis_distances (GdkEvent *event1, /** * gdk_events_get_distance: - * @event1: first #GdkEvent - * @event2: second #GdkEvent + * @event1: first `GdkEvent` + * @event2: second `GdkEvent` * @distance: (out): return location for the distance * - * If both events have X/Y information, the distance between both coordinates - * (as in a straight line going from @event1 to @event2) will be returned. + * Returns the distance between the event locations. + * + * This assumes that both events have X/Y information. + * If not, this function returns %FALSE. * * Returns: %TRUE if the distance could be calculated. **/ @@ -1018,17 +1023,21 @@ gdk_events_get_distance (GdkEvent *event1, /** * gdk_events_get_angle: - * @event1: first #GdkEvent - * @event2: second #GdkEvent + * @event1: first `GdkEvent` + * @event2: second `GdkEvent` * @angle: (out): return location for the relative angle between both events * - * If both events contain X/Y information, this function will return %TRUE - * and return in @angle the relative angle from @event1 to @event2. The rotation - * direction for positive angles is from the positive X axis towards the positive - * Y axis. + * Returns the relative angle from @event1 to @event2. + * + * The relative angle is the angle between the X axis and the line + * through both events' positions. The rotation direction for positive + * angles is from the positive X axis towards the positive Y axis. + * + * This assumes that both events have X/Y information. + * If not, this function returns %FALSE. * * Returns: %TRUE if the angle could be calculated. - **/ + */ gboolean gdk_events_get_angle (GdkEvent *event1, GdkEvent *event2, @@ -1060,16 +1069,18 @@ gdk_events_get_angle (GdkEvent *event1, /** * gdk_events_get_center: - * @event1: first #GdkEvent - * @event2: second #GdkEvent + * @event1: first `GdkEvent` + * @event2: second `GdkEvent` * @x: (out): return location for the X coordinate of the center * @y: (out): return location for the Y coordinate of the center * - * If both events contain X/Y information, the center of both coordinates - * will be returned in @x and @y. + * Returns the point halfway between the events' positions. + * + * This assumes that both events have X/Y information. + * If not, this function returns %FALSE. * * Returns: %TRUE if the center could be calculated. - **/ + */ gboolean gdk_events_get_center (GdkEvent *event1, GdkEvent *event2, @@ -1111,14 +1122,14 @@ G_DEFINE_BOXED_TYPE (GdkEventSequence, gdk_event_sequence, /** * gdk_event_get_axes: - * @event: a #GdkEvent + * @event: a `GdkEvent` * @axes: (transfer none) (out) (array length=n_axes): the array of values for all axes * @n_axes: (out): the length of array * * Extracts all axis values from an event. * * Returns: %TRUE on success, otherwise %FALSE - **/ + */ gboolean gdk_event_get_axes (GdkEvent *event, double **axes, @@ -1147,11 +1158,11 @@ gdk_event_dup_axes (GdkEvent *event) /** * gdk_event_get_event_type: - * @event: a #GdkEvent + * @event: a `GdkEvent` * * Retrieves the type of the event. * - * Returns: a #GdkEventType + * Returns: a `GdkEvent`Type */ GdkEventType gdk_event_get_event_type (GdkEvent *event) @@ -1163,9 +1174,9 @@ gdk_event_get_event_type (GdkEvent *event) /** * gdk_event_get_surface: - * @event: a #GdkEvent + * @event: a `GdkEvent` * - * Extracts the #GdkSurface associated with an event. + * Extracts the surface associated with an event. * * Returns: (transfer none): The #GdkSurface associated with the event */ @@ -1179,7 +1190,7 @@ gdk_event_get_surface (GdkEvent *event) /** * gdk_event_get_seat: - * @event: a #GdkEvent + * @event: a `GdkEvent` * * Returns the seat that originated the event. * @@ -1195,7 +1206,7 @@ gdk_event_get_seat (GdkEvent *event) /** * gdk_event_get_device: - * @event: a #GdkEvent. + * @event: a `GdkEvent`. * * Returns the device of an event. * @@ -1211,16 +1222,18 @@ gdk_event_get_device (GdkEvent *event) /** * gdk_event_get_device_tool: - * @event: a #GdkEvent + * @event: a `GdkEvent` * - * If the event was generated by a device that supports - * different tools (eg. a tablet), this function will - * return a #GdkDeviceTool representing the tool that - * caused the event. Otherwise, %NULL will be returned. + * Returns a `GdkDeviceTool` representing the tool that + * caused the event. * - * Note: the #GdkDeviceTools will be constant during + * If the was not generated by a device that supports + * different tools (such as a tablet), this function will + * return %NULL. + * + * Note: the `GdkDeviceTool` will be constant during * the application lifetime, if settings must be stored - * persistently across runs, see gdk_device_tool_get_serial() + * persistently across runs, see [method@Gdk.DeviceTool.get_serial]. * * Returns: (transfer none) (nullable): The current device tool, or %NULL **/ @@ -1234,13 +1247,15 @@ gdk_event_get_device_tool (GdkEvent *event) /** * gdk_event_get_time: - * @event: a #GdkEvent + * @event: a `GdkEvent` * - * Returns the time stamp from @event, if there is one; otherwise - * returns #GDK_CURRENT_TIME. + * Returns the timestamp of @event. * - * Returns: time stamp field from @event - **/ + * Not all events have timestamps. In that case, this function + * returns %GDK_CURRENT_TIME. + * + * Returns: timestamp field from @event + */ guint32 gdk_event_get_time (GdkEvent *event) { @@ -1251,9 +1266,9 @@ gdk_event_get_time (GdkEvent *event) /** * gdk_event_get_display: - * @event: a #GdkEvent + * @event: a `GdkEvent` * - * Retrieves the #GdkDisplay associated to the @event. + * Retrieves the display associated to the @event. * * Returns: (transfer none) (nullable): a #GdkDisplay */ @@ -1270,10 +1285,12 @@ gdk_event_get_display (GdkEvent *event) /** * gdk_event_get_event_sequence: - * @event: a #GdkEvent + * @event: a `GdkEvent` * - * If @event is a touch event, returns the #GdkEventSequence - * to which the event belongs. Otherwise, return %NULL. + * Retuns the event sequence to which the event belongs. + * + * Related touch events are connected in a sequence. Other + * events typically don't have event sequence information. * * Returns: (transfer none): the event sequence that the event belongs to */ @@ -1287,12 +1304,12 @@ gdk_event_get_event_sequence (GdkEvent *event) /** * gdk_event_get_modifier_state: - * @event: a #GdkEvent + * @event: a `GdkEvent` * * Returns the modifier state field of an event. * * Returns: the modifier state of @event - **/ + */ GdkModifierType gdk_event_get_modifier_state (GdkEvent *event) { @@ -1303,12 +1320,12 @@ gdk_event_get_modifier_state (GdkEvent *event) /** * gdk_event_get_position: - * @event: a #GdkEvent + * @event: a `GdkEvent` * @x: (out): location to put event surface x coordinate * @y: (out): location to put event surface y coordinate * * Extract the event surface relative x/y coordinates from an event. - **/ + */ gboolean gdk_event_get_position (GdkEvent *event, double *x, @@ -1324,7 +1341,7 @@ gdk_event_get_position (GdkEvent *event, /** * GdkButtonEvent: * - * An event related to a button on a pointer device/ + * An event related to a button on a pointer device. */ static void @@ -1484,8 +1501,8 @@ GDK_DEFINE_EVENT_TYPE (GdkKeyEvent, gdk_key_event, /*< private > * gdk_key_event_new: * @type: the event type, either %GDK_KEY_PRESS or %GDK_KEY_RELEASE - * @surface: the #GdkSurface of the event - * @device: the #GdkDevice related to the event + * @surface: the surface of the event + * @device: the device related to the event * @time: the event's timestamp * @keycode: the keycode of the event * @state: the modifiers state @@ -1493,9 +1510,9 @@ GDK_DEFINE_EVENT_TYPE (GdkKeyEvent, gdk_key_event, * @translated: the translated key data for the given @state * @no_lock: the translated key data without the given @state * - * Creates a new #GdkKeyEvent. + * Creates a new `GdkKeyEvent`. * - * Returns: (transfer full) (type GdkKeyEvent): the newly created #GdkEvent + * Returns: (transfer full) (type GdkKeyEvent): the newly created `GdkEvent` */ GdkEvent * gdk_key_event_new (GdkEventType type, @@ -1671,17 +1688,20 @@ gdk_key_event_is_modifier (GdkEvent *event) /** * gdk_key_event_matches: - * @event: (type GdkKeyEvent): a key #GdkEvent + * @event: (type GdkKeyEvent): a key `GdkEvent` * @keyval: the keyval to match * @modifiers: the modifiers to match * - * Matches a key event against a keyboard shortcut that is specified - * as a keyval and modifiers. Partial matches are possible where the - * combination matches if the currently active group is ignored. + * Matches a key event against a keyval and modifiers. + * + * This is typically used to trigger keyboard shortcuts such as Ctrl-C. + * + * Partial matches are possible where the combination matches + * if the currently active group is ignored. * * Note that we ignore Caps Lock for matching. * - * Returns: a GdkKeyMatch value describing whether @event matches + * Returns: a `GdkKeyMatch` value describing whether @event matches */ GdkKeyMatch gdk_key_event_matches (GdkEvent *event, @@ -1773,12 +1793,14 @@ gdk_key_event_matches (GdkEvent *event, /** * gdk_key_event_get_match: - * @event: (type GdkKeyEvent): a key #GdkEvent + * @event: (type GdkKeyEvent): a key `GdkEvent` * @keyval: (out): return location for a keyval * @modifiers: (out): return location for modifiers * - * Gets a keyval and modifier combination that will cause - * gdk_key_event_matches() to successfully match the given event. + * Gets a keyval and modifier combination that will match + * the event. + * + * See [method@Gdk.KeyEvent.matches]. * * Returns: %TRUE on success */ @@ -2153,7 +2175,7 @@ gdk_delete_event_new (GdkSurface *surface) /** * GdkFocusEvent: * - * An event related to a focus change. + * An event related to a keyboard focus change. */ static const GdkEventTypeInfo gdk_focus_event_info = { @@ -2345,11 +2367,13 @@ gdk_scroll_event_get_deltas (GdkEvent *event, * gdk_scroll_event_is_stop: * @event: (type GdkScrollEvent): a scroll event * - * Check whether a scroll event is a stop scroll event. Scroll sequences - * with smooth scroll information may provide a stop scroll event once the - * interaction with the device finishes, e.g. by lifting a finger. This - * stop scroll event is the signal that a widget may trigger kinetic - * scrolling based on the current velocity. + * Check whether a scroll event is a stop scroll event. + * + * Scroll sequences with smooth scroll information may provide + * a stop scroll event once the interaction with the device finishes, + * e.g. by lifting a finger. This stop scroll event is the signal + * that a widget may trigger kinetic scrolling based on the current + * velocity. * * Stop scroll events always have a delta of 0/0. * @@ -2373,7 +2397,12 @@ gdk_scroll_event_is_stop (GdkEvent *event) /** * GdkTouchpadEvent: * - * An event related to a touchpad device. + * An event related to a gesture on a touchpad device. + * + * Unlike touchscreens, where the windowing system sends basic + * sequences of begin, update, end events, and leaves gesture + * recognition to the clients, touchpad gestures are typically + * processed by the system, resulting in these events. */ static GdkModifierType @@ -2469,7 +2498,7 @@ gdk_touchpad_event_new_pinch (GdkSurface *surface, /** * gdk_touchpad_event_get_gesture_phase: - * @event: (type GdkTouchpadEvent): a touchpad #GdkEvent + * @event: (type GdkTouchpadEvent): a touchpad event * * Extracts the touchpad gesture phase from a touchpad event. * @@ -2514,7 +2543,7 @@ gdk_touchpad_event_get_n_fingers (GdkEvent *event) * @dy: (out): return location for y * * Extracts delta information from a touchpad event. - **/ + */ void gdk_touchpad_event_get_deltas (GdkEvent *event, double *dx, @@ -2680,7 +2709,7 @@ gdk_pad_event_new_group_mode (GdkSurface *surface, * a pad event. * * Returns: the button of @event - **/ + */ guint gdk_pad_event_get_button (GdkEvent *event) { @@ -2700,7 +2729,7 @@ gdk_pad_event_get_button (GdkEvent *event) * @value: (out): Return location for the axis value * * Extracts the information from a pad strip or ring event. - **/ + */ void gdk_pad_event_get_axis_value (GdkEvent *event, guint *index, @@ -2723,7 +2752,7 @@ gdk_pad_event_get_axis_value (GdkEvent *event, * @mode: (out): return location for the mode * * Extracts group and mode information from a pad event. - **/ + */ void gdk_pad_event_get_group_mode (GdkEvent *event, guint *group, @@ -2850,16 +2879,17 @@ gdk_motion_event_new (GdkSurface *surface, /** * gdk_event_get_history: - * @event: a motion or scroll #GdkEvent + * @event: a motion or scroll event * @out_n_coords: (out): Return location for the length of the returned array * - * Retrieves the history of the @event, as a list of time and coordinates. + * Retrieves the history of the device that @event is for, as a list of + * time and coordinates. * - * The history includes events that are not delivered to the application - * because they occurred in the same frame as @event. + * The history includes positions that are not delivered as separate events + * to the application because they occurred in the same frame as @event. * * Note that only motion and scroll events record history, and motion - * events only if one of the mouse buttons is down. + * events do it only if one of the mouse buttons is down. * * Returns: (transfer container) (array length=out_n_coords) (nullable): an * array of time and coordinates @@ -3053,7 +3083,7 @@ gdk_dnd_event_new (GdkEventType type, * gdk_dnd_event_get_drop: * @event: (type GdkDNDEvent): a DND event * - * Gets the #GdkDrop from a DND event. + * Gets the `GdkDrop` object from a DND event. * * Returns: (transfer none) (nullable): the drop **/ diff --git a/gdk/gdkevents.h b/gdk/gdkevents.h index 2b87754eec..e038501cd2 100644 --- a/gdk/gdkevents.h +++ b/gdk/gdkevents.h @@ -47,10 +47,9 @@ G_BEGIN_DECLS #define GDK_IS_EVENT_TYPE(event, type) (gdk_event_get_event_type ((event)) == (type)) /** - * GDK_PRIORITY_EVENTS: + * GDK_PRIORITY_EVENTS: (value: 0) * - * This is the priority that events from the X server are given in the - * [GLib Main Loop][glib-The-Main-Event-Loop]. + * This is the priority that events from the X server are given in the main loop. */ #define GDK_PRIORITY_EVENTS (G_PRIORITY_DEFAULT) @@ -58,8 +57,7 @@ G_BEGIN_DECLS * GDK_PRIORITY_REDRAW: (value 120) * * This is the priority that the idle handler processing surface updates - * is given in the - * [GLib Main Loop][glib-The-Main-Event-Loop]. + * is given in the main loop. */ #define GDK_PRIORITY_REDRAW (G_PRIORITY_HIGH_IDLE + 20) @@ -216,9 +214,11 @@ typedef enum * @GDK_TOUCHPAD_GESTURE_PHASE_CANCEL: The gesture was cancelled, all * changes should be undone. * - * Specifies the current state of a touchpad gesture. All gestures are - * guaranteed to begin with an event with phase %GDK_TOUCHPAD_GESTURE_PHASE_BEGIN, - * followed by 0 or several events with phase %GDK_TOUCHPAD_GESTURE_PHASE_UPDATE. + * Specifies the current state of a touchpad gesture. + * + * All gestures are guaranteed to begin with an event with phase + * %GDK_TOUCHPAD_GESTURE_PHASE_BEGIN, followed by 0 or several events + * with phase %GDK_TOUCHPAD_GESTURE_PHASE_UPDATE. * * A finished gesture may have 2 possible outcomes, an event with phase * %GDK_TOUCHPAD_GESTURE_PHASE_END will be emitted when the gesture is @@ -494,8 +494,9 @@ gboolean gdk_events_get_center (GdkEvent *event1, * (specifically, the currently active group) is ignored * @GDK_KEY_MATCH_EXACT: The key event matches * - * The possible return values from gdk_key_event_matches() - * describe how well an event matches a given keyval and modifiers. + * Describes how well an event matches a given keyval and modifiers. + * + * `GdkKeyMatch` values are returned by [method@Gdk.KeyEvent.matches]. */ typedef enum { GDK_KEY_MATCH_NONE, diff --git a/gdk/gdkframeclock.c b/gdk/gdkframeclock.c index 5e4492744c..92c9b6fcfc 100644 --- a/gdk/gdkframeclock.c +++ b/gdk/gdkframeclock.c @@ -28,52 +28,43 @@ #include "gdkinternals.h" /** - * SECTION:gdkframeclock - * @Title: GdkFrameClock - * @Short_description: Synchronizes painting to a surface + * GdkFrameClock: * - * 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 - * total number of frames). The frame clock can also automatically - * stop painting when it knows the frames will not be visible, or - * scale back animation framerates. + * A `GdkFrameClock` tells the application when to update and repaint + * a surface. * - * #GdkFrameClock is designed to be compatible with an OpenGL-based - * implementation or with mozRequestAnimationFrame in Firefox, - * for example. + * 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 total number of frames). + * + * The frame clock can also automatically stop painting when it knows the frames + * will not be visible, or scale back animation framerates. + * + * `GdkFrameClock` is designed to be compatible with an OpenGL-based implementation + * or with mozRequestAnimationFrame in Firefox, for example. * * A frame clock is idle until someone requests a frame with - * gdk_frame_clock_request_phase(). At some later point that makes - * sense for the synchronization being implemented, the clock will - * process a frame and emit signals for each phase that has been - * requested. (See the signals of the #GdkFrameClock class for - * documentation of the phases. %GDK_FRAME_CLOCK_PHASE_UPDATE and the - * #GdkFrameClock::update signal are most interesting for application - * writers, and are used to update the animations, using the frame time - * given by gdk_frame_clock_get_frame_time(). + * [method@Gdk.FrameClock.request_phase]. At some later point that makes sense + * for the synchronization being implemented, the clock will process a frame and + * emit signals for each phase that has been requested. (See the signals of the + * `GdkFrameClock` class for documentation of the phases. + * %GDK_FRAME_CLOCK_PHASE_UPDATE and the [signal@GdkFrameClock::update] signal + * are most interesting for application writers, and are used to update the + * animations, using the frame time given by [metohd@Gdk.FrameClock.get_frame_time]. * * The frame time is reported in microseconds and generally in the same * timescale as g_get_monotonic_time(), however, it is not the same * as g_get_monotonic_time(). The frame time does not advance during * the time a frame is being painted, and outside of a frame, an attempt - * is made so that all calls to gdk_frame_clock_get_frame_time() that + * is made so that all calls to [method@Gdk.FrameClock.get_frame_time] that * are called at a “similar” time get the same value. This means that * if different animations are timed by looking at the difference in - * time between an initial value from gdk_frame_clock_get_frame_time() - * and the value inside the #GdkFrameClock::update signal of the clock, + * time between an initial value from [method@Gdk.FrameClock.get_frame_time] + * and the value inside the [signal@GdkFrameClock::update] signal of the clock, * they will stay exactly synchronized. */ -/** - * GdkFrameClock: - * - * The GdkFrameClock struct contains only private fields and - * should not be accessed directly. - */ - enum { FLUSH_EVENTS, BEFORE_PAINT, @@ -138,9 +129,10 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass) * GdkFrameClock::flush-events: * @clock: the frame clock emitting the signal * - * This signal is used to flush pending motion events that - * are being batched up and compressed together. Applications - * should not handle this signal. + * Used to flush pending motion events that are being batched up and + * compressed together. + * + * Applications should not handle this signal. */ signals[FLUSH_EVENTS] = g_signal_new (g_intern_static_string ("flush-events"), @@ -154,8 +146,9 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass) * GdkFrameClock::before-paint: * @clock: the frame clock emitting the signal * - * This signal begins processing of the frame. Applications - * should generally not handle this signal. + * Begins processing of the frame. + * + * Applications should generally not handle this signal. */ signals[BEFORE_PAINT] = g_signal_new (g_intern_static_string ("before-paint"), @@ -169,12 +162,12 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass) * GdkFrameClock::update: * @clock: the frame clock emitting the signal * - * This signal is emitted as the first step of toolkit and - * application processing of the frame. Animations should - * be updated using gdk_frame_clock_get_frame_time(). - * Applications can connect directly to this signal, or - * use gtk_widget_add_tick_callback() as a more convenient - * interface. + * Emitted as the first step of toolkit and application processing + * of the frame. + * + * Animations should be updated using [method@Gdk.FrameClock.get_frame_time]. + * Applications can connect directly to this signal, or use + * [method@Gtk.Widget.add_tick_callback] as a more convenient interface. */ signals[UPDATE] = g_signal_new (g_intern_static_string ("update"), @@ -188,10 +181,11 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass) * GdkFrameClock::layout: * @clock: the frame clock emitting the signal * - * This signal is emitted as the second step of toolkit and - * application processing of the frame. Any work to update - * sizes and positions of application elements should be - * performed. GTK normally handles this internally. + * Emitted as the second step of toolkit and application processing + * of the frame. + * + * Any work to update sizes and positions of application elements + * should be performed. GTK normally handles this internally. */ signals[LAYOUT] = g_signal_new (g_intern_static_string ("layout"), @@ -205,11 +199,12 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass) * GdkFrameClock::paint: * @clock: the frame clock emitting the signal * - * This signal is emitted as the third step of toolkit and - * application processing of the frame. The frame is - * repainted. GDK normally handles this internally and - * emits #GdkSurface::render which are turned into - * #GtkWidget::snapshot signals by GTK. + * Emitted as the third step of toolkit and application processing + * of the frame. + * + * The frame is repainted. GDK normally handles this internally and + * emits [signal@Gdk.Surface::render] signals which are turned into + * [signal@Gtk.Widget::snapshot] signals by GTK. */ signals[PAINT] = g_signal_new (g_intern_static_string ("paint"), @@ -223,8 +218,9 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass) * GdkFrameClock::after-paint: * @clock: the frame clock emitting the signal * - * This signal ends processing of the frame. Applications - * should generally not handle this signal. + * This signal ends processing of the frame. + * + * Applications should generally not handle this signal. */ signals[AFTER_PAINT] = g_signal_new (g_intern_static_string ("after-paint"), @@ -238,8 +234,9 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass) * GdkFrameClock::resume-events: * @clock: the frame clock emitting the signal * - * This signal is emitted after processing of the frame is - * finished, and is handled internally by GTK to resume normal + * Emitted after processing of the frame is finished. + * + * This signal is handled internally by GTK to resume normal * event processing. Applications should not handle this signal. */ signals[RESUME_EVENTS] = @@ -267,10 +264,11 @@ gdk_frame_clock_init (GdkFrameClock *clock) /** * gdk_frame_clock_get_frame_time: - * @frame_clock: a #GdkFrameClock + * @frame_clock: a `GdkFrameClock` * - * Gets the time that should currently be used for animations. Inside - * the processing of a frame, it’s the time used to compute the + * Gets the time that should currently be used for animations. + * + * Inside the processing of a frame, it’s the time used to compute the * animation position of everything in a frame. Outside of a frame, it's * the time of the conceptual “previous frame,” which may be either * the actual previous frame time, or if that’s too old, an updated @@ -289,18 +287,19 @@ gdk_frame_clock_get_frame_time (GdkFrameClock *frame_clock) /** * gdk_frame_clock_request_phase: - * @frame_clock: a #GdkFrameClock + * @frame_clock: a `GdkFrameClock` * @phase: the phase that is requested * - * Asks the frame clock to run a particular phase. The signal - * corresponding the requested phase will be emitted the next + * Asks the frame clock to run a particular phase. + * + * The signal corresponding the requested phase will be emitted the next * time the frame clock processes. Multiple calls to * gdk_frame_clock_request_phase() will be combined together * and only one frame processed. If you are displaying animated * content and want to continually request the * %GDK_FRAME_CLOCK_PHASE_UPDATE phase for a period of time, - * you should use gdk_frame_clock_begin_updating() instead, since - * this allows GTK to adjust system parameters to get maximally + * you should use [method@Gdk.FrameClock.begin_updating] instead, + * since this allows GTK to adjust system parameters to get maximally * smooth animations. */ void @@ -314,14 +313,15 @@ gdk_frame_clock_request_phase (GdkFrameClock *frame_clock, /** * gdk_frame_clock_begin_updating: - * @frame_clock: a #GdkFrameClock + * @frame_clock: a `GdkFrameClock` * - * Starts updates for an animation. Until a matching call to - * gdk_frame_clock_end_updating() is made, the frame clock will continually - * request a new frame with the %GDK_FRAME_CLOCK_PHASE_UPDATE phase. - * This function may be called multiple times and frames will be - * requested until gdk_frame_clock_end_updating() is called the same - * number of times. + * Starts updates for an animation. + * + * Until a matching call to [method@Gdk.FrameClock.end_updating] is made, + * the frame clock will continually request a new frame with the + * %GDK_FRAME_CLOCK_PHASE_UPDATE phase. This function may be called multiple + * times and frames will be requested until gdk_frame_clock_end_updating() + * is called the same number of times. */ void gdk_frame_clock_begin_updating (GdkFrameClock *frame_clock) @@ -333,10 +333,11 @@ gdk_frame_clock_begin_updating (GdkFrameClock *frame_clock) /** * gdk_frame_clock_end_updating: - * @frame_clock: a #GdkFrameClock + * @frame_clock: a `GdkFrameClock` * - * Stops updates for an animation. See the documentation for - * gdk_frame_clock_begin_updating(). + * Stops updates for an animation. + * + * See the documentation for [method@Gdk.FrameClock.begin_updating]. */ void gdk_frame_clock_end_updating (GdkFrameClock *frame_clock) @@ -354,7 +355,6 @@ _gdk_frame_clock_freeze (GdkFrameClock *clock) GDK_FRAME_CLOCK_GET_CLASS (clock)->freeze (clock); } - static void _gdk_frame_clock_thaw (GdkFrameClock *clock) { @@ -377,7 +377,6 @@ _gdk_frame_clock_inhibit_freeze (GdkFrameClock *clock) _gdk_frame_clock_thaw (clock); } - void _gdk_frame_clock_uninhibit_freeze (GdkFrameClock *clock) { @@ -394,13 +393,13 @@ _gdk_frame_clock_uninhibit_freeze (GdkFrameClock *clock) /** * gdk_frame_clock_get_frame_counter: - * @frame_clock: a #GdkFrameClock + * @frame_clock: a `GdkFrameClock` * - * A #GdkFrameClock maintains a 64-bit counter that increments for + * `GdkFrameClock` maintains a 64-bit counter that increments for * each frame drawn. * * Returns: inside frame processing, the value of the frame counter - * for the current frame. Outside of frame processing, the frame + * for the current frame. Outside of frame processing, the frame * counter for the last frame. */ gint64 @@ -417,18 +416,20 @@ gdk_frame_clock_get_frame_counter (GdkFrameClock *frame_clock) /** * gdk_frame_clock_get_history_start: - * @frame_clock: a #GdkFrameClock + * @frame_clock: a `GdkFrameClock` * - * #GdkFrameClock internally keeps a history of #GdkFrameTimings + * Returns the frame counter for the oldest frame available in history. + * + * `GdkFrameClock` internally keeps a history of `GdkFrameTimings` * objects for recent frames that can be retrieved with - * gdk_frame_clock_get_timings(). The set of stored frames + * [method@Gdk.FrameClock.get_timings]. The set of stored frames * is the set from the counter values given by - * gdk_frame_clock_get_history_start() and - * gdk_frame_clock_get_frame_counter(), inclusive. + * [method@Gdk.FrameClock.get_history_start] and + * [method@Gdk.FrameClock.get_frame_counter], inclusive. * * Returns: the frame counter value for the oldest frame * that is available in the internal frame history of the - * #GdkFrameClock. + * `GdkFrameClock` */ gint64 gdk_frame_clock_get_history_start (GdkFrameClock *frame_clock) @@ -472,17 +473,19 @@ _gdk_frame_clock_begin_frame (GdkFrameClock *frame_clock) /** * gdk_frame_clock_get_timings: - * @frame_clock: a #GdkFrameClock + * @frame_clock: a `GdkFrameClock` * @frame_counter: the frame counter value identifying the frame to - * be received. + * be received * - * Retrieves a #GdkFrameTimings object holding timing information - * for the current frame or a recent frame. The #GdkFrameTimings - * object may not yet be complete: see gdk_frame_timings_get_complete(). + * Retrieves a `GdkFrameTimings` object holding timing information + * for the current frame or a recent frame. * - * Returns: (nullable) (transfer none): the #GdkFrameTimings object for - * the specified frame, or %NULL if it is not available. See - * gdk_frame_clock_get_history_start(). + * The `GdkFrameTimings` object may not yet be complete: see + * [method@Gdk.FrameTimings.get_complete]. + * + * Returns: (nullable) (transfer none): the `GdkFrameTimings` object + * for the specified frame, or %NULL if it is not available. See + * [method@Gdk.FrameClock.get_history_start]. */ GdkFrameTimings * gdk_frame_clock_get_timings (GdkFrameClock *frame_clock, @@ -508,14 +511,14 @@ gdk_frame_clock_get_timings (GdkFrameClock *frame_clock, /** * gdk_frame_clock_get_current_timings: - * @frame_clock: a #GdkFrameClock + * @frame_clock: a `GdkFrameClock` * * Gets the frame timings for the current frame. * - * Returns: (nullable) (transfer none): the #GdkFrameTimings for the - * frame currently being processed, or even no frame is being - * processed, for the previous frame. Before any frames have been - * processed, returns %NULL. + * Returns: (nullable) (transfer none): the `GdkFrameTimings` for the + * frame currently being processed, or even no frame is being + * processed, for the previous frame. Before any frames have been + * processed, returns %NULL. */ GdkFrameTimings * gdk_frame_clock_get_current_timings (GdkFrameClock *frame_clock) @@ -584,14 +587,16 @@ _gdk_frame_clock_debug_print_timings (GdkFrameClock *clock, /** * gdk_frame_clock_get_refresh_info: - * @frame_clock: a #GdkFrameClock + * @frame_clock: a `GdkFrameClock` * @base_time: base time for determining a presentaton time * @refresh_interval_return: (out) (optional): a location to store the - * determined refresh interval, or %NULL. A default refresh interval of - * 1/60th of a second will be stored if no history is present. + * determined refresh interval, or %NULL. A default refresh interval of + * 1/60th of a second will be stored if no history is present. * @presentation_time_return: (out): a location to store the next - * candidate presentation time after the given base time. - * 0 will be will be stored if no history is present. + * candidate presentation time after the given base time. + * 0 will be will be stored if no history is present. + * + * Predicts a presentation time, based on history. * * Using the frame history stored in the frame clock, finds the last * known presentation time and refresh interval, and assuming that @@ -754,12 +759,12 @@ guess_refresh_interval (GdkFrameClock *frame_clock) /** * gdk_frame_clock_get_fps: - * @frame_clock: a #GdkFrameClock + * @frame_clock: a `GdkFrameClock` * * Calculates the current frames-per-second, based on the * frame timings of @frame_clock. * - * Returns: the current fps, as a double + * Returns: the current fps, as a `double` */ double gdk_frame_clock_get_fps (GdkFrameClock *frame_clock) diff --git a/gdk/gdkframeclock.h b/gdk/gdkframeclock.h index f50512c150..0fd6bca1f4 100644 --- a/gdk/gdkframeclock.h +++ b/gdk/gdkframeclock.h @@ -55,10 +55,10 @@ typedef struct _GdkFrameClockClass GdkFrameClockClass; * @GDK_FRAME_CLOCK_PHASE_RESUME_EVENTS: corresponds to GdkFrameClock::resume-events. Should not be handled by applications. * @GDK_FRAME_CLOCK_PHASE_AFTER_PAINT: corresponds to GdkFrameClock::after-paint. Should not be handled by applications. * - * #GdkFrameClockPhase is used to represent the different paint clock - * phases that can be requested. The elements of the enumeration - * correspond to the signals of #GdkFrameClock. - **/ + * Used to represent the different paint clock phases that can be requested. + * + * The elements of the enumeration correspond to the signals of `GdkFrameClock`. + */ typedef enum { GDK_FRAME_CLOCK_PHASE_NONE = 0, GDK_FRAME_CLOCK_PHASE_FLUSH_EVENTS = 1 << 0, diff --git a/gdk/gdkframetimings.c b/gdk/gdkframetimings.c index 797638d844..22d9623746 100644 --- a/gdk/gdkframetimings.c +++ b/gdk/gdkframetimings.c @@ -21,24 +21,17 @@ #include "gdkframeclockprivate.h" -/** - * SECTION:gdkframetimings - * @Short_description: Object holding timing information for a single frame - * @Title: Frame timings - * - * A #GdkFrameTimings object holds timing information for a single frame - * of the application’s displays. To retrieve #GdkFrameTimings objects, - * use gdk_frame_clock_get_timings() or gdk_frame_clock_get_current_timings(). - * The information in #GdkFrameTimings is useful for precise synchronization - * of video with the event or audio streams, and for measuring - * quality metrics for the application’s display, such as latency and jitter. - */ - /** * GdkFrameTimings: * - * The GdkFrameTimings struct contains only private fields and - * should not be accessed directly. + * A `GdkFrameTimings` object holds timing information for a single frame + * of the application’s displays. + * + * To retrieve `GdkFrameTimings` objects, use [method@Gdk.FrameClock.get_timings] + * or [method@Gdk.FrameClock.get_current_timings]. The information in + * `GdkFrameTimings` is useful for precise synchronization of video with + * the event or audio streams, and for measuring quality metrics for the + * application’s display, such as latency and jitter. */ G_DEFINE_BOXED_TYPE (GdkFrameTimings, gdk_frame_timings, @@ -74,7 +67,7 @@ _gdk_frame_timings_steal (GdkFrameTimings *timings, /** * gdk_frame_timings_ref: - * @timings: a #GdkFrameTimings + * @timings: a `GdkFrameTimings` * * Increases the reference count of @timings. * @@ -92,10 +85,11 @@ gdk_frame_timings_ref (GdkFrameTimings *timings) /** * gdk_frame_timings_unref: - * @timings: a #GdkFrameTimings + * @timings: a `GdkFrameTimings` * - * Decreases the reference count of @timings. If @timings - * is no longer referenced, it will be freed. + * Decreases the reference count of @timings. + * + * If @timings is no longer referenced, it will be freed. */ void gdk_frame_timings_unref (GdkFrameTimings *timings) @@ -112,9 +106,9 @@ gdk_frame_timings_unref (GdkFrameTimings *timings) /** * gdk_frame_timings_get_frame_counter: - * @timings: a #GdkFrameTimings + * @timings: a `GdkFrameTimings` * - * Gets the frame counter value of the #GdkFrameClock when this + * Gets the frame counter value of the `GdkFrameClock` when * this frame was drawn. * * Returns: the frame counter value for this frame @@ -127,20 +121,24 @@ gdk_frame_timings_get_frame_counter (GdkFrameTimings *timings) /** * gdk_frame_timings_get_complete: - * @timings: a #GdkFrameTimings + * @timings: a `GdkFrameTimings` * - * The timing information in a #GdkFrameTimings is filled in + * Returns whether @timings are complete. + * + * The timing information in a `GdkFrameTimings` is filled in * incrementally as the frame as drawn and passed off to the * window system for processing and display to the user. The - * accessor functions for #GdkFrameTimings can return 0 to + * accessor functions for `GdkFrameTimings` can return 0 to * indicate an unavailable value for two reasons: either because * the information is not yet available, or because it isn't - * available at all. Once gdk_frame_timings_get_complete() returns - * %TRUE for a frame, you can be certain that no further values - * will become available and be stored in the #GdkFrameTimings. + * available at all. + * + * Once this function returns %TRUE for a frame, you can be + * certain that no further values will become available and be + * stored in the `GdkFrameTimings`. * * Returns: %TRUE if all information that will be available - * for the frame has been filled in. + * for the frame has been filled in. */ gboolean gdk_frame_timings_get_complete (GdkFrameTimings *timings) @@ -152,11 +150,12 @@ gdk_frame_timings_get_complete (GdkFrameTimings *timings) /** * gdk_frame_timings_get_frame_time: - * @timings: A #GdkFrameTimings + * @timings: A `GdkFrameTimings` * - * Returns the frame time for the frame. This is the time value - * that is typically used to time animations for the frame. See - * gdk_frame_clock_get_frame_time(). + * Returns the frame time for the frame. + * + * This is the time value that is typically used to time + * animations for the frame. See [method@Gdk.FrameClock.get_frame_time]. * * Returns: the frame time for the frame, in the timescale * of g_get_monotonic_time() @@ -171,14 +170,15 @@ gdk_frame_timings_get_frame_time (GdkFrameTimings *timings) /** * gdk_frame_timings_get_presentation_time: - * @timings: a #GdkFrameTimings + * @timings: a `GdkFrameTimings` * - * Reurns the presentation time. This is the time at which the frame - * became visible to the user. + * Reurns the presentation time. + * + * This is the time at which the frame became visible to the user. * * Returns: the time the frame was displayed to the user, in the - * timescale of g_get_monotonic_time(), or 0 if no presentation - * time is available. See gdk_frame_timings_get_complete() + * timescale of g_get_monotonic_time(), or 0 if no presentation + * time is available. See [method@Gdk.FrameTimings.get_complete] */ gint64 gdk_frame_timings_get_presentation_time (GdkFrameTimings *timings) @@ -190,21 +190,24 @@ gdk_frame_timings_get_presentation_time (GdkFrameTimings *timings) /** * gdk_frame_timings_get_predicted_presentation_time: - * @timings: a #GdkFrameTimings + * @timings: a `GdkFrameTimings` * - * Gets the predicted time at which this frame will be displayed. Although - * no predicted time may be available, if one is available, it will - * be available while the frame is being generated, in contrast to - * gdk_frame_timings_get_presentation_time(), which is only available - * after the frame has been presented. In general, if you are simply - * animating, you should use gdk_frame_clock_get_frame_time() rather - * than this function, but this function is useful for applications - * that want exact control over latency. For example, a movie player - * may want this information for Audio/Video synchronization. + * Gets the predicted time at which this frame will be displayed. + * + * Although no predicted time may be available, if one is available, + * it will be available while the frame is being generated, in contrast + * to [method@Gdk.FrameTimings.get_presentation_time], which is only + * available after the frame has been presented. + * + * In general, if you are simply animating, you should use + * [method@Gdk.FrameClock.get_frame_time] rather than this function, + * but this function is useful for applications that want exact control + * over latency. For example, a movie player may want this information + * for Audio/Video synchronization. * * Returns: The predicted time at which the frame will be presented, - * in the timescale of g_get_monotonic_time(), or 0 if no predicted - * presentation time is available. + * in the timescale of g_get_monotonic_time(), or 0 if no predicted + * presentation time is available. */ gint64 gdk_frame_timings_get_predicted_presentation_time (GdkFrameTimings *timings) @@ -216,15 +219,17 @@ gdk_frame_timings_get_predicted_presentation_time (GdkFrameTimings *timings) /** * gdk_frame_timings_get_refresh_interval: - * @timings: a #GdkFrameTimings + * @timings: a `GdkFrameTimings` * * Gets the natural interval between presentation times for - * the display that this frame was displayed on. Frame presentation - * usually happens during the “vertical blanking interval”. + * the display that this frame was displayed on. + * + * Frame presentation usually happens during the “vertical + * blanking interval”. * * Returns: the refresh interval of the display, in microseconds, - * or 0 if the refresh interval is not available. - * See gdk_frame_timings_get_complete(). + * or 0 if the refresh interval is not available. + * See [method@Gdk.FrameTimings.get_complete]. */ gint64 gdk_frame_timings_get_refresh_interval (GdkFrameTimings *timings) diff --git a/gdk/gdkglcontext.c b/gdk/gdkglcontext.c index 3bc52b74fb..adcd92eaf1 100644 --- a/gdk/gdkglcontext.c +++ b/gdk/gdkglcontext.c @@ -19,68 +19,57 @@ */ /** - * SECTION:gdkglcontext - * @Title: GdkGLContext - * @Short_description: OpenGL draw context + * GdkGLContext: * - * #GdkGLContext is an object representing the platform-specific + * `GdkGLContext` is an object representing a platform-specific * OpenGL draw context. * - * #GdkGLContexts are created for a #GdkSurface using - * gdk_surface_create_gl_context(), and the context will match the - * the characteristics of the surface. + * `GdkGLContext`s are created for a surface using + * [method@Gdk.Surface.create_gl_context], and the context will match + * the the characteristics of the surface. * - * A #GdkGLContext is not tied to any particular normal framebuffer. - * For instance, it cannot draw to the #GdkSurface back buffer. The GDK + * A `GdkGLContext` is not tied to any particular normal framebuffer. + * For instance, it cannot draw to the surface back buffer. The GDK * repaint system is in full control of the painting to that. Instead, - * you can create render buffers or textures and use gdk_cairo_draw_from_gl() + * you can create render buffers or textures and use [func@cairo_draw_from_gl] * in the draw function of your widget to draw them. Then GDK will handle * the integration of your rendering with that of other widgets. * - * Support for #GdkGLContext is platform-specific, context creation + * Support for `GdkGLContext` is platform-specific and context creation * can fail, returning %NULL context. * - * A #GdkGLContext has to be made "current" in order to start using + * A `GdkGLContext` has to be made "current" in order to start using * it, otherwise any OpenGL call will be ignored. * - * ## Creating a new OpenGL context ## + * ## Creating a new OpenGL context * - * In order to create a new #GdkGLContext instance you need a - * #GdkSurface, which you typically get during the realize call - * of a widget. + * In order to create a new `GdkGLContext` instance you need a `GdkSurface`, + * which you typically get during the realize call of a widget. * - * A #GdkGLContext is not realized until either gdk_gl_context_make_current(), - * or until it is realized using gdk_gl_context_realize(). It is possible to - * specify details of the GL context like the OpenGL version to be used, or - * whether the GL context should have extra state validation enabled after - * calling gdk_surface_create_gl_context() by calling gdk_gl_context_realize(). - * If the realization fails you have the option to change the settings of the - * #GdkGLContext and try again. + * A `GdkGLContext` is not realized until either [method@Gdk.GLContext.make_current] + * or [method@Gdk.GLContext.realize] is called. It is possible to specify + * details of the GL context like the OpenGL version to be used, or whether + * the GL context should have extra state validation enabled after calling + * [method@Gdk.Surface.create_gl_context] by calling [method@Gdk.GLContext.realize]. + * If the realization fails you have the option to change the settings of + * the `GdkGLContext` and try again. * - * ## Using a GdkGLContext ## + * ## Using a GdkGLContext * - * You will need to make the #GdkGLContext the current context - * before issuing OpenGL calls; the system sends OpenGL commands to - * whichever context is current. It is possible to have multiple - * contexts, so you always need to ensure that the one which you - * want to draw with is the current one before issuing commands: + * You will need to make the `GdkGLContext` the current context before issuing + * OpenGL calls; the system sends OpenGL commands to whichever context is current. + * It is possible to have multiple contexts, so you always need to ensure that + * the one which you want to draw with is the current one before issuing commands: * - * |[ - * gdk_gl_context_make_current (context); - * ]| + * ```c + * gdk_gl_context_make_current (context); + * ``` * * You can now perform your drawing using OpenGL commands. * - * You can check which #GdkGLContext is the current one by using - * gdk_gl_context_get_current(); you can also unset any #GdkGLContext - * that is currently set by calling gdk_gl_context_clear_current(). - */ - -/** - * GdkGLContext: - * - * The GdkGLContext struct contains only private fields and - * should not be accessed directly. + * You can check which `GdkGLContext` is the current one by using + * [func@Gdk.GLContext.get_current]; you can also unset any `GdkGLContext` + * that is currently set by calling [func@Gdk.GLContext.clear_current]. */ #include "config.h" @@ -425,7 +414,7 @@ gdk_gl_context_class_init (GdkGLContextClass *klass) /** * GdkGLContext:shared-context: * - * The #GdkGLContext that this context is sharing data with, or %NULL + * The `GdkGLContext` that this context is sharing data with, or %NULL */ obj_pspecs[PROP_SHARED_CONTEXT] = g_param_spec_object ("shared-context", @@ -566,14 +555,15 @@ gdk_gl_context_has_unpack_subimage (GdkGLContext *context) /** * gdk_gl_context_set_debug_enabled: - * @context: a #GdkGLContext + * @context: a `GdkGLContext` * @enabled: whether to enable debugging in the context * - * Sets whether the #GdkGLContext should perform extra validations and - * run time checking. This is useful during development, but has - * additional overhead. + * Sets whether the `GdkGLContext` should perform extra validations and + * runtime checking. * - * The #GdkGLContext must not be realized or made current prior to + * This is useful during development, but has additional overhead. + * + * The `GdkGLContext` must not be realized or made current prior to * calling this function. */ void @@ -592,9 +582,11 @@ gdk_gl_context_set_debug_enabled (GdkGLContext *context, /** * gdk_gl_context_get_debug_enabled: - * @context: a #GdkGLContext + * @context: a `GdkGLContext` * - * Retrieves the value set using gdk_gl_context_set_debug_enabled(). + * Retrieves whether the context is doing extra validations and runtime checking. + * + * See [method@Gdk.GLContext.set_debug_enabled]. * * Returns: %TRUE if debugging is enabled */ @@ -610,17 +602,17 @@ gdk_gl_context_get_debug_enabled (GdkGLContext *context) /** * gdk_gl_context_set_forward_compatible: - * @context: a #GdkGLContext - * @compatible: whether the context should be forward compatible + * @context: a `GdkGLContext` + * @compatible: whether the context should be forward-compatible * - * Sets whether the #GdkGLContext should be forward compatible. + * Sets whether the `GdkGLContext` should be forward-compatible. * - * Forward compatible contexts must not support OpenGL functionality that + * Forward-compatible contexts must not support OpenGL functionality that * has been marked as deprecated in the requested version; non-forward * compatible contexts, on the other hand, must support both deprecated and * non deprecated functionality. * - * The #GdkGLContext must not be realized or made current prior to calling + * The `GdkGLContext` must not be realized or made current prior to calling * this function. */ void @@ -639,11 +631,13 @@ gdk_gl_context_set_forward_compatible (GdkGLContext *context, /** * gdk_gl_context_get_forward_compatible: - * @context: a #GdkGLContext + * @context: a `GdkGLContext` * - * Retrieves the value set using gdk_gl_context_set_forward_compatible(). + * Retrieves whether the context is forward-compatible. * - * Returns: %TRUE if the context should be forward compatible + * See [method@Gdk.GLContext.set_forward_compatible]. + * + * Returns: %TRUE if the context should be forward-compatible */ gboolean gdk_gl_context_get_forward_compatible (GdkGLContext *context) @@ -657,7 +651,7 @@ gdk_gl_context_get_forward_compatible (GdkGLContext *context) /** * gdk_gl_context_set_required_version: - * @context: a #GdkGLContext + * @context: a `GdkGLContext` * @major: the major version to request * @minor: the minor version to request * @@ -665,7 +659,7 @@ gdk_gl_context_get_forward_compatible (GdkGLContext *context) * * Setting @major and @minor to zero will use the default values. * - * The #GdkGLContext must not be realized or made current prior to calling + * The `GdkGLContext` must not be realized or made current prior to calling * this function. */ void @@ -716,12 +710,13 @@ gdk_gl_context_set_required_version (GdkGLContext *context, /** * gdk_gl_context_get_required_version: - * @context: a #GdkGLContext + * @context: a `GdkGLContext` * @major: (out) (nullable): return location for the major version to request * @minor: (out) (nullable): return location for the minor version to request * - * Retrieves the major and minor version requested by calling - * gdk_gl_context_set_required_version(). + * Retrieves required OpenGL version. + * + * See [method@Gdk.GLContext.set_required_version]. */ void gdk_gl_context_get_required_version (GdkGLContext *context, @@ -776,11 +771,11 @@ gdk_gl_context_get_required_version (GdkGLContext *context, /** * gdk_gl_context_is_legacy: - * @context: a #GdkGLContext + * @context: a `GdkGLContext` * - * Whether the #GdkGLContext is in legacy mode or not. + * Whether the `GdkGLContext` is in legacy mode or not. * - * The #GdkGLContext must be realized before calling this function. + * The `GdkGLContext` must be realized before calling this function. * * When realizing a GL context, GDK will try to use the OpenGL 3.2 core * profile; this profile removes all the OpenGL API that was deprecated @@ -819,12 +814,13 @@ gdk_gl_context_set_is_legacy (GdkGLContext *context, /** * gdk_gl_context_set_use_es: - * @context: a #GdkGLContext: + * @context: a `GdkGLContext` * @use_es: whether the context should use OpenGL ES instead of OpenGL, * or -1 to allow auto-detection * - * Requests that GDK create an OpenGL ES context instead of an OpenGL one, - * if the platform and windowing system allows it. + * Requests that GDK create an OpenGL ES context instead of an OpenGL one. + * + * Not all platforms support OpenGL ES. * * The @context must not have been realized. * @@ -832,9 +828,9 @@ gdk_gl_context_set_is_legacy (GdkGLContext *context, * underlying GL implementation is OpenGL or OpenGL ES once the @context * is realized. * - * You should check the return value of gdk_gl_context_get_use_es() after - * calling gdk_gl_context_realize() to decide whether to use the OpenGL or - * OpenGL ES API, extensions, or shaders. + * You should check the return value of [method@Gdk.GLContext.get_use_es] + * after calling [method@Gdk.GLContext.realize] to decide whether to use + * the OpenGL or OpenGL ES API, extensions, or shaders. */ void gdk_gl_context_set_use_es (GdkGLContext *context, @@ -851,11 +847,11 @@ gdk_gl_context_set_use_es (GdkGLContext *context, /** * gdk_gl_context_get_use_es: - * @context: a #GdkGLContext + * @context: a `GdkGLContext` * * Checks whether the @context is using an OpenGL or OpenGL ES profile. * - * Returns: %TRUE if the #GdkGLContext is using an OpenGL ES profile + * Returns: %TRUE if the `GdkGLContext` is using an OpenGL ES profile */ gboolean gdk_gl_context_get_use_es (GdkGLContext *context) @@ -963,12 +959,12 @@ gl_debug_message_callback (GLenum source, /** * gdk_gl_context_realize: - * @context: a #GdkGLContext - * @error: return location for a #GError + * @context: a `GdkGLContext` + * @error: return location for a `GError` * - * Realizes the given #GdkGLContext. + * Realizes the given `GdkGLContext`. * - * It is safe to call this function on a realized #GdkGLContext. + * It is safe to call this function on a realized `GdkGLContext`. * * Returns: %TRUE if the context is realized */ @@ -1088,7 +1084,7 @@ gdk_gl_context_check_extensions (GdkGLContext *context) /** * gdk_gl_context_make_current: - * @context: a #GdkGLContext + * @context: a `GdkGLContext` * * Makes the @context the current one. */ @@ -1127,11 +1123,11 @@ gdk_gl_context_make_current (GdkGLContext *context) /** * gdk_gl_context_get_display: - * @context: a #GdkGLContext + * @context: a `GdkGLContext` * - * Retrieves the #GdkDisplay the @context is created for + * Retrieves the display the @context is created for * - * Returns: (nullable) (transfer none): a #GdkDisplay or %NULL + * Returns: (nullable) (transfer none): a `GdkDisplay` or %NULL */ GdkDisplay * gdk_gl_context_get_display (GdkGLContext *context) @@ -1143,11 +1139,11 @@ gdk_gl_context_get_display (GdkGLContext *context) /** * gdk_gl_context_get_surface: - * @context: a #GdkGLContext + * @context: a `GdkGLContext` * - * Retrieves the #GdkSurface used by the @context. + * Retrieves the surface used by the @context. * - * Returns: (nullable) (transfer none): a #GdkSurface or %NULL + * Returns: (nullable) (transfer none): a `GdkSurface` or %NULL */ GdkSurface * gdk_gl_context_get_surface (GdkGLContext *context) @@ -1159,11 +1155,11 @@ gdk_gl_context_get_surface (GdkGLContext *context) /** * gdk_gl_context_get_shared_context: - * @context: a #GdkGLContext + * @context: a `GdkGLContext` * - * Retrieves the #GdkGLContext that this @context share data with. + * Retrieves the `GdkGLContext` that this @context share data with. * - * Returns: (nullable) (transfer none): a #GdkGLContext or %NULL + * Returns: (nullable) (transfer none): a `GdkGLContext` or %NULL */ GdkGLContext * gdk_gl_context_get_shared_context (GdkGLContext *context) @@ -1177,7 +1173,7 @@ gdk_gl_context_get_shared_context (GdkGLContext *context) /** * gdk_gl_context_get_version: - * @context: a #GdkGLContext + * @context: a `GdkGLContext` * @major: (out): return location for the major version * @minor: (out): return location for the minor version * @@ -1204,10 +1200,10 @@ gdk_gl_context_get_version (GdkGLContext *context, /** * gdk_gl_context_clear_current: * - * Clears the current #GdkGLContext. + * Clears the current `GdkGLContext`. * * Any OpenGL call after this function returns will be ignored - * until gdk_gl_context_make_current() is called. + * until [method@Gdk.GLContext.make_current] is called. */ void gdk_gl_context_clear_current (void) @@ -1225,9 +1221,9 @@ gdk_gl_context_clear_current (void) /** * gdk_gl_context_get_current: * - * Retrieves the current #GdkGLContext. + * Retrieves the current `GdkGLContext`. * - * Returns: (nullable) (transfer none): the current #GdkGLContext, or %NULL + * Returns: (nullable) (transfer none): the current `GdkGLContext`, or %NULL */ GdkGLContext * gdk_gl_context_get_current (void) diff --git a/gdk/gdkgltexture.c b/gdk/gdkgltexture.c index 5688513528..caf3e7ab6b 100644 --- a/gdk/gdkgltexture.c +++ b/gdk/gdkgltexture.c @@ -25,6 +25,12 @@ #include +/** + * GdkGLTexture: + * + * A GdkTexture representing a GL texture object. + */ + struct _GdkGLTexture { GdkTexture parent_instance; @@ -133,14 +139,13 @@ gdk_gl_texture_get_id (GdkGLTexture *self) /** * gdk_gl_texture_release: - * @self: a #GdkTexture wrapping a GL texture + * @self: a `GdkTexture` wrapping a GL texture * - * Releases the GL resources held by a #GdkGLTexture that - * was created with gdk_gl_texture_new(). + * Releases the GL resources held by a `GdkGLTexture`. * * The texture contents are still available via the - * gdk_texture_download() function, after this function - * has been called. + * [method@Gdk.Texture.download] function, after this + * function has been called. */ void gdk_gl_texture_release (GdkGLTexture *self) @@ -177,21 +182,21 @@ gdk_gl_texture_release (GdkGLTexture *self) /** * gdk_gl_texture_new: - * @context: a #GdkGLContext + * @context: a `GdkGLContext` * @id: the ID of a texture that was created with @context * @width: the nominal width of the texture * @height: the nominal height of the texture * @destroy: a destroy notify that will be called when the GL resources - * are released + * are released * @data: data that gets passed to @destroy * * Creates a new texture for an existing GL texture. * * Note that the GL texture must not be modified until @destroy is called, * which will happen when the GdkTexture object is finalized, or due to - * an explicit call of gdk_gl_texture_release(). + * an explicit call of [method@Gdk.GLTexture.release]. * - * Return value: (transfer full): A newly-created #GdkTexture + * Return value: (transfer full): A newly-created `GdkTexture` */ GdkTexture * gdk_gl_texture_new (GdkGLContext *context, diff --git a/gdk/gdkgltexture.h b/gdk/gdkgltexture.h index bdc70a0cad..54e4fee7e7 100644 --- a/gdk/gdkgltexture.h +++ b/gdk/gdkgltexture.h @@ -33,11 +33,6 @@ G_BEGIN_DECLS #define GDK_GL_TEXTURE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GDK_TYPE_GL_TEXTURE, GdkGLTexture)) #define GDK_IS_GL_TEXTURE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GDK_TYPE_GL_TEXTURE)) -/** - * GdkGLTexture: - * - * A #GdkTexture representing a GL texture object. - */ typedef struct _GdkGLTexture GdkGLTexture; typedef struct _GdkGLTextureClass GdkGLTextureClass; diff --git a/gdk/gdkmemorytexture.c b/gdk/gdkmemorytexture.c index 663d0409f9..06fa3d6619 100644 --- a/gdk/gdkmemorytexture.c +++ b/gdk/gdkmemorytexture.c @@ -21,6 +21,12 @@ #include "gdkmemorytextureprivate.h" +/** + * GdkMemoryTexture: + * + * A `GdkTexture` representing image data in memory. + */ + struct _GdkMemoryTexture { GdkTexture parent_instance; @@ -111,14 +117,15 @@ gdk_memory_texture_init (GdkMemoryTexture *self) * @width: the width of the texture * @height: the height of the texture * @format: the format of the data - * @bytes: the #GBytes containing the pixel data + * @bytes: the `GBytes` containing the pixel data * @stride: rowstride for the data * * Creates a new texture for a blob of image data. - * The #GBytes must contain @stride x @height pixels + * + * The `GBytes` must contain @stride x @height pixels * in the given format. * - * Returns: A newly-created #GdkTexture + * Returns: A newly-created `GdkTexture` */ GdkTexture * gdk_memory_texture_new (int width, diff --git a/gdk/gdkmemorytexture.h b/gdk/gdkmemorytexture.h index d4161d60de..090b5c6275 100644 --- a/gdk/gdkmemorytexture.h +++ b/gdk/gdkmemorytexture.h @@ -45,14 +45,14 @@ G_BEGIN_DECLS * @GDK_MEMORY_N_FORMATS: The number of formats. This value will change as * more formats get added, so do not rely on its concrete integer. * - * #GdkMemoryFormat describes a format that bytes can have in memory. + * `GdkMemoryFormat` describes a format that bytes can have in memory. * * It describes formats by listing the contents of the memory passed to it. * So GDK_MEMORY_A8R8G8B8 will be 1 byte (8 bits) of alpha, followed by a * byte each of red, green and blue. It is not endian-dependent, so - * CAIRO_FORMAT_ARGB32 is represented by different #GdkMemoryFormats on - * architectures with different endiannesses. - * + * CAIRO_FORMAT_ARGB32 is represented by different `GdkMemoryFormats` + * on architectures with different endiannesses. + * * Its naming is modelled after VkFormat (see * https://www.khronos.org/registry/vulkan/specs/1.0/html/vkspec.html#VkFormat * for details). @@ -74,12 +74,13 @@ typedef enum { /** * GDK_MEMORY_DEFAULT: * - * This is the default memory format used by GTK and is the format - * provided by gdk_texture_download(). It is equal to - * %CAIRO_FORMAT_ARGB32. + * The default memory format used by GTK. * - * Be aware that unlike the #GdkMemoryFormat values, this format is - * different for different endianness. + * This is the format provided by [method@Gdk.Texture.download]. + * It is equal to %CAIRO_FORMAT_ARGB32. + * + * Be aware that unlike the #GdkMemoryFormat values, this format + * is different for different endianness. */ #if G_BYTE_ORDER == G_LITTLE_ENDIAN #define GDK_MEMORY_DEFAULT GDK_MEMORY_B8G8R8A8_PREMULTIPLIED @@ -94,11 +95,6 @@ typedef enum { #define GDK_MEMORY_TEXTURE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GDK_TYPE_MEMORY_TEXTURE, GdkMemoryTexture)) #define GDK_IS_MEMORY_TEXTURE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GDK_TYPE_MEMORY_TEXTURE)) -/** - * GdkMemoryTexture: - * - * A #GdkTexture representing image data in memory. - */ typedef struct _GdkMemoryTexture GdkMemoryTexture; typedef struct _GdkMemoryTextureClass GdkMemoryTextureClass; diff --git a/gdk/gdkmonitor.c b/gdk/gdkmonitor.c index 46edc8a5c4..0e9bd5064d 100644 --- a/gdk/gdkmonitor.c +++ b/gdk/gdkmonitor.c @@ -25,22 +25,16 @@ #include "gdkdisplay.h" #include "gdkenumtypes.h" -/** - * SECTION:gdkmonitor - * @Title: GdkMonitor - * @Short_description: Object representing an output - * - * GdkMonitor objects represent the individual outputs that are - * associated with a #GdkDisplay. GdkDisplay keeps a #GListModel to enumerate - * and monitor monitors with gdk_display_get_monitors(). - * You can use gdk_display_get_monitor_at_surface() to find a particular monitor. - */ - /** * GdkMonitor: * - * The GdkMonitor struct contains only private fields and should not - * be accessed directly. + * `GdkMonitor` objects represent the individual outputs that are + * associated with a `GdkDisplay`. + * + * `GdkDisplay` keeps a `GListModel` to enumerate and monitor + * monitors with [method@Gdk.Display.get_monitors]. You can use + * [method@Gdk.Display.get_monitor_at_surface] to find a particular + * monitor. */ enum { @@ -176,30 +170,59 @@ gdk_monitor_class_init (GdkMonitorClass *class) object_class->get_property = gdk_monitor_get_property; object_class->set_property = gdk_monitor_set_property; + /** + * GdkMonitor:display: + * + * The `GdkDisplay` of the monitor. + */ props[PROP_DISPLAY] = g_param_spec_object ("display", "Display", "The display of the monitor", GDK_TYPE_DISPLAY, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS); + + /** + * GdkMonitor:manufacturer: + * + * The manufacturer name. + */ props[PROP_MANUFACTURER] = g_param_spec_string ("manufacturer", "Manufacturer", "The manufacturer name", NULL, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + + /** + * GdkMonitor:model: + * + * The model name. + */ props[PROP_MODEL] = g_param_spec_string ("model", "Model", "The model name", NULL, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + + /** + * GdkMonitor:connector: + * + * The connector name. + */ props[PROP_CONNECTOR] = g_param_spec_string ("connector", "Connector", "The connector name", NULL, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + + /** + * GdkMonitor:scale-factor: + * + * The scale factor. + */ props[PROP_SCALE_FACTOR] = g_param_spec_int ("scale-factor", "Scale factor", @@ -207,12 +230,24 @@ gdk_monitor_class_init (GdkMonitorClass *class) 0, G_MAXINT, 1, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + + /** + * GdkMonitor:geometry: + * + * The geometry of the monitor. + */ props[PROP_GEOMETRY] = g_param_spec_boxed ("geometry", "Geometry", "The geometry of the monitor", GDK_TYPE_RECTANGLE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + + /** + * GdkMonitor:width-mm: + * + * The width of the monitor, in millimeters. + */ props[PROP_WIDTH_MM] = g_param_spec_int ("width-mm", "Physical width", @@ -220,6 +255,12 @@ gdk_monitor_class_init (GdkMonitorClass *class) 0, G_MAXINT, 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + + /** + * GdkMonitor:height-mm: + * + * The height of the monitor, in millimeters. + */ props[PROP_HEIGHT_MM] = g_param_spec_int ("height-mm", "Physical height", @@ -227,6 +268,12 @@ gdk_monitor_class_init (GdkMonitorClass *class) 0, G_MAXINT, 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + + /** + * GdkMonitor:refresh-rate: + * + * The refresh rate, in milli-Hertz. + */ props[PROP_REFRESH_RATE] = g_param_spec_int ("refresh-rate", "Refresh rate", @@ -234,6 +281,12 @@ gdk_monitor_class_init (GdkMonitorClass *class) 0, G_MAXINT, 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + + /** + * GdkMonitor:subpixel-layout: + * + * The subpixel layout. + */ props[PROP_SUBPIXEL_LAYOUT] = g_param_spec_enum ("subpixel-layout", "Subpixel layout", @@ -241,6 +294,12 @@ gdk_monitor_class_init (GdkMonitorClass *class) GDK_TYPE_SUBPIXEL_LAYOUT, GDK_SUBPIXEL_LAYOUT_UNKNOWN, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + + /** + * GdkMonitor:valid: + * + * Whether the object is still valid. + */ props[PROP_VALID] = g_param_spec_boolean ("valid", "Valid", @@ -254,8 +313,7 @@ gdk_monitor_class_init (GdkMonitorClass *class) * GdkMonitor::invalidate: * @monitor: the object on which this signal was emitted * - * The ::invalidate signal gets emitted when the output represented - * by @monitor gets disconnected. + * Emitted when the output represented by @monitor gets disconnected. */ signals[INVALIDATE] = g_signal_new (g_intern_static_string ("invalidate"), G_TYPE_FROM_CLASS (object_class), @@ -268,7 +326,7 @@ gdk_monitor_class_init (GdkMonitorClass *class) /** * gdk_monitor_get_display: - * @monitor: a #GdkMonitor + * @monitor: a `GdkMonitor` * * Gets the display that this monitor belongs to. * @@ -284,12 +342,14 @@ gdk_monitor_get_display (GdkMonitor *monitor) /** * gdk_monitor_get_geometry: - * @monitor: a #GdkMonitor - * @geometry: (out): a #GdkRectangle to be filled with the monitor geometry + * @monitor: a `GdkMonitor` + * @geometry: (out): a `GdkRectangle` to be filled with the monitor geometry * - * Retrieves the size and position of an individual monitor within the - * display coordinate space. The returned geometry is in ”application pixels”, - * not in ”device pixels” (see gdk_monitor_get_scale_factor()). + * Retrieves the size and position of the monitor within the + * display coordinate space. + * + * The returned geometry is in ”application pixels”, not in + * ”device pixels” (see [method@Gdk.Monitor.get_scale_factor]). */ void gdk_monitor_get_geometry (GdkMonitor *monitor, @@ -303,7 +363,7 @@ gdk_monitor_get_geometry (GdkMonitor *monitor, /** * gdk_monitor_get_width_mm: - * @monitor: a #GdkMonitor + * @monitor: a `GdkMonitor` * * Gets the width in millimeters of the monitor. * @@ -319,7 +379,7 @@ gdk_monitor_get_width_mm (GdkMonitor *monitor) /** * gdk_monitor_get_height_mm: - * @monitor: a #GdkMonitor + * @monitor: a `GdkMonitor` * * Gets the height in millimeters of the monitor. * @@ -335,7 +395,7 @@ gdk_monitor_get_height_mm (GdkMonitor *monitor) /** * gdk_monitor_get_connector: - * @monitor: a #GdkMonitor + * @monitor: a `GdkMonitor` * * Gets the name of the monitor's connector, if available. * @@ -351,16 +411,18 @@ gdk_monitor_get_connector (GdkMonitor *monitor) /** * gdk_monitor_get_manufacturer: - * @monitor: a #GdkMonitor + * @monitor: a `GdkMonitor` * - * Gets the name or PNP ID of the monitor's manufacturer, if available. + * Gets the name or PNP ID of the monitor's manufacturer. * * Note that this value might also vary depending on actual * display backend. * - * PNP ID registry is located at https://uefi.org/pnp_id_list + * The PNP ID registry is located at + * [https://uefi.org/pnp_id_list](https://uefi.org/pnp_id_list). * - * Returns: (transfer none) (nullable): the name of the manufacturer, or %NULL + * Returns: (transfer none) (nullable): the name of the manufacturer, + * or %NULL */ const char * gdk_monitor_get_manufacturer (GdkMonitor *monitor) @@ -372,7 +434,7 @@ gdk_monitor_get_manufacturer (GdkMonitor *monitor) /** * gdk_monitor_get_model: - * @monitor: a #GdkMonitor + * @monitor: a `GdkMonitor` * * Gets the string identifying the monitor model, if available. * @@ -388,15 +450,17 @@ gdk_monitor_get_model (GdkMonitor *monitor) /** * gdk_monitor_get_scale_factor: - * @monitor: a #GdkMonitor + * @monitor: a `GdkMonitor` * * Gets the internal scale factor that maps from monitor coordinates - * to the actual device pixels. On traditional systems this is 1, but - * on very high density outputs this can be a higher value (often 2). + * to device pixels. + * + * On traditional systems this is 1, but on very high density outputs + * it can be a higher value (often 2). * * This can be used if you want to create pixel based data for a * particular monitor, but most of the time you’re drawing to a surface - * where it is better to use gdk_surface_get_scale_factor() instead. + * where it is better to use [method@Gdk.Surface.get_scale_factor] instead. * * Returns: the scale factor */ @@ -410,7 +474,7 @@ gdk_monitor_get_scale_factor (GdkMonitor *monitor) /** * gdk_monitor_get_refresh_rate: - * @monitor: a #GdkMonitor + * @monitor: a `GdkMonitor` * * Gets the refresh rate of the monitor, if available. * @@ -429,10 +493,10 @@ gdk_monitor_get_refresh_rate (GdkMonitor *monitor) /** * gdk_monitor_get_subpixel_layout: - * @monitor: a #GdkMonitor + * @monitor: a `GdkMonitor` * * Gets information about the layout of red, green and blue - * primaries for each pixel in this monitor, if available. + * primaries for pixels. * * Returns: the subpixel layout */ @@ -561,11 +625,13 @@ gdk_monitor_invalidate (GdkMonitor *monitor) /** * gdk_monitor_is_valid: - * @monitor: a #GdkMonitor + * @monitor: a `GdkMonitor` * * Returns %TRUE if the @monitor object corresponds to a - * physical monitor. The @monitor becomes invalid when the - * physical monitor is unplugged or removed. + * physical monitor. + * + * The @monitor becomes invalid when the physical monitor + * is unplugged or removed. * * Returns: %TRUE if the object corresponds to a physical monitor */ diff --git a/gdk/gdkpaintable.c b/gdk/gdkpaintable.c index a1726401b0..0c0c5dea14 100644 --- a/gdk/gdkpaintable.c +++ b/gdk/gdkpaintable.c @@ -30,52 +30,53 @@ void gtk_snapshot_push_debug (GdkSnapshot void gtk_snapshot_pop (GdkSnapshot *snapshot); /** - * SECTION:gdkpaintable - * @Title: GdkPaintable - * @Short_description: An interface for a paintable region - * @See_also: #ClutterContent, #GtkImage, #GdkTexture, #GtkSnapshot + * GdkPaintable: * - * #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), + * `GdkPaintable` is a simple interface used by GTK to represent content that + * can be painted. + * + * The content of a `GdkPaintable` 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), * [HTML/CSS Paint Sources](https://www.w3.org/TR/css-images-4/#paint-source), * or [SVG Paint Servers](https://www.w3.org/TR/SVG2/pservers.html). * - * A #GdkPaintable can be snapshot at any time and size using - * gdk_paintable_snapshot(). How the paintable interprets that size and if it - * scales or centers itself into the given rectangle is implementation defined, - * though if you are implementing a #GdkPaintable and don't know what to do, it - * is suggested that you scale your paintable ignoring any potential aspect ratio. + * A `GdkPaintable` can be snapshot at any time and size using + * [method@Gdk.Paintable.snapshot]. How the paintable interprets that size and + * if it scales or centers itself into the given rectangle is implementation + * defined, though if you are implementing a `GdkPaintable` and don't know what + * to do, it is suggested that you scale your paintable ignoring any potential + * aspect ratio. * - * The contents that a #GdkPaintable produces may depend on the #GdkSnapshot passed - * to it. For example, paintables may decide to use more detailed images on higher - * resolution screens or when OpenGL is available. A #GdkPaintable will however - * always produce the same output for the same snapshot. + * The contents that a `GdkPaintable` produces may depend on the [class@GdkSnapshot] + * passed to it. For example, paintables may decide to use more detailed images + * on higher resolution screens or when OpenGL is available. A `GdkPaintable` + * will however always produce the same output for the same snapshot. * - * A #GdkPaintable may change its contents, meaning that it will now produce a - * different output with the same snapshot. Once that happens, it will call - * gdk_paintable_invalidate_contents() which will emit the - * #GdkPaintable::invalidate-contents signal. If a paintable is known to never - * change its contents, it will set the %GDK_PAINTABLE_STATIC_CONTENTS flag. - * If a consumer cannot deal with changing contents, it may call - * gdk_paintable_get_current_image() which will return a static paintable and - * use that. + * A `GdkPaintable` may change its contents, meaning that it will now produce + * a different output with the same snapshot. Once that happens, it will call + * [method@Gdk.Paintable.invalidate_contents] which will emit the + * [signal@GdkPaintable::invalidate-contents] signal. If a paintable is known + * to never change its contents, it will set the %GDK_PAINTABLE_STATIC_CONTENTS + * flag. If a consumer cannot deal with changing contents, it may call + * [method@Gdk.Paintable.get_current_image] which will return a static + * paintable and use that. * * A paintable can report an intrinsic (or preferred) size or aspect ratio it * wishes to be rendered at, though it doesn't have to. Consumers of the interface - * can use this information to layout thepaintable appropriately. - * Just like the contents, the size of a paintable can change. A paintable will - * indicate this by calling gdk_paintable_invalidate_size() which will emit the - * #GdkPaintable::invalidate-size signal. - * And just like for contents, if a paintable is known to never change its size, - * it will set the %GDK_PAINTABLE_STATIC_SIZE flag. + * can use this information to layout thepaintable appropriately. Just like the + * contents, the size of a paintable can change. A paintable will indicate this + * by calling [method@Gdk.Paintable.invalidate_size] which will emit the + * [signal@GdkPaintable::invalidate-size] signal. And just like for contents, + * if a paintable is known to never change its size, it will set the + * %GDK_PAINTABLE_STATIC_SIZE flag. * * Besides API for applications, there are some functions that are only * useful for implementing subclasses and should not be used by applications: - * gdk_paintable_invalidate_contents(), - * gdk_paintable_invalidate_size(), - * gdk_paintable_new_empty(). + * [method@Gdk.Paintable.invalidate_contents], + * [method@Gdk.Paintable.invalidate_size], + * [func@Gdk.Paintable.new_empty]. */ G_DEFINE_INTERFACE (GdkPaintable, gdk_paintable, G_TYPE_OBJECT) @@ -161,7 +162,7 @@ gdk_paintable_default_init (GdkPaintableInterface *iface) /** * GdkPaintable::invalidate-contents - * @paintable: a #GdkPaintable + * @paintable: a `GdkPaintable` * * Emitted when the contents of the @paintable change. * @@ -179,15 +180,18 @@ gdk_paintable_default_init (GdkPaintableInterface *iface) /** * GdkPaintable::invalidate-size - * @paintable: a #GdkPaintable + * @paintable: a `GdkPaintable` * - * Emitted when the intrinsic size of the @paintable changes. This means the values - * reported by at least one of gdk_paintable_get_intrinsic_width(), - * gdk_paintable_get_intrinsic_height() or gdk_paintable_get_intrinsic_aspect_ratio() + * Emitted when the intrinsic size of the @paintable changes. + * + * This means the values reported by at least one of + * [method@Gdk.Paintable.get_intrinsic_width], + * [method@Gdk.Paintable.get_intrinsic_height] or + * [method@Gdk.Paintable.get_intrinsic_aspect_ratio] * has changed. * - * Examples for such an event would be a paintable displaying the contents of a toplevel - * surface being resized. + * Examples for such an event would be a paintable displaying + * the contents of a toplevel surface being resized. */ signals[INVALIDATE_SIZE] = g_signal_new ("invalidate-size", @@ -201,14 +205,16 @@ gdk_paintable_default_init (GdkPaintableInterface *iface) /** * gdk_paintable_snapshot: - * @paintable: a #GdkPaintable - * @snapshot: a #GdkSnapshot to snapshot to + * @paintable: a `GdkPaintable` + * @snapshot: a `GdkSnapshot` to snapshot to * @width: width to snapshot in * @height: height to snapshot in * - * Snapshots the given paintable with the given @width and @height at the - * current (0,0) offset of the @snapshot. If @width and @height are not larger - * than zero, this function will do nothing. + * Snapshots the given paintable with the given @width and @height. + * + * The paintable is drawn at the current (0,0) offset of the @snapshot. + * If @width and @height are not larger than zero, this function will + * do nothing. */ void gdk_paintable_snapshot (GdkPaintable *paintable, @@ -241,12 +247,12 @@ gdk_paintable_is_immutable (GdkPaintable *paintable) /** * gdk_paintable_get_current_image: - * @paintable: a #GdkPaintable + * @paintable: a `GdkPaintable` * * Gets an immutable paintable for the current contents displayed by @paintable. * - * This is useful when you want to retain the current state of an animation, for - * example to take a screenshot of a running animation. + * This is useful when you want to retain the current state of an animation, + * for example to take a screenshot of a running animation. * * If the @paintable is already immutable, it will return itself. * @@ -269,13 +275,15 @@ gdk_paintable_get_current_image (GdkPaintable *paintable) /** * gdk_paintable_get_flags: - * @paintable: a #GdkPaintable + * @paintable: a `GdkPaintable` * - * Get flags for the paintable. This is oftentimes useful for optimizations. + * Get flags for the paintable. * - * See #GdkPaintableFlags for the flags and what they mean. + * This is oftentimes useful for optimizations. * - * Returns: The #GdkPaintableFlags for this paintable. + * See [flags@Gdk.PaintableFlags] for the flags and what they mean. + * + * Returns: The `GdkPaintableFlags` for this paintable */ GdkPaintableFlags gdk_paintable_get_flags (GdkPaintable *paintable) @@ -290,17 +298,18 @@ gdk_paintable_get_flags (GdkPaintable *paintable) /** * gdk_paintable_get_intrinsic_width: - * @paintable: a #GdkPaintable + * @paintable: a `GdkPaintable` * * Gets the preferred width the @paintable would like to be displayed at. + * * Consumers of this interface can use this to reserve enough space to draw * 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(). + * This is a purely informational value and does not in any way limit the + * values that may be passed to [method@Gdk.Paintable.snapshot]. * - * If the @paintable does not have a preferred width, it returns 0. Negative - * values are never returned. + * If the @paintable does not have a preferred width, it returns 0. + * Negative values are never returned. * * Returns: the intrinsic width of @paintable or 0 if none. */ @@ -317,17 +326,18 @@ gdk_paintable_get_intrinsic_width (GdkPaintable *paintable) /** * gdk_paintable_get_intrinsic_height: - * @paintable: a #GdkPaintable + * @paintable: a `GdkPaintable` * * Gets the preferred height the @paintable would like to be displayed at. + * * Consumers of this interface can use this to reserve enough space to draw * 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(). + * This is a purely informational value and does not in any way limit the + * values that may be passed to [method@Gdk.Paintable.snapshot]. * - * If the @paintable does not have a preferred height, it returns 0. Negative - * values are never returned. + * If the @paintable does not have a preferred height, it returns 0. + * Negative values are never returned. * * Returns: the intrinsic height of @paintable or 0 if none. */ @@ -344,23 +354,25 @@ gdk_paintable_get_intrinsic_height (GdkPaintable *paintable) /** * gdk_paintable_get_intrinsic_aspect_ratio: - * @paintable: a #GdkPaintable + * @paintable: a `GdkPaintable` * * Gets the preferred aspect ratio the @paintable would like to be displayed at. - * 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 - * 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(). + * 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 the paintable. + * + * This is a purely informational value and does not in any way limit the + * values that may be passed to [method@Gdk.Paintable.snapshot]. * * 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. + * [method@Gdk.Paintable.get_intrinsic_width] and + * [method@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. - * Negative values are never returned. + * 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 if none. */ @@ -377,13 +389,15 @@ gdk_paintable_get_intrinsic_aspect_ratio (GdkPaintable *paintable) /** * gdk_paintable_invalidate_contents: - * @paintable: a #GdkPaintable + * @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 of gdk_paintable_snapshot() produce the same output. + * multiple calls of [method@Gdk.Paintable.snapshot] produce the same output. * - * This function will emit the #GdkPaintable::invalidate-contents signal. + * This function will emit the [signal@Gdk.Paintable::invalidate-contents] + * signal. * * If a @paintable reports the %GDK_PAINTABLE_STATIC_CONTENTS flag, * it must not call this function. @@ -399,13 +413,15 @@ gdk_paintable_invalidate_contents (GdkPaintable *paintable) /** * gdk_paintable_invalidate_size: - * @paintable: a #GdkPaintable + * @paintable: a `GdkPaintable` + * + * Called by implementations of `GdkPaintable` to invalidate their size. * - * 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. + * This function will emit the [signal@Gdk.Paintable::invalidate-size] + * signal. * * If a @paintable reports the %GDK_PAINTABLE_STATIC_SIZE flag, * it must not call this function. @@ -421,7 +437,7 @@ gdk_paintable_invalidate_size (GdkPaintable *paintable) /** * gdk_paintable_compute_concrete_size: - * @paintable: a #GdkPaintable + * @paintable: a `GdkPaintable` * @specified_width: the width @paintable could be drawn into or * 0.0 if unknown * @specified_height: the height @paintable could be drawn into or @@ -435,8 +451,10 @@ gdk_paintable_invalidate_size (GdkPaintable *paintable) * @concrete_height: (out): will be set to the concrete height * computed. * - * Applies the sizing algorithm outlined in - * https://drafts.csswg.org/css-images-3/#default-sizing + * Compute a concrete size for the `GdkPaintable`. + * + * Applies the sizing algorithm outlined in the + * [CSS Image spec](https://drafts.csswg.org/css-images-3/#default-sizing) * to the given @paintable. See that link for more details. * * It is not necessary to call this function when both @specified_width @@ -643,11 +661,13 @@ gdk_empty_paintable_init (GdkEmptyPaintable *self) * @intrinsic_height: The intrinsic height to report. Can be 0 for no height. * * Returns a paintable that has the given intrinsic size and draws nothing. - * This is often useful for implementing the #GdkPaintableInterface.get_current_image() - * virtual function when the paintable is in an incomplete state (like a - * #GtkMediaStream before receiving the first frame). * - * Returns: (transfer full): a #GdkPaintable + * This is often useful for implementing the + * #GdkPaintableInterface.get_current_image() virtual function + * when the paintable is in an incomplete state (like a + * [class@Gtk.MediaStream] before receiving the first frame). + * + * Returns: (transfer full): a `GdkPaintable` */ GdkPaintable * gdk_paintable_new_empty (int intrinsic_width, diff --git a/gdk/gdkpaintable.h b/gdk/gdkpaintable.h index 2936a75b7a..938aa2bf59 100644 --- a/gdk/gdkpaintable.h +++ b/gdk/gdkpaintable.h @@ -31,25 +31,21 @@ G_BEGIN_DECLS #define GDK_TYPE_PAINTABLE (gdk_paintable_get_type ()) -/** - * GdkPaintable: - * - * Interface for paintable objects. - */ GDK_AVAILABLE_IN_ALL G_DECLARE_INTERFACE (GdkPaintable, gdk_paintable, GDK, PAINTABLE, GObject) /** * GdkPaintableFlags: * @GDK_PAINTABLE_STATIC_SIZE: The size is immutable. - * The #GdkPaintable::invalidate-size signal will never be + * The [signal@GdkPaintable::invalidate-size] signal will never be * emitted. * @GDK_PAINTABLE_STATIC_CONTENTS: The content is immutable. - * The #GdkPaintable::invalidate-contents signal will never be + * The [signal@GdkPaintable::invalidate-contents] signal will never be * emitted. * - * Flags about this object. Implementations use these for optimizations - * such as caching. + * Flags about a paintable object. + * + * Implementations use these for optimizations such as caching. */ typedef enum { GDK_PAINTABLE_STATIC_SIZE = 1 << 0, @@ -78,14 +74,15 @@ typedef enum { * #GdkPaintableInterface.get_intrinsic_height() return non-zero values, * this function should return the aspect ratio computed from those. * - * The list of functions that can be implemented for the #GdkPaintable interface. + * The list of functions that can be implemented for the `GdkPaintable` + * interface. * - * Note that apart from the #GdkPaintableInterface.snapshot() function, no virtual - * function of this interface is mandatory to implement, though it is a good idea - * to implement #GdkPaintableInterface.get_current_image() for non-static paintables - * and #GdkPaintableInterface.get_flags() if the image is not dynamic as the default - * implementation returns no flags and that will make the implementation likely - * quite slow. + * Note that apart from the #GdkPaintableInterface.snapshot() function, no + * virtual function of this interface is mandatory to implement, though it + * is a good idea to implement #GdkPaintableInterface.get_current_image() + * for non-static paintables and #GdkPaintableInterface.get_flags() if the + * image is not dynamic as the default implementation returns no flags and + * that will make the implementation likely quite slow. */ struct _GdkPaintableInterface { diff --git a/gdk/gdkpopup.c b/gdk/gdkpopup.c index 26b8fe55dd..20f7ca23bd 100644 --- a/gdk/gdkpopup.c +++ b/gdk/gdkpopup.c @@ -24,16 +24,15 @@ #include "gdkpopupprivate.h" /** - * SECTION:gdkpopup - * @Short_description: Interface for popup surfaces - * @Title: Popups - * @See_also: #GdkToplevel, #GdkSurface + * GdkPopup: * - * A #GdkPopup is a surface that is attached to another surface, - * called its #GdkPopup:parent, and is positioned relative to it. + * A `GdkPopup` is a surface that is attached to another surface. * - * #GdkPopups are typically used to implement menus and similar popups. - * They can be modal, which is indicated by the #GdkPopup:autohide property. + * The `GdkPopup` is positioned relative to its parent surface. + * + * `GdkPopup`s are typically used to implement menus and similar popups. + * They can be modal, which is indicated by the [property@GdkPopup:autohide] + * property. */ G_DEFINE_INTERFACE (GdkPopup, gdk_popup, GDK_TYPE_SURFACE) @@ -96,25 +95,26 @@ gdk_popup_default_init (GdkPopupInterface *iface) /** * gdk_popup_present: - * @popup: the #GdkPopup to show + * @popup: the `GdkPopup` to show * @width: the unconstrained popup width to layout * @height: the unconstrained popup height to layout - * @layout: the #GdkPopupLayout object used to layout + * @layout: the `GdkPopupLayout` object used to layout * * Present @popup after having processed the #GdkPopupLayout rules. + * * If the popup was previously now showing, it will be showed, * otherwise it will change position according to @layout. * * After calling this function, the result should be handled in response - * to the #GdkSurface::layout signal being emitted. The resulting popup - * position can be queried using gdk_popup_get_position_x(), - * gdk_popup_get_position_y(), and the resulting size will be sent as - * parameters in the layout signal. Use gdk_popup_get_rect_anchor() and - * gdk_popup_get_surface_anchor() to get the resulting anchors. + * to the [signal@GdkSurface::layout] signal being emitted. The resulting + * popup position can be queried using [method@Gdk.Popup.get_position_x], + * [method@Gdk.Popup.get_position_y], and the resulting size will be sent as + * parameters in the layout signal. Use [method@Gdk.Popup.get_rect_anchor] + * and [method@Gdk.Popup.get_surface_anchor] to get the resulting anchors. * * Presenting may fail, for example if the @popup is set to autohide * and is immediately hidden upon being presented. If presenting failed, - * the #GdkSurface::layout signal will not me emitted. + * the [signal@Gdk.Surface::layout] signal will not me emitted. * * Returns: %FALSE if it failed to be presented, otherwise %TRUE. */ @@ -134,12 +134,12 @@ gdk_popup_present (GdkPopup *popup, /** * gdk_popup_get_surface_anchor: - * @popup: a #GdkPopup + * @popup: a `GdkPopup` * * Gets the current popup surface anchor. * - * The value returned may change after calling gdk_popup_present(), - * or after the #GdkSurface::layout signal is emitted. + * The value returned may change after calling [method@Gdk.Popup.present], + * or after the [signal@Gdk.Surface::layout] signal is emitted. * * Returns: the current surface anchor value of @popup */ @@ -153,12 +153,12 @@ gdk_popup_get_surface_anchor (GdkPopup *popup) /** * gdk_popup_get_rect_anchor: - * @popup: a #GdkPopup + * @popup: a `GdkPopup` * * Gets the current popup rectangle anchor. * - * The value returned may change after calling gdk_popup_present(), - * or after the #GdkSurface::layout signal is emitted. + * The value returned may change after calling [method@Gdk.Popup.present], + * or after the [signal@Gdk.Surface::layout] signal is emitted. * * Returns: the current rectangle anchor value of @popup */ @@ -172,7 +172,7 @@ gdk_popup_get_rect_anchor (GdkPopup *popup) /** * gdk_popup_get_parent: - * @popup: a #GdkPopup + * @popup: a `GdkPopup` * * Returns the parent surface of a popup. * @@ -195,7 +195,7 @@ gdk_popup_get_parent (GdkPopup *popup) /** * gdk_popup_get_position_x: - * @popup: a #GdkPopup + * @popup: a `GdkPopup` * * Obtains the position of the popup relative to its parent. * @@ -211,7 +211,7 @@ gdk_popup_get_position_x (GdkPopup *popup) /** * gdk_popup_get_position_y: - * @popup: a #GdkPopup + * @popup: a `GdkPopup` * * Obtains the position of the popup relative to its parent. * @@ -227,7 +227,7 @@ gdk_popup_get_position_y (GdkPopup *popup) /** * gdk_popup_get_autohide: - * @popup: a #GdkPopup + * @popup: a `GdkPopup` * * Returns whether this popup is set to hide on outside clicks. * @@ -249,7 +249,18 @@ guint gdk_popup_install_properties (GObjectClass *object_class, guint first_prop) { + /** + * GdkToplevel:parent: + * + * The parent surface of the toplevel. + */ g_object_class_override_property (object_class, first_prop + GDK_POPUP_PROP_PARENT, "parent"); + + /** + * GdkToplevel:autohide: + * + * Whether the toplevel should be modal with respect to its parent. + */ g_object_class_override_property (object_class, first_prop + GDK_POPUP_PROP_AUTOHIDE, "autohide"); return GDK_POPUP_NUM_PROPERTIES; diff --git a/gdk/gdkpopup.h b/gdk/gdkpopup.h index 361d4bac03..ba8a2782a7 100644 --- a/gdk/gdkpopup.h +++ b/gdk/gdkpopup.h @@ -31,11 +31,6 @@ G_BEGIN_DECLS #define GDK_TYPE_POPUP (gdk_popup_get_type ()) -/** - * GdkPopup: - * - * Interface for popup surfaces. - */ GDK_AVAILABLE_IN_ALL G_DECLARE_INTERFACE (GdkPopup, gdk_popup, GDK, POPUP, GObject) diff --git a/gdk/gdkpopuplayout.c b/gdk/gdkpopuplayout.c index 686a2cbafe..ccf815d0f1 100644 --- a/gdk/gdkpopuplayout.c +++ b/gdk/gdkpopuplayout.c @@ -23,13 +23,10 @@ #include "gdksurface.h" /** - * SECTION:gdkpopuplayout - * @Title: GdkPopupLayout - * @Short_description: Information for presenting popups + * GdkPopupLayout: * - * Popups are positioned relative to their parent surface. - * The GdkPopupLayout struct contains information that is - * necessary to do so. + * The `GdkPopupLayout` struct contains information that is + * necessary position a `GdkPopup` relaive to its parent. * * The positioning requires a negotiation with the windowing system, * since it depends on external constraints, such as the position of @@ -55,12 +52,12 @@ * * Ultimatively, it is up to the windowing system to determine the position * and size of the popup. You can learn about the result by calling - * gdk_popup_get_position_x(), gdk_popup_get_position_y(), - * gdk_popup_get_rect_anchor() and gdk_popup_get_surface_anchor() after the - * popup has been presented. This can be used to adjust the rendering. For - * example, GtkPopover changes its arrow position accordingly. But you have - * to be careful avoid changing the size of the popover, or it has to be - * presented again. + * [method@Gdk.Popup.get_position_x], [method@Gdk.Popup.get_position_y], + * [method@Gdk.Popup.get_rect_anchor] and [method@Gdk.Popup.get_surface_anchor] + * after the popup has been presented. This can be used to adjust the rendering. + * For example, [class@Gtk.Popover] changes its arrow position accordingly. + * But you have to be careful avoid changing the size of the popover, or it + * has to be presented again. */ struct _GdkPopupLayout @@ -86,22 +83,24 @@ G_DEFINE_BOXED_TYPE (GdkPopupLayout, gdk_popup_layout, /** * gdk_popup_layout_new: (constructor) - * @anchor_rect: (not nullable): the anchor #GdkRectangle to align @surface with + * @anchor_rect: (not nullable): the anchor `GdkRectangle` to align @surface with * @rect_anchor: the point on @anchor_rect to align with @surface's anchor point * @surface_anchor: the point on @surface to align with @rect's anchor point * - * Create a popup layout description. Used together with gdk_popup_present() - * to describe how a popup surface should be placed and behave on-screen. + * Create a popup layout description. + * + * Used together with [method@Gdk.Popup.present] to describe how a popup + * surface should be placed and behave on-screen. * * @anchor_rect is relative to the top-left corner of the surface's parent. * @rect_anchor and @surface_anchor determine anchor points on @anchor_rect * and surface to pin together. * * The position of @anchor_rect's anchor point can optionally be offset using - * gdk_popup_layout_set_offset(), which is equivalent to offsetting the + * [method@Gdk.PopupLayout.set_offset], which is equivalent to offsetting the * position of surface. * - * Returns: (transfer full): newly created instance of #GdkPopupLayout + * Returns: (transfer full): newly created instance of `GdkPopupLayout` */ GdkPopupLayout * gdk_popup_layout_new (const GdkRectangle *anchor_rect, @@ -121,7 +120,7 @@ gdk_popup_layout_new (const GdkRectangle *anchor_rect, /** * gdk_popup_layout_ref: - * @layout: a #GdkPopupLayout + * @layout: a `GdkPopupLayout` * * Increases the reference count of @value. * @@ -136,7 +135,7 @@ gdk_popup_layout_ref (GdkPopupLayout *layout) /** * gdk_popup_layout_unref: - * @layout: a #GdkPopupLayout + * @layout: a `GdkPopupLayout` * * Decreases the reference count of @value. */ @@ -149,9 +148,9 @@ gdk_popup_layout_unref (GdkPopupLayout *layout) /** * gdk_popup_layout_copy: - * @layout: a #GdkPopupLayout + * @layout: a `GdkPopupLayout` * - * Create a new #GdkPopupLayout and copy the contents of @layout into it. + * Makes a copy of @layout. * * Returns: (transfer full): a copy of @layout. */ @@ -179,13 +178,13 @@ gdk_popup_layout_copy (GdkPopupLayout *layout) /** * gdk_popup_layout_equal: - * @layout: a #GdkPopupLayout - * @other: another #GdkPopupLayout + * @layout: a `GdkPopupLayout` + * @other: another `GdkPopupLayout` * * Check whether @layout and @other has identical layout properties. * * Returns: %TRUE if @layout and @other have identical layout properties, - * otherwise %FALSE. + * otherwise %FALSE. */ gboolean gdk_popup_layout_equal (GdkPopupLayout *layout, @@ -208,7 +207,7 @@ gdk_popup_layout_equal (GdkPopupLayout *layout, /** * gdk_popup_layout_set_anchor_rect: - * @layout: a #GdkPopupLayout + * @layout: a `GdkPopupLayout` * @anchor_rect: the new anchor rectangle * * Set the anchor rectangle. @@ -222,11 +221,11 @@ gdk_popup_layout_set_anchor_rect (GdkPopupLayout *layout, /** * gdk_popup_layout_get_anchor_rect: - * @layout: a #GdkPopupLayout + * @layout: a `GdkPopupLayout` * * Get the anchor rectangle. * - * Returns: The anchor rectangle. + * Returns: The anchor rectangle */ const GdkRectangle * gdk_popup_layout_get_anchor_rect (GdkPopupLayout *layout) @@ -236,7 +235,7 @@ gdk_popup_layout_get_anchor_rect (GdkPopupLayout *layout) /** * gdk_popup_layout_set_rect_anchor: - * @layout: a #GdkPopupLayout + * @layout: a `GdkPopupLayout` * @anchor: the new rect anchor * * Set the anchor on the anchor rectangle. @@ -250,7 +249,7 @@ gdk_popup_layout_set_rect_anchor (GdkPopupLayout *layout, /** * gdk_popup_layout_get_rect_anchor: - * @layout: a #GdkPopupLayout + * @layout: a `GdkPopupLayout` * * Returns the anchor position on the anchor rectangle. * @@ -264,7 +263,7 @@ gdk_popup_layout_get_rect_anchor (GdkPopupLayout *layout) /** * gdk_popup_layout_set_surface_anchor: - * @layout: a #GdkPopupLayout + * @layout: a `GdkPopupLayout` * @anchor: the new popup surface anchor * * Set the anchor on the popup surface. @@ -278,7 +277,7 @@ gdk_popup_layout_set_surface_anchor (GdkPopupLayout *layout, /** * gdk_popup_layout_get_surface_anchor: - * @layout: a #GdkPopupLayout + * @layout: a `GdkPopupLayout` * * Returns the anchor position on the popup surface. * @@ -292,15 +291,16 @@ gdk_popup_layout_get_surface_anchor (GdkPopupLayout *layout) /** * gdk_popup_layout_set_anchor_hints: - * @layout: a #GdkPopupLayout - * @anchor_hints: the new #GdkAnchorHints + * @layout: a `GdkPopupLayout` + * @anchor_hints: the new `GdkAnchorHints` * * Set new anchor hints. * - * The set @anchor_hints determines how @surface will be moved if the anchor - * points cause it to move off-screen. For example, %GDK_ANCHOR_FLIP_X will - * replace %GDK_GRAVITY_NORTH_WEST with %GDK_GRAVITY_NORTH_EAST and vice versa - * if @surface extends beyond the left or right edges of the monitor. + * The set @anchor_hints determines how @surface will be moved + * if the anchor points cause it to move off-screen. For example, + * %GDK_ANCHOR_FLIP_X will replace %GDK_GRAVITY_NORTH_WEST with + * %GDK_GRAVITY_NORTH_EAST and vice versa if @surface extends + * beyond the left or right edges of the monitor. */ void gdk_popup_layout_set_anchor_hints (GdkPopupLayout *layout, @@ -311,11 +311,11 @@ gdk_popup_layout_set_anchor_hints (GdkPopupLayout *layout, /** * gdk_popup_layout_get_anchor_hints: - * @layout: a #GdkPopupLayout + * @layout: a `GdkPopupLayout` * - * Get the #GdkAnchorHints. + * Get the `GdkAnchorHints`. * - * Returns: the #GdkAnchorHints. + * Returns: the `GdkAnchorHints` */ GdkAnchorHints gdk_popup_layout_get_anchor_hints (GdkPopupLayout *layout) @@ -325,7 +325,7 @@ gdk_popup_layout_get_anchor_hints (GdkPopupLayout *layout) /** * gdk_popup_layout_set_offset: - * @layout: a #GdkPopupLayout + * @layout: a `GdkPopupLayout` * @dx: x delta to offset the anchor rectangle with * @dy: y delta to offset the anchor rectangle with * @@ -342,7 +342,7 @@ gdk_popup_layout_set_offset (GdkPopupLayout *layout, /** * gdk_popup_layout_get_offset: - * @layout: a #GdkPopupLayout + * @layout: a `GdkPopupLayout` * @dx: (out): return location for the delta X coordinate * @dy: (out): return location for the delta Y coordinate * @@ -361,15 +361,17 @@ gdk_popup_layout_get_offset (GdkPopupLayout *layout, /** * gdk_popup_layout_set_shadow_width: - * @layout: a #GdkPopupLayout + * @layout: a `GdkPopupLayout` * @left: width of the left part of the shadow * @right: width of the right part of the shadow * @top: height of the top part of the shadow * @bottom: height of the bottom part of the shadow * - * The shadow width corresponds to the part of the computed surface size - * that would consist of the shadow margin surrounding the window, would - * there be any. + * Sets the shadow width of the popup. + * + * The shadow width corresponds to the part of the computed + * surface size that would consist of the shadow margin + * surrounding the window, would there be any. * * Since: 4.2 */ @@ -388,7 +390,7 @@ gdk_popup_layout_set_shadow_width (GdkPopupLayout *layout, /** * gdk_popup_layout_get_shadow_width: - * @layout: a #GdkPopupLayout + * @layout: a `GdkPopupLayout` * @left: (out): return location for the left shadow width * @right: (out): return location for the right shadow width * @top: (out): return location for the top shadow width diff --git a/gdk/gdkrectangle.c b/gdk/gdkrectangle.c index 83b77429cf..3db6292bfe 100644 --- a/gdk/gdkrectangle.c +++ b/gdk/gdkrectangle.c @@ -29,15 +29,17 @@ /** - * SECTION:gdkregion - * @Short_description: Simple graphical data type - * @Title: GdkRectangle + * GdkRectangle: + * @x: the x coordinate of the top left corner + * @y: the y coordinate of the top left corner + * @width: the width of the rectangle + * @height: the height of the rectangle * - * 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` data type for representing rectangles. * - * A #GdkRectangle represents the position and size of a rectangle. + * `GdkRectangle` is identical to `cairo_rectangle_t`. Together with Cairo’s + * `cairo_region_t` data type, these are the central types for representing + * sets of pixels. * * The intersection of two rectangles can be computed with * [method@Gdk.Rectangle.intersect]; to find the union of two rectangles use @@ -53,14 +55,15 @@ /** * gdk_rectangle_union: - * @src1: a #GdkRectangle - * @src2: a #GdkRectangle + * @src1: a `GdkRectangle` + * @src2: a `GdkRectangle` * @dest: (out): return location for the union of @src1 and @src2 * * Calculates the union of two rectangles. + * * The union of rectangles @src1 and @src2 is the smallest rectangle which - * includes both @src1 and @src2 within it. - * It is allowed for @dest to be the same as either @src1 or @src2. + * includes both @src1 and @src2 within it. It is allowed for @dest to be + * the same as either @src1 or @src2. * * Note that this function does not ignore 'empty' rectangles (ie. with * zero width or height). @@ -86,17 +89,18 @@ gdk_rectangle_union (const GdkRectangle *src1, /** * gdk_rectangle_intersect: - * @src1: a #GdkRectangle - * @src2: a #GdkRectangle + * @src1: a `GdkRectangle` + * @src2: a `GdkRectangle` * @dest: (out caller-allocates) (allow-none): return location for the - * intersection of @src1 and @src2, or %NULL + * intersection of @src1 and @src2, or %NULL * - * Calculates the intersection of two rectangles. It is allowed for - * @dest to be the same as either @src1 or @src2. If the rectangles - * do not intersect, @dest’s width and height is set to 0 and its x - * and y values are undefined. If you are only interested in whether - * the rectangles intersect, but not in the intersecting area itself, - * pass %NULL for @dest. + * Calculates the intersection of two rectangles. + * + * It is allowed for @dest to be the same as either @src1 or @src2. + * If the rectangles do not intersect, @dest’s width and height is set + * to 0 and its x and y values are undefined. If you are only interested + * in whether the rectangles intersect, but not in the intersecting area + * itself, pass %NULL for @dest. * * Returns: %TRUE if the rectangles intersect. */ @@ -141,7 +145,7 @@ gdk_rectangle_intersect (const GdkRectangle *src1, /** * gdk_rectangle_contains_point: - * @rect: a #GdkRectangle + * @rect: a `GdkRectangle` * @x: X coordinate * @y: Y coordinate * @@ -164,8 +168,8 @@ gdk_rectangle_contains_point (const GdkRectangle *rect, /** * gdk_rectangle_equal: - * @rect1: a #GdkRectangle - * @rect2: a #GdkRectangle + * @rect1: a `GdkRectangle` + * @rect2: a `GdkRectangle` * * Checks if the two given rectangles are equal. * diff --git a/gdk/gdkrgba.c b/gdk/gdkrgba.c index a2525591c9..3632147b7f 100644 --- a/gdk/gdkrgba.c +++ b/gdk/gdkrgba.c @@ -30,18 +30,6 @@ #include #include -/** - * SECTION:gdkrgba - * @Title: GdkRGBA - * @Short_description: RGBA colors - * - * #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 - * (1.0, 1.0, 1.0, 1.0) is opaque white. Other values will be clamped - * to this range when drawing. - */ G_DEFINE_BOXED_TYPE (GdkRGBA, gdk_rgba, gdk_rgba_copy, gdk_rgba_free) @@ -54,19 +42,26 @@ G_DEFINE_BOXED_TYPE (GdkRGBA, gdk_rgba, * @alpha: The opacity of the color from 0.0 for completely translucent to * 1.0 for opaque * - * A #GdkRGBA is used to represent a (possibly translucent) - * color, in a way that is compatible with cairo’s notion of color. + * A `GdkRGBA` is used to represent a color, in a way that is compatible + * with cairo’s notion of color. + * + * `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 + * (1.0, 1.0, 1.0, 1.0) is opaque white. Other values will + * be clamped to this range when drawing. */ /** * gdk_rgba_copy: - * @rgba: a #GdkRGBA + * @rgba: a `GdkRGBA` * - * Makes a copy of a #GdkRGBA. + * Makes a copy of a `GdkRGBA`. * - * The result must be freed through gdk_rgba_free(). + * The result must be freed through [method@Gdk.RGBA.free]. * - * Returns: A newly allocated #GdkRGBA, with the same contents as @rgba + * Returns: A newly allocated `GdkRGBA`, with the same contents as @rgba */ GdkRGBA * gdk_rgba_copy (const GdkRGBA *rgba) @@ -76,9 +71,9 @@ gdk_rgba_copy (const GdkRGBA *rgba) /** * gdk_rgba_free: - * @rgba: a #GdkRGBA + * @rgba: a `GdkRGBA` * - * Frees a #GdkRGBA created with gdk_rgba_copy() + * Frees a `GdkRGBA`. */ void gdk_rgba_free (GdkRGBA *rgba) @@ -88,10 +83,11 @@ gdk_rgba_free (GdkRGBA *rgba) /** * gdk_rgba_is_clear: - * @rgba: a #GdkRGBA + * @rgba: a `GdkRGBA` * - * Checks if an @rgba value is transparent. That is, drawing with the value - * would not produce any change. + * Checks if an @rgba value is transparent. + * + * That is, drawing with the value would not produce any change. * * Returns: %TRUE if the @rgba is clear */ @@ -103,10 +99,12 @@ gdk_rgba_is_clear (const GdkRGBA *rgba) /** * gdk_rgba_is_opaque: - * @rgba: a #GdkRGBA + * @rgba: a `GdkRGBA` * - * Checks if an @rgba value is opaque. That is, drawing with the value - * will not retain any results from previous contents. + * Checks if an @rgba value is opaque. + * + * That is, drawing with the value will not retain any results + * from previous contents. * * Returns: %TRUE if the @rgba is opaque */ @@ -160,26 +158,27 @@ parse_rgb_value (const char *str, /** * gdk_rgba_parse: - * @rgba: the #GdkRGBA to fill in + * @rgba: the `GdkRGBA` to fill in * @spec: the string specifying the color * - * Parses a textual representation of a color, filling in - * the @red, @green, @blue and @alpha fields of the @rgba #GdkRGBA. + * Parses a textual representation of a color. * * The string can be either one of: + * * - A standard name (Taken from the X11 rgb.txt file). * - A hexadecimal value in the form “\#rgb”, “\#rrggbb”, * “\#rrrgggbbb” or ”\#rrrrggggbbbb” * - A hexadecimal value in the form “\#rgba”, “\#rrggbbaa”, * or ”\#rrrrggggbbbbaaaa” - * - A RGB color in the form “rgb(r,g,b)” (In this case the color will - * have full opacity) + * - A RGB color in the form “rgb(r,g,b)” (In this case the color + * will have full opacity) * - A RGBA color in the form “rgba(r,g,b,a)” * - * Where “r”, “g”, “b” and “a” are respectively the red, green, blue and - * alpha color values. In the last two cases, “r”, “g”, and “b” are either - * integers in the range 0 to 255 or percentage values in the range 0% to - * 100%, and a is a floating point value in the range 0 to 1. + * Where “r”, “g”, “b” and “a” are respectively the red, green, + * blue and alpha color values. In the last two cases, “r”, “g”, + * and “b” are either integers in the range 0 to 255 or percentage + * values in the range 0% to 100%, and a is a floating point value + * in the range 0 to 1. * * Returns: %TRUE if the parsing succeeded */ @@ -306,10 +305,10 @@ gdk_rgba_parse (GdkRGBA *rgba, /** * gdk_rgba_hash: - * @p: (type GdkRGBA): a #GdkRGBA pointer + * @p: (type GdkRGBA): a `GdkRGBA` * * A hash function suitable for using for a hash - * table that stores #GdkRGBAs. + * table that stores `GdkRGBA`s. * * Returns: The hash value for @p */ @@ -326,10 +325,10 @@ gdk_rgba_hash (gconstpointer p) /** * gdk_rgba_equal: - * @p1: (type GdkRGBA): a #GdkRGBA pointer - * @p2: (type GdkRGBA): another #GdkRGBA pointer + * @p1: (type GdkRGBA): a `GdkRGBA` + * @p2: (type GdkRGBA): another `GdkRGBA` * - * Compares two RGBA colors. + * Compares two `GdkRGBA` colors. * * Returns: %TRUE if the two colors compare equal */ @@ -353,23 +352,21 @@ gdk_rgba_equal (gconstpointer p1, /** * gdk_rgba_to_string: - * @rgba: a #GdkRGBA + * @rgba: a `GdkRGBA` * * Returns a textual specification of @rgba in the form - * `rgb(r,g,b)` or - * `rgba(r,g,b,a)`, - * where “r”, “g”, “b” and “a” represent the red, green, - * blue and alpha values respectively. “r”, “g”, and “b” are - * represented as integers in the range 0 to 255, and “a” - * is represented as a floating point value in the range 0 to 1. + * `rgb(r,g,b)` or `rgba(r,g,b,a)`, where “r”, “g”, “b” and + * “a” represent the red, green, blue and alpha values + * respectively. “r”, “g”, and “b” are represented as integers + * in the range 0 to 255, and “a” is represented as a floating + * point value in the range 0 to 1. * * These string forms are string forms that are supported by - * the CSS3 colors module, and can be parsed by gdk_rgba_parse(). + * the CSS3 colors module, and can be parsed by [method@Gdk.RGBA.parse]. * - * Note that this string representation may lose some - * precision, since “r”, “g” and “b” are represented as 8-bit - * integers. If this is a concern, you should use a - * different representation. + * Note that this string representation may lose some precision, + * since “r”, “g” and “b” are represented as 8-bit integers. If + * this is a concern, you should use a different representation. * * Returns: A newly allocated text string */ @@ -578,4 +575,3 @@ gdk_rgba_parser_parse (GtkCssParser *parser, return FALSE; } } - diff --git a/gdk/gdkseat.c b/gdk/gdkseat.c index 83af3b88a4..397dc9ff4b 100644 --- a/gdk/gdkseat.c +++ b/gdk/gdkseat.c @@ -28,21 +28,11 @@ #include "gdkintl.h" #include "gdkinternals.h" -/** - * SECTION:gdkseat - * @Short_description: Object representing a user seat - * @Title: GdkSeat - * @See_also: #GdkDisplay, #GdkDevice - * - * The #GdkSeat object represents a collection of input devices - * that belong to a user. - */ - /** * GdkSeat: * - * The GdkSeat struct contains only private fields and - * should not be accessed directly. + * The `GdkSeat` object represents a collection of input devices + * that belong to a user. */ typedef struct _GdkSeatPrivate GdkSeatPrivate; @@ -120,10 +110,9 @@ gdk_seat_class_init (GdkSeatClass *klass) /** * GdkSeat::device-added: * @seat: the object on which the signal is emitted - * @device: the newly added #GdkDevice. + * @device: the newly added `GdkDevice`. * - * The ::device-added signal is emitted when a new input - * device is related to this seat. + * Emitted when a new input device is related to this seat. */ signals [DEVICE_ADDED] = g_signal_new (g_intern_static_string ("device-added"), @@ -138,10 +127,9 @@ gdk_seat_class_init (GdkSeatClass *klass) /** * GdkSeat::device-removed: * @seat: the object on which the signal is emitted - * @device: the just removed #GdkDevice. + * @device: the just removed `GdkDevice`. * - * The ::device-removed signal is emitted when an - * input device is removed (e.g. unplugged). + * Emitted when an input device is removed (e.g. unplugged). */ signals [DEVICE_REMOVED] = g_signal_new (g_intern_static_string ("device-removed"), @@ -156,12 +144,13 @@ gdk_seat_class_init (GdkSeatClass *klass) /** * GdkSeat::tool-added: * @seat: the object on which the signal is emitted - * @tool: the new #GdkDeviceTool known to the seat + * @tool: the new `GdkDeviceTool` known to the seat * - * The ::tool-added signal is emitted whenever a new tool - * is made known to the seat. The tool may later be assigned - * to a device (i.e. on proximity with a tablet). The device - * will emit the #GdkDevice::tool-changed signal accordingly. + * Emitted whenever a new tool is made known to the seat. + * + * The tool may later be assigned to a device (i.e. on + * proximity with a tablet). The device will emit the + * [signalGdkDevice::tool-changed] signal accordingly. * * A same tool may be used by several devices. */ @@ -177,10 +166,9 @@ gdk_seat_class_init (GdkSeatClass *klass) /** * GdkSeat::tool-removed: * @seat: the object on which the signal is emitted - * @tool: the just removed #GdkDeviceTool + * @tool: the just removed `GdkDeviceTool` * - * This signal is emitted whenever a tool is no longer known - * to this @seat. + * Emitted whenever a tool is no longer known to this @seat. */ signals [TOOL_REMOVED] = g_signal_new (g_intern_static_string ("tool-removed"), @@ -194,7 +182,7 @@ gdk_seat_class_init (GdkSeatClass *klass) /** * GdkSeat:display: * - * #GdkDisplay of this seat. + * `GdkDisplay` of this seat. */ props[PROP_DISPLAY] = g_param_spec_object ("display", @@ -215,12 +203,12 @@ gdk_seat_init (GdkSeat *seat) /** * gdk_seat_get_capabilities: - * @seat: a #GdkSeat + * @seat: a `GdkSeat` * - * Returns the capabilities this #GdkSeat currently has. + * Returns the capabilities this `GdkSeat` currently has. * * Returns: the seat capabilities - **/ + */ GdkSeatCapabilities gdk_seat_get_capabilities (GdkSeat *seat) { @@ -234,30 +222,30 @@ gdk_seat_get_capabilities (GdkSeat *seat) /* * gdk_seat_grab: - * @seat: a #GdkSeat - * @surface: the #GdkSurface which will own the grab + * @seat: a `GdkSeat` + * @surface: the `GdkSurface` which will own the grab * @capabilities: capabilities that will be grabbed * @owner_events: if %FALSE then all device events are reported with respect to - * @surface and are only reported if selected by @event_mask. If - * %TRUE then pointer events for this application are reported - * as normal, but pointer events outside this application are - * reported with respect to @surface and only if selected by - * @event_mask. In either mode, unreported events are discarded. - * @cursor: (nullable): the cursor to display while the grab is active. If - * this is %NULL then the normal cursors are used for - * @surface and its descendants, and the cursor for @surface is used - * elsewhere. + * @surface and are only reported if selected by @event_mask. If %TRUE then + * pointer events for this application are reported as normal, but pointer + * events outside this application are reported with respect to @surface and + * only if selected by @event_mask. In either mode, unreported events are + * discarded. + * @cursor: (nullable): the cursor to display while the grab is active. + * If this is %NULL then the normal cursors are used for @surface and + * its descendants, and the cursor for @surface is used elsewhere. * @event: (nullable): the event that is triggering the grab, or %NULL if none - * is available. - * @prepare_func: (nullable) (scope call): function to - * prepare the surface to be grabbed, it can be %NULL if @surface is - * visible before this call. + * is available. + * @prepare_func: (nullable) (scope call): function to prepare the surface + * to be grabbed, it can be %NULL if @surface is visible before this call. * @prepare_func_data: (closure): user data to pass to @prepare_func * * Grabs the seat so that all events corresponding to the given @capabilities - * are passed to this application until the seat is ungrabbed with gdk_seat_ungrab(), - * or the surface becomes hidden. This overrides any previous grab on the - * seat by this client. + * are passed to this application. + * + * The grab remains in place until the seat is ungrabbed with + * [method@Gdk.Seat.ungrab], or the surface becomes hidden. This overrides + * any previous grab on the seat by this client. * * As a rule of thumb, if a grab is desired over %GDK_SEAT_CAPABILITY_POINTER, * all other "pointing" capabilities (eg. %GDK_SEAT_CAPABILITY_TOUCH) should @@ -269,18 +257,18 @@ gdk_seat_get_capabilities (GdkSeat *seat) * events corresponding to the given capabilities. For example in GTK this * is used for Drag and Drop operations, popup menus and such. * - * Note that if the event mask of a #GdkSurface has selected both button press + * Note that if the event mask of a `GdkSurface` has selected both button press * and button release events, or touch begin and touch end, then a press event * will cause an automatic grab until the button is released, equivalent to a - * grab on the surface with @owner_events set to %TRUE. This is done because most - * applications expect to receive paired press and release events. + * grab on the surface with @owner_events set to %TRUE. This is done because + * most applications expect to receive paired press and release events. * * If you set up anything at the time you take the grab that needs to be - * cleaned up when the grab ends, you should handle the #GdkEventGrabBroken + * cleaned up when the grab ends, you should handle the `GdkEventGrabBroken` * events that are emitted when the grab ends unvoluntarily. * * Returns: %GDK_GRAB_SUCCESS if the grab was successful. - **/ + */ GdkGrabStatus gdk_seat_grab (GdkSeat *seat, GdkSurface *surface, @@ -308,10 +296,12 @@ gdk_seat_grab (GdkSeat *seat, /* * gdk_seat_ungrab: - * @seat: a #GdkSeat + * @seat: a `GdkSeat` * - * Releases a grab added through gdk_seat_grab(). - **/ + * Releases a grab. + * + * See [method@Gdk.Seat.grab] for more information. + */ void gdk_seat_ungrab (GdkSeat *seat) { @@ -330,10 +320,10 @@ gdk_seat_ungrab (GdkSeat *seat) * * Returns the devices that match the given capabilities. * - * Returns: (transfer container) (element-type GdkDevice): A list of #GdkDevices. - * The list must be freed with g_list_free(), the elements are owned - * by GTK and must not be freed. - **/ + * Returns: (transfer container) (element-type GdkDevice): A list + * of `GdkDevices`. The list must be freed with g_list_free(), + * the elements are owned by GTK and must not be freed. + */ GList * gdk_seat_get_devices (GdkSeat *seat, GdkSeatCapabilities capabilities) @@ -348,13 +338,13 @@ gdk_seat_get_devices (GdkSeat *seat, /** * gdk_seat_get_pointer: - * @seat: a #GdkSeat + * @seat: a `GdkSeat` * * Returns the device that routes pointer events. * - * Returns: (transfer none) (nullable): a #GdkDevice with pointer - * capabilities. This object is owned by GTK and must not be freed. - **/ + * Returns: (transfer none) (nullable): a `GdkDevice` with pointer + * capabilities. This object is owned by GTK and must not be freed. + */ GdkDevice * gdk_seat_get_pointer (GdkSeat *seat) { @@ -368,13 +358,13 @@ gdk_seat_get_pointer (GdkSeat *seat) /** * gdk_seat_get_keyboard: - * @seat: a #GdkSeat + * @seat: a `GdkSeat` * * Returns the device that routes keyboard events. * - * Returns: (transfer none) (nullable): a #GdkDevice with keyboard - * capabilities. This object is owned by GTK and must not be freed. - **/ + * Returns: (transfer none) (nullable): a `GdkDevice` with keyboard + * capabilities. This object is owned by GTK and must not be freed. + */ GdkDevice * gdk_seat_get_keyboard (GdkSeat *seat) { @@ -404,13 +394,13 @@ gdk_seat_device_removed (GdkSeat *seat, /** * gdk_seat_get_display: - * @seat: a #GdkSeat + * @seat: a `GdkSeat` * - * Returns the #GdkDisplay this seat belongs to. + * Returns the `GdkDisplay` this seat belongs to. * - * Returns: (transfer none): a #GdkDisplay. This object is owned by GTK - * and must not be freed. - **/ + * Returns: (transfer none): a `GdkDisplay`. This object + * is owned by GTK and must not be freed. + */ GdkDisplay * gdk_seat_get_display (GdkSeat *seat) { @@ -464,14 +454,13 @@ gdk_seat_get_tool (GdkSeat *seat, /** * gdk_seat_get_tools: - * @seat: A #GdkSeat + * @seat: a `GdkSeat` * - * Returns all #GdkDeviceTools that are known to the - * application. + * Returns all `GdkDeviceTools` that are known to the application. * * Returns: (transfer container) (element-type Gdk.DeviceTool): - * A list of tools. Free with g_list_free(). - **/ + * A list of tools. Free with g_list_free(). + */ GList * gdk_seat_get_tools (GdkSeat *seat) { diff --git a/gdk/gdksnapshot.c b/gdk/gdksnapshot.c index 1589428e5e..ae6b9fbc4c 100644 --- a/gdk/gdksnapshot.c +++ b/gdk/gdksnapshot.c @@ -21,6 +21,14 @@ #include "gdksnapshotprivate.h" +/** + * GdkSnapshot: + * + * Base type for snapshot operations. + * + * The subclass of `GdkSnapshot` used by GTK is [class@Gtk.Snapshot]. + */ + G_DEFINE_ABSTRACT_TYPE (GdkSnapshot, gdk_snapshot, G_TYPE_OBJECT) static void diff --git a/gdk/gdksnapshot.h b/gdk/gdksnapshot.h index c2b4ce2e1c..e609ea3807 100644 --- a/gdk/gdksnapshot.h +++ b/gdk/gdksnapshot.h @@ -29,11 +29,6 @@ G_BEGIN_DECLS -/** - * GdkSnapshot: - * - * Base type for snapshot operations. - */ typedef struct _GdkSnapshotClass GdkSnapshotClass; diff --git a/gdk/gdksurface.c b/gdk/gdksurface.c index 31c5b44b73..c04a2e7eef 100644 --- a/gdk/gdksurface.c +++ b/gdk/gdksurface.c @@ -51,28 +51,18 @@ #include "wayland/gdkwayland.h" #endif -/** - * 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 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. - */ - /** * GdkSurface: * - * The GdkSurface struct contains only private fields and - * should not be accessed directly. + * A `GdkSurface` is a rectangular region on the screen. + * + * It’s a low-level object, used to implement high-level objects + * such as [class@Gtk.Window] or [class@Gtk.Dialog] in GTK. + * + * The surfaces you see in practice are either [class@Gdk.Toplevel] or + * [class@Gdk.Popup], 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. */ enum { @@ -501,8 +491,10 @@ gdk_surface_class_init (GdkSurfaceClass *klass) /** * GdkSurface:cursor: * - * The mouse pointer for a #GdkSurface. See gdk_surface_set_cursor() and - * gdk_surface_get_cursor() for details. + * The mouse pointer for the `GdkSurface`. + * + * See [method@Gdk.Surface.set_cursor] and + * [method@Gdk.Surface.get_cursor] for details. */ properties[PROP_CURSOR] = g_param_spec_object ("cursor", @@ -514,8 +506,9 @@ gdk_surface_class_init (GdkSurfaceClass *klass) /** * GdkSurface:display: * - * The #GdkDisplay connection of the surface. See gdk_surface_get_display() - * for details. + * The `GdkDisplay` connection of the surface. + * + * See [method@Gdk.Surface.get_display] for details. */ properties[PROP_DISPLAY] = g_param_spec_object ("display", @@ -524,6 +517,11 @@ gdk_surface_class_init (GdkSurfaceClass *klass) GDK_TYPE_DISPLAY, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS); + /** + * GdkSurface:frame-clock: + * + * The `GdkFrameClock` of the surface. + */ properties[PROP_FRAME_CLOCK] = g_param_spec_object ("frame-clock", P_("Frame Clock"), @@ -531,6 +529,11 @@ gdk_surface_class_init (GdkSurfaceClass *klass) GDK_TYPE_FRAME_CLOCK, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS); + /** + * GdkSurface:mapped: + * + * Whether the surface is mapped. + */ properties[PROP_MAPPED] = g_param_spec_boolean ("mapped", P_("Mapped"), @@ -538,6 +541,11 @@ gdk_surface_class_init (GdkSurfaceClass *klass) FALSE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + /** + * GdkSurface:width: + * + * The width of the surface in pixels. + */ properties[PROP_WIDTH] = g_param_spec_int ("width", P_("Width"), @@ -545,6 +553,11 @@ gdk_surface_class_init (GdkSurfaceClass *klass) 0, G_MAXINT, 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + /** + * GdkSurface:height: + * + * The height of the surface, in pixels. + */ properties[PROP_HEIGHT] = g_param_spec_int ("height", P_("Height"), @@ -552,6 +565,11 @@ gdk_surface_class_init (GdkSurfaceClass *klass) 0, G_MAXINT, 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + /** + * GdkSurface:scale-factor: + * + * The scale factor of the surface. + */ properties[PROP_SCALE_FACTOR] = g_param_spec_int ("scale-factor", P_("Scale factor"), @@ -563,7 +581,7 @@ gdk_surface_class_init (GdkSurfaceClass *klass) /** * GdkSurface::layout: - * @surface: the #GdkSurface + * @surface: the `GdkSurface` * @width: the current width * @height: the current height * @@ -588,13 +606,13 @@ gdk_surface_class_init (GdkSurfaceClass *klass) /** * GdkSurface::render: - * @surface: the #GdkSurface + * @surface: the `GdkSurface` * @region: the region that needs to be redrawn * * Emitted when part of the surface needs to be redrawn. * * Returns: %TRUE to indicate that the signal has been handled - */ + */ signals[RENDER] = g_signal_new (g_intern_static_string ("render"), G_OBJECT_CLASS_TYPE (object_class), @@ -612,13 +630,13 @@ gdk_surface_class_init (GdkSurfaceClass *klass) /** * GdkSurface::event: - * @surface: the #GdkSurface + * @surface: the `GdkSurface` * @event: (type Gdk.Event): an input event * * Emitted when GDK receives an input event for @surface. * * Returns: %TRUE to indicate that the event has been handled - */ + */ signals[EVENT] = g_signal_new (g_intern_static_string ("event"), G_OBJECT_CLASS_TYPE (object_class), @@ -636,11 +654,11 @@ gdk_surface_class_init (GdkSurfaceClass *klass) /** * GdkSurface::enter-monitor: - * @surface: the #GdkSurface + * @surface: the `GdkSurface` * @monitor: the monitor * * Emitted when @surface starts being present on the monitor. - */ + */ signals[ENTER_MONITOR] = g_signal_new (g_intern_static_string ("enter-monitor"), G_OBJECT_CLASS_TYPE (object_class), @@ -655,11 +673,11 @@ gdk_surface_class_init (GdkSurfaceClass *klass) /** * GdkSurface::leave-monitor: - * @surface: the #GdkSurface + * @surface: the `GdkSurface` * @monitor: the monitor * * Emitted when @surface stops being present on the monitor. - */ + */ signals[LEAVE_MONITOR] = g_signal_new (g_intern_static_string ("leave-monitor"), G_OBJECT_CLASS_TYPE (object_class), @@ -833,8 +851,8 @@ gdk_surface_new (GdkDisplay *display, * * Creates a new toplevel surface. * - * Returns: (transfer full): the new #GdkSurface - **/ + * Returns: (transfer full): the new `GdkSurface` + */ GdkSurface * gdk_surface_new_toplevel (GdkDisplay *display) { @@ -852,9 +870,9 @@ gdk_surface_new_toplevel (GdkDisplay *display) * Create a new popup surface. * * The surface will be attached to @parent and can be positioned - * relative to it using gdk_popup_present(). + * relative to it using [method@Gdk.Popup.present]. * - * Returns: (transfer full): a new #GdkSurface + * Returns: (transfer full): a new `GdkSurface` */ GdkSurface * gdk_surface_new_popup (GdkSurface *parent, @@ -898,20 +916,19 @@ surface_remove_from_pointer_info (GdkSurface *surface, /** * _gdk_surface_destroy_hierarchy: - * @surface: a #GdkSurface - * @recursing_native: If %TRUE, then this is being called because a native parent - * was destroyed. This generally means that the call to the - * windowing system to destroy the surface can be omitted, since - * it will be destroyed as a result of the parent being destroyed. - * Unless @foreign_destroy. + * @surface: a `GdkSurface` + * @recursing_native: If %TRUE, then this is being called because a native + * parent was destroyed. This generally means that the call to the windowing + * system to destroy the surface can be omitted, since it will be destroyed + * as a result of the parent being destroyed. Unless @foreign_destroy. * @foreign_destroy: If %TRUE, the surface or a parent was destroyed by some - * external agency. The surface has already been destroyed and no - * windowing system calls should be made. (This may never happen - * for some windowing systems.) + * external agency. The surface has already been destroyed and no windowing + * system calls should be made. (This may never happen for some windowing + * systems.) * * Internal function to destroy a surface. Like gdk_surface_destroy(), * but does not drop the reference count created by gdk_surface_new(). - **/ + */ static void _gdk_surface_destroy_hierarchy (GdkSurface *surface, gboolean foreign_destroy) @@ -955,15 +972,15 @@ _gdk_surface_destroy_hierarchy (GdkSurface *surface, /** * _gdk_surface_destroy: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * @foreign_destroy: If %TRUE, the surface or a parent was destroyed by some - * external agency. The surface has already been destroyed and no - * windowing system calls should be made. (This may never happen - * for some windowing systems.) + * external agency. The surface has already been destroyed and no windowing + * system calls should be made. (This may never happen for some windowing + * systems.) * * Internal function to destroy a surface. Like gdk_surface_destroy(), * but does not drop the reference count created by gdk_surface_new(). - **/ + */ void _gdk_surface_destroy (GdkSurface *surface, gboolean foreign_destroy) @@ -973,16 +990,18 @@ _gdk_surface_destroy (GdkSurface *surface, /** * gdk_surface_destroy: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * - * Destroys the window system resources associated with @surface and decrements @surface's - * reference count. The window system resources for all children of @surface are also + * Destroys the window system resources associated with @surface and + * decrements @surface's reference count. + * + * The window system resources for all children of @surface are also * destroyed, but the children’s reference counts are not decremented. * - * Note that a surface will not be destroyed automatically when its reference count - * reaches zero. You must call this function yourself before that happens. - * - **/ + * Note that a surface will not be destroyed automatically when its + * reference count reaches zero. You must call this function yourself + * before that happens. + */ void gdk_surface_destroy (GdkSurface *surface) { @@ -1005,12 +1024,12 @@ gdk_surface_get_widget (GdkSurface *surface) /** * gdk_surface_get_display: - * @surface: a #GdkSurface - * - * Gets the #GdkDisplay associated with a #GdkSurface. - * - * Returns: (transfer none): the #GdkDisplay associated with @surface - **/ + * @surface: a `GdkSurface` + * + * Gets the `GdkDisplay` associated with a `GdkSurface`. + * + * Returns: (transfer none): the `GdkDisplay` associated with @surface + */ GdkDisplay * gdk_surface_get_display (GdkSurface *surface) { @@ -1020,12 +1039,12 @@ gdk_surface_get_display (GdkSurface *surface) } /** * gdk_surface_is_destroyed: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * - * Check to see if a surface is destroyed.. + * Check to see if a surface is destroyed. * * Returns: %TRUE if the surface is destroyed - **/ + */ gboolean gdk_surface_is_destroyed (GdkSurface *surface) { @@ -1034,13 +1053,15 @@ gdk_surface_is_destroyed (GdkSurface *surface) /** * gdk_surface_get_mapped: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * - * Checks whether the surface has been mapped (with gdk_toplevel_present() - * or gdk_popup_present()). + * Checks whether the surface has been mapped. + * + * A surface is mapped with [method@Gdk.Toplevel.present] + * or [method@Gdk.Popup.present]. * * Returns: %TRUE if the surface is mapped - **/ + */ gboolean gdk_surface_get_mapped (GdkSurface *surface) { @@ -1138,21 +1159,19 @@ gdk_surface_get_paint_gl_context (GdkSurface *surface, /** * gdk_surface_create_gl_context: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * @error: return location for an error * - * Creates a new #GdkGLContext matching the - * framebuffer format to the visual of the #GdkSurface. The context - * is disconnected from any particular surface or surface. + * Creates a new `GdkGLContext` for the `GdkSurface`. * - * If the creation of the #GdkGLContext failed, @error will be set. + * The context is disconnected from any particular surface or surface. + * If the creation of the `GdkGLContext` failed, @error will be set. + * Before using the returned `GdkGLContext`, you will need to + * call [method@Gdk.GLContext.make_current] or [method@Gdk.GLContext.realize]. * - * Before using the returned #GdkGLContext, you will need to - * call gdk_gl_context_make_current() or gdk_gl_context_realize(). - * - * Returns: (transfer full): the newly created #GdkGLContext, or - * %NULL on error - **/ + * Returns: (transfer full): the newly created `GdkGLContext`, + * or %NULL on error + */ GdkGLContext * gdk_surface_create_gl_context (GdkSurface *surface, GError **error) @@ -1174,12 +1193,12 @@ gdk_surface_create_gl_context (GdkSurface *surface, /** * gdk_surface_create_cairo_context: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * - * Creates a new #GdkCairoContext for rendering on @surface. + * Creates a new `GdkCairoContext` for rendering on @surface. * - * Returns: (transfer full): the newly created #GdkCairoContext - **/ + * Returns: (transfer full): the newly created `GdkCairoContext` + */ GdkCairoContext * gdk_surface_create_cairo_context (GdkSurface *surface) { @@ -1196,16 +1215,16 @@ gdk_surface_create_cairo_context (GdkSurface *surface) /** * gdk_surface_create_vulkan_context: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * @error: return location for an error * - * Creates a new #GdkVulkanContext for rendering on @surface. + * Creates a new `GdkVulkanContext` for rendering on @surface. * - * If the creation of the #GdkVulkanContext failed, @error will be set. + * If the creation of the `GdkVulkanContext` failed, @error will be set. * - * Returns: (transfer full): the newly created #GdkVulkanContext, or - * %NULL on error - **/ + * Returns: (transfer full): the newly created `GdkVulkanContext`, or + * %NULL on error + */ GdkVulkanContext * gdk_surface_create_vulkan_context (GdkSurface *surface, GError **error) @@ -1370,10 +1389,11 @@ gdk_surface_layout_on_clock (GdkFrameClock *clock, /** * gdk_surface_request_layout: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * - * Request a %GDK_FRAME_CLOCK_PHASE_LAYOUT from the surface's - * frame clock. See gdk_frame_clock_request_phase(). + * Request a layout phase from the surface's frame clock. + * + * See [method@Gdk.FrameClock.request_phase]. */ void gdk_surface_request_layout (GdkSurface *surface) @@ -1423,14 +1443,15 @@ gdk_surface_paint_on_clock (GdkFrameClock *clock, /* * gdk_surface_invalidate_rect: - * @surface: a #GdkSurface - * @rect: (allow-none): rectangle to invalidate or %NULL to invalidate the whole - * surface + * @surface: a `GdkSurface` + * @rect: (allow-none): rectangle to invalidate or %NULL to + * invalidate the whole surface * - * A convenience wrapper around gdk_surface_invalidate_region() - * which invalidates a rectangular region. - * See gdk_surface_invalidate_region() for details. - **/ + * Invalidate a rectangular region of @surface. + * + * This is a convenience wrapper around + * [method@Gdk.Surface.invalidate_region]. + */ void gdk_surface_invalidate_rect (GdkSurface *surface, const GdkRectangle *rect) @@ -1473,14 +1494,14 @@ impl_surface_add_update_area (GdkSurface *impl_surface, /** * gdk_surface_queue_render: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * - * Forces a #GdkSurface::render signal emission for @surface + * Forces a [signal@Gdk.Surface::render] signal emission for @surface * to be scheduled. * * This function is useful for implementations that track invalid * regions on their own. - **/ + */ void gdk_surface_queue_render (GdkSurface *surface) { @@ -1495,16 +1516,18 @@ gdk_surface_queue_render (GdkSurface *surface) /* * gdk_surface_invalidate_region: - * @surface: a #GdkSurface - * @region: a #cairo_region_t + * @surface: a `GdkSurface` + * @region: a `cairo_region_t` * - * Adds @region to the update area for @surface. The update area is - * the region that needs to be redrawn, or “dirty region.” + * Adds @region to the update area for @surface. * - * GDK will process all updates whenever the frame clock schedules a - * redraw, so there’s no need to do forces redraws manually, you just - * need to invalidate regions that you know should be redrawn. - **/ + * The update area is the region that needs to be redrawn, + * or “dirty region.” + * + * GDK will process all updates whenever the frame clock schedules + * a redraw, so there’s no need to do forces redraws manually, you + * just need to invalidate regions that you know should be redrawn. + */ void gdk_surface_invalidate_region (GdkSurface *surface, const cairo_region_t *region) @@ -1535,11 +1558,11 @@ gdk_surface_invalidate_region (GdkSurface *surface, /* * _gdk_surface_clear_update_area: - * @surface: a #GdkSurface. + * @surface: a `GdkSurface` * * Internal function to clear the update area for a surface. * This is called when the surface is hidden or destroyed. - **/ + */ void _gdk_surface_clear_update_area (GdkSurface *surface) { @@ -1556,14 +1579,14 @@ _gdk_surface_clear_update_area (GdkSurface *surface) /* * gdk_surface_freeze_updates: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * * Temporarily freezes a surface such that it won’t receive expose * events. The surface will begin receiving expose events again when * gdk_surface_thaw_updates() is called. If gdk_surface_freeze_updates() * has been called more than once, gdk_surface_thaw_updates() must be * called an equal number of times to begin processing exposes. - **/ + */ void gdk_surface_freeze_updates (GdkSurface *surface) { @@ -1590,12 +1613,12 @@ request_motion_cb (void *data) /* * gdk_surface_thaw_updates: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * * Thaws a surface frozen with gdk_surface_freeze_updates(). Note that this * will not necessarily schedule updates if the surface freeze count reaches * zero. - **/ + */ void gdk_surface_thaw_updates (GdkSurface *surface) { @@ -1623,7 +1646,7 @@ gdk_surface_thaw_updates (GdkSurface *surface) /* * gdk_surface_constrain_size: - * @geometry: a #GdkGeometry structure + * @geometry: a `GdkGeometry` structure * @flags: a mask indicating what portions of @geometry are set * @width: desired width of surface * @height: desired height of the surface @@ -1677,18 +1700,19 @@ gdk_surface_constrain_size (GdkGeometry *geometry, /** * gdk_surface_get_device_position: - * @surface: a #GdkSurface. - * @device: pointer #GdkDevice to query to. - * @x: (out) (allow-none): return location for the X coordinate of @device, or %NULL. - * @y: (out) (allow-none): return location for the Y coordinate of @device, or %NULL. - * @mask: (out) (allow-none): return location for the modifier mask, or %NULL. + * @surface: a `GdkSurface` + * @device: pointer `GdkDevice` to query to + * @x: (out) (allow-none): return locatio for the X coordinate of @device, or %NULL + * @y: (out) (allow-none): return location for the Y coordinate of @device, or %NULL + * @mask: (out) (allow-none): return location for the modifier mask, or %NULL * - * Obtains the current device position in doubles and modifier state. - * The position is given in coordinates relative to the upper left - * corner of @surface. + * Obtains the current device position and modifier state. + * + * The position is given in coordinates relative to the upper + * left corner of @surface. * * Return: %TRUE if the device is over the surface - **/ + */ gboolean gdk_surface_get_device_position (GdkSurface *surface, GdkDevice *device, @@ -1725,12 +1749,14 @@ gdk_surface_get_device_position (GdkSurface *surface, /** * gdk_surface_hide: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` + * + * Hide the surface. * * For toplevel surfaces, withdraws them, so they will no longer be * known to the window manager; for all surfaces, unmaps them, so * they won’t be displayed. Normally done automatically as - * part of gtk_widget_hide(). + * part of [method@Gtk.Widget.hide]. */ void gdk_surface_hide (GdkSurface *surface) @@ -1811,17 +1837,18 @@ gdk_surface_set_cursor_internal (GdkSurface *surface, /** * gdk_surface_get_cursor: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * - * Retrieves a #GdkCursor pointer for the cursor currently set on the - * specified #GdkSurface, or %NULL. If the return value is %NULL then - * there is no custom cursor set on the specified surface, and it is - * using the cursor for its parent surface. + * Retrieves a `GdkCursor` pointer for the cursor currently set on the + * `GdkSurface`. * - * Returns: (nullable) (transfer none): a #GdkCursor, or %NULL. The - * returned object is owned by the #GdkSurface and should not be - * unreferenced directly. Use gdk_surface_set_cursor() to unset the - * cursor of the surface + * If the return value is %NULL then there is no custom cursor set on + * the surface, and it is using the cursor for its parent surface. + * + * Returns: (nullable) (transfer none): a `GdkCursor`, or %NULL. The + * returned object is owned by the `GdkSurface` and should not be + * unreferenced directly. Use [method@Gdk.Surface.set_cursor] to + * unset the cursor of the surface */ GdkCursor * gdk_surface_get_cursor (GdkSurface *surface) @@ -1833,22 +1860,21 @@ gdk_surface_get_cursor (GdkSurface *surface) /** * gdk_surface_set_cursor: - * @surface: a #GdkSurface - * @cursor: (allow-none): a cursor + * @surface: a `GdkSurface` + * @cursor: (allow-none): a `GdkCursor` * - * Sets the default mouse pointer for a #GdkSurface. + * Sets the default mouse pointer for a `GdkSurface`. * + * Passing %NULL for the @cursor argument means that @surface will use + * the cursor of its parent surface. Most surfaces should use this default. * Note that @cursor must be for the same display as @surface. * - * Use gdk_cursor_new_from_name() or gdk_cursor_new_from_texture() to - * create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. - * Passing %NULL for the @cursor argument to gdk_surface_set_cursor() means - * that @surface will use the cursor of its parent surface. Most surfaces - * should use this default. + * Use [ctor@Gdk.Cursor.new_from_name] or [ctor@Gdk.Cursor.new_from_texture] + * to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. */ void gdk_surface_set_cursor (GdkSurface *surface, - GdkCursor *cursor) + GdkCursor *cursor) { g_return_if_fail (GDK_IS_SURFACE (surface)); @@ -1891,22 +1917,23 @@ gdk_surface_set_cursor (GdkSurface *surface, /** * gdk_surface_get_device_cursor: - * @surface: a #GdkSurface. - * @device: a logical, pointer #GdkDevice. + * @surface: a `GdkSurface` + * @device: a pointer `GdkDevice` * - * Retrieves a #GdkCursor pointer for the @device currently set on the - * specified #GdkSurface, or %NULL. If the return value is %NULL then - * there is no custom cursor set on the specified surface, and it is - * using the cursor for its parent surface. + * Retrieves a `GdkCursor` pointer for the @device currently set on the + * specified `GdkSurface`. * - * Returns: (nullable) (transfer none): a #GdkCursor, or %NULL. The - * returned object is owned by the #GdkSurface and should not be - * unreferenced directly. Use gdk_surface_set_cursor() to unset the - * cursor of the surface - **/ + * If the return value is %NULL then there is no custom cursor set on the + * specified surface, and it is using the cursor for its parent surface. + * + * Returns: (nullable) (transfer none): a `GdkCursor`, or %NULL. The + * returned object is owned by the `GdkSurface` and should not be + * unreferenced directly. Use [method@Gdk.Surface.set_cursor] to unset + * the cursor of the surface + */ GdkCursor * gdk_surface_get_device_cursor (GdkSurface *surface, - GdkDevice *device) + GdkDevice *device) { g_return_val_if_fail (GDK_IS_SURFACE (surface), NULL); g_return_val_if_fail (GDK_IS_DEVICE (device), NULL); @@ -1917,21 +1944,22 @@ gdk_surface_get_device_cursor (GdkSurface *surface, /** * gdk_surface_set_device_cursor: - * @surface: a #GdkSurface - * @device: a logical, pointer #GdkDevice - * @cursor: a #GdkCursor + * @surface: a `GdkSurface` + * @device: a pointer `GdkDevice` + * @cursor: a `GdkCursor` * - * Sets a specific #GdkCursor for a given device when it gets inside @surface. - * Use gdk_cursor_new_from_name() or gdk_cursor_new_from_texture() to create - * the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. Passing - * %NULL for the @cursor argument to gdk_surface_set_cursor() means that - * @surface will use the cursor of its parent surface. Most surfaces should - * use this default. - **/ + * Sets a specific `GdkCursor` for a given device when it gets inside @surface. + * + * Passing %NULL for the @cursor argument means that @surface will use the + * cursor of its parent surface. Most surfaces should use this default. + * + * Use [ctor@Gdk.Cursor.new_from_name] or [ctor@Gdk.Cursor.new_from_texture] + * to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. + */ void gdk_surface_set_device_cursor (GdkSurface *surface, - GdkDevice *device, - GdkCursor *cursor) + GdkDevice *device, + GdkCursor *cursor) { g_return_if_fail (GDK_IS_SURFACE (surface)); g_return_if_fail (GDK_IS_DEVICE (device)); @@ -1947,39 +1975,41 @@ gdk_surface_set_device_cursor (GdkSurface *surface, /* * gdk_surface_get_geometry: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * @x: (out) (allow-none): return location for X coordinate of surface (relative to its parent) * @y: (out) (allow-none): return location for Y coordinate of surface (relative to its parent) * @width: (out) (allow-none): return location for width of surface * @height: (out) (allow-none): return location for height of surface * - * Any of the return location arguments to this function may be %NULL, - * if you aren’t interested in getting the value of that field. + * Get the geometry of the surface. * * The X and Y coordinates returned are relative to the parent surface * of @surface, which for toplevels usually means relative to the * surface decorations (titlebar, etc.) rather than relative to the * root window (screen-size background window). * - * On the X11 platform, the geometry is obtained from the X server, - * so reflects the latest position of @surface; this may be out-of-sync - * with the position of @surface delivered in the most-recently-processed - * #GdkEventConfigure. gdk_surface_get_position() in contrast gets the - * position from the most recent configure event. + * On the X11 platform, the geometry is obtained from the X server, so + * reflects the latest position of @surface; this may be out-of-sync with + * the position of @surface delivered in the most-recently-processed + * `GdkEventConfigure`. [method@Gdk.Surface.get_position] in contrast gets + * the position from the most recent configure event. * - * Note: If @surface is not a toplevel, it is much better - * to call gdk_surface_get_position(), gdk_surface_get_width() and - * gdk_surface_get_height() instead, because it avoids the roundtrip to - * the X server and because these functions support the full 32-bit + * Any of the return location arguments to this function may be %NULL, + * if you aren’t interested in getting the value of that field. + * + * Note: If @surface is not a toplevel, it is much better to call + * [method@Gdk.Surface.get_position], [method@Gdk.Surface.get_width] and + * [method@Gdk.Surface.get_height] instead, because it avoids the roundtrip + * to the X server and because these functions support the full 32-bit * coordinate space, whereas gdk_surface_get_geometry() is restricted to * the 16-bit coordinates of X11. */ void gdk_surface_get_geometry (GdkSurface *surface, - int *x, - int *y, - int *width, - int *height) + int *x, + int *y, + int *width, + int *height) { g_return_if_fail (GDK_IS_SURFACE (surface)); @@ -1991,12 +2021,12 @@ gdk_surface_get_geometry (GdkSurface *surface, /** * gdk_surface_get_width: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * * Returns the width of the given @surface. * * Surface size is reported in ”application pixels”, not - * ”device pixels” (see gdk_surface_get_scale_factor()). + * ”device pixels” (see [method@Gdk.Surface.get_scale_factor]). * * Returns: The width of @surface */ @@ -2010,12 +2040,12 @@ gdk_surface_get_width (GdkSurface *surface) /** * gdk_surface_get_height: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * * Returns the height of the given @surface. * * Surface size is reported in ”application pixels”, not - * ”device pixels” (see gdk_surface_get_scale_factor()). + * ”device pixels” (see [method@Gdk.Surface.get_scale_factor]). * * Returns: The height of @surface */ @@ -2029,11 +2059,12 @@ gdk_surface_get_height (GdkSurface *surface) /* * gdk_surface_get_origin: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * @x: (out): return location for X coordinate * @y: (out): return location for Y coordinate * * Obtains the position of a surface in root window coordinates. + * * (Compare with gdk_surface_get_position() and * gdk_surface_get_geometry() which return the position * of a surface relative to its parent surface.) @@ -2050,7 +2081,7 @@ gdk_surface_get_origin (GdkSurface *surface, /* * gdk_surface_get_root_coords: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * @x: X coordinate in surface * @y: Y coordinate in surface * @root_x: (out): return location for X coordinate @@ -2082,21 +2113,22 @@ gdk_surface_get_root_coords (GdkSurface *surface, /** * gdk_surface_set_input_region: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * @region: region of surface to be reactive * * Apply the region to the surface for the purpose of event - * handling. Mouse events which happen while the pointer position - * corresponds to an unset bit in the mask will be passed on the - * surface below @surface. + * handling. * - * An input region is typically used with RGBA surfaces. - * The alpha channel of the surface defines which pixels are - * invisible and allows for nicely antialiased borders, - * and the input region controls where the surface is - * “clickable”. + * Mouse events which happen while the pointer position corresponds + * to an unset bit in the mask will be passed on the surface below + * @surface. * - * Use gdk_display_supports_input_shapes() to find out if + * An input region is typically used with RGBA surfaces. The alpha + * channel of the surface defines which pixels are invisible and + * allows for nicely antialiased borders, and the input region + * controls where the surface is “clickable”. + * + * Use [method@Gdk.Display.supports_input_shapes] to find out if * a particular backend supports input regions. */ void @@ -2162,12 +2194,13 @@ update_cursor (GdkDisplay *display, /** * gdk_surface_beep: - * @surface: a toplevel #GdkSurface + * @surface: a toplevel `GdkSurface` * - * Emits a short beep associated to @surface in the appropriate - * display, if supported. Otherwise, emits a short beep on - * the display just as gdk_display_beep(). - **/ + * Emits a short beep associated to @surface. + * + * If the display of @surface does not support per-surface beeps, + * emits a short beep on the display just as [method@Gdk.Display.beep]. + */ void gdk_surface_beep (GdkSurface *surface) { @@ -2310,24 +2343,26 @@ _gdk_windowing_got_event (GdkDisplay *display, * @width: width of the new surface * @height: height of the new surface * - * Create a new surface that is as compatible as possible with the - * given @surface. For example the new surface will have the same - * fallback resolution and font options as @surface. Generally, the new - * surface will also use the same backend as @surface, unless that is - * not possible for some reason. The type of the returned surface may - * be examined with cairo_surface_get_type(). + * Create a new Cairo surface that is as compatible as possible with the + * given @surface. + * + * For example the new surface will have the same fallback resolution + * and font options as @surface. Generally, the new surface will also + * use the same backend as @surface, unless that is not possible for + * some reason. The type of the returned surface may be examined with + * cairo_surface_get_type(). * * Initially the surface contents are all 0 (transparent if contents * have transparency, black otherwise.) * - * Returns: a pointer to the newly allocated surface. The caller - * owns the surface and should call cairo_surface_destroy() when done - * with it. - * * This function always returns a valid pointer, but it will return a * pointer to a “nil” surface if @other is already in an error state * or any other error occurs. - **/ + * + * Returns: a pointer to the newly allocated surface. The caller + * owns the surface and should call cairo_surface_destroy() when done + * with it. + */ cairo_surface_t * gdk_surface_create_similar_surface (GdkSurface * surface, cairo_content_t content, @@ -2370,18 +2405,19 @@ gdk_surface_destroy_notify (GdkSurface *surface) * * This function is called by the drag source. After this call, you * probably want to set up the drag icon using the surface returned - * by gdk_drag_get_drag_surface(). + * by [method@Gdk.Drag.get_drag_surface]. * - * This function returns a reference to the GdkDrag object, but GTK - * keeps its own reference as well, as long as the DND operation is - * going on. + * This function returns a reference to the [class@Gdk.Drag] object, + * but GTK keeps its own reference as well, as long as the DND operation + * is going on. * * Note: if @actions include %GDK_ACTION_MOVE, you need to listen for - * the #GdkDrag::dnd-finished signal and delete the data at the source - * if gdk_drag_get_selected_action() returns %GDK_ACTION_MOVE. + * the [signal@Gdk.Drag::dnd-finished] signal and delete the data at + * the source if [method@Gdk.Drag.get_selected_action] returns + * %GDK_ACTION_MOVE. * - * Returns: (transfer full) (nullable): a newly created #GdkDrag or - * %NULL on error. + * Returns: (transfer full) (nullable): a newly created [class@Gdk.Drag] + * or %NULL on error */ GdkDrag * gdk_drag_begin (GdkSurface *surface, @@ -2529,13 +2565,14 @@ gdk_surface_set_frame_clock (GdkSurface *surface, * gdk_surface_get_frame_clock: * @surface: surface to get frame clock for * - * Gets the frame clock for the surface. The frame clock for a surface - * never changes unless the surface is reparented to a new toplevel - * surface. + * Gets the frame clock for the surface. + * + * The frame clock for a surface never changes unless the surface is + * reparented to a new toplevel surface. * * Returns: (transfer none): the frame clock */ -GdkFrameClock* +GdkFrameClock * gdk_surface_get_frame_clock (GdkSurface *surface) { g_return_val_if_fail (GDK_IS_SURFACE (surface), NULL); @@ -2548,14 +2585,14 @@ gdk_surface_get_frame_clock (GdkSurface *surface) * @surface: surface to get scale factor for * * Returns the internal scale factor that maps from surface coordinates - * to the actual device pixels. On traditional systems this is 1, but - * on very high density outputs this can be a higher value (often 2). + * to the actual device pixels. * - * A higher value means that drawing is automatically scaled up to - * a higher resolution, so any code doing drawing will automatically look - * nicer. However, if you are supplying pixel-based data the scale - * value can be used to determine whether to use a pixel resource - * with higher resolution data. + * On traditional systems this is 1, but on very high density outputs + * this can be a higher value (often 2). A higher value means that drawing + * is automatically scaled up to a higher resolution, so any code doing + * drawing will automatically look nicer. However, if you are supplying + * pixel-based data the scale value can be used to determine whether to + * use a pixel resource with higher resolution data. * * The scale of a surface may change during runtime. * @@ -2611,9 +2648,11 @@ gdk_surface_get_unscaled_size (GdkSurface *surface, /** * gdk_surface_set_opaque_region: - * @surface: a top-level or non-native #GdkSurface + * @surface: a top-level `GdkSurface` * @region: (allow-none): a region, or %NULL * + * Marks a region of the `GdkSurface` as opaque. + * * For optimisation purposes, compositing window managers may * like to not draw obscured regions of surfaces, or turn off blending * during for these regions. With RGB windows with no transparency, @@ -2623,10 +2662,10 @@ gdk_surface_get_unscaled_size (GdkSurface *surface, * * This function only works for toplevel surfaces. * - * GTK will update this property automatically if - * the @surface background is opaque, as we know where the opaque regions - * are. If your surface background is not opaque, please update this - * property in your #GtkWidgetClass.css_changed() handler. + * GTK will update this property automatically if the @surface background + * is opaque, as we know where the opaque regions are. If your surface + * background is not opaque, please update this property in your + * #GtkWidgetClass.css_changed() handler. */ void gdk_surface_set_opaque_region (GdkSurface *surface, @@ -2943,12 +2982,14 @@ gdk_surface_handle_event (GdkEvent *event) /* * gdk_surface_request_motion: - * @surface: a #GdkSurface + * @surface: a `GdkSurface` * * Request that the next frame cycle should deliver a motion - * event for @surface if the pointer is over it, regardless - * whether the pointer has moved or not. This is used by GTK - * after moving widgets around. + * event for @surface. + * + * The motion event will be delivered if the pointer is over the + * surface, regardless whether the pointer has moved or not. This + * is used by GTK after moving widgets around. */ void gdk_surface_request_motion (GdkSurface *surface) @@ -2963,16 +3004,12 @@ gdk_surface_request_motion (GdkSurface *surface) * @x: (inout): coordinates to translate * @y: (inout): coordinates to translate * - * Translates the given coordinates from being - * relative to the @from surface to being relative - * to the @to surface. + * Translates coordinates between two surfaces. * - * Note that this only works if @to and @from are - * popups or transient-for to the same toplevel - * (directly or indirectly). + * Note that this only works if @to and @from are popups or + * transient-for to the same toplevel (directly or indirectly). * - * Returns: %TRUE if the coordinates were successfully - * translated + * Returns: %TRUE if the coordinates were successfully translated */ gboolean gdk_surface_translate_coordinates (GdkSurface *from, diff --git a/gdk/gdktexture.c b/gdk/gdktexture.c index 621274c84f..6e3bc73380 100644 --- a/gdk/gdktexture.c +++ b/gdk/gdktexture.c @@ -17,21 +17,21 @@ */ /** - * SECTION:gdktexture - * @Title: GdkTexture - * @Short_description: Pixel data + * GdkTexture: * - * #GdkTexture is the basic element used to refer to pixel data. - * It is primarily mean for pixel data that will not change over + * `GdkTexture` is the basic element used to refer to pixel data. + * + * It is primarily meant for pixel data that will not change over * multiple frames, and will be used for a long time. * - * There are various ways to create #GdkTexture objects from a - * #GdkPixbuf, or a Cairo surface, or other pixel data. + * There are various ways to create `GdkTexture` objects from a + * `GdkPixbuf`, or a Cairo surface, or other pixel data. * - * The ownership of the pixel data is transferred to the #GdkTexture - * instance; you can only make a copy of it, via gdk_texture_download(). + * The ownership of the pixel data is transferred to the `GdkTexture` + * instance; you can only make a copy of it, via + * [method@Gdk.Texture.download]. * - * #GdkTexture is an immutable object: That means you cannot change + * `GdkTexture` is an immutable object: That means you cannot change * anything about it other than increasing the reference count via * g_object_ref(). */ @@ -53,12 +53,6 @@ gtk_snapshot_append_texture (GdkSnapshot *snapshot, GdkTexture *texture, const graphene_rect_t *bounds); -/** - * GdkTexture: - * - * The `GdkTexture` structure contains only private data. - */ - enum { PROP_0, PROP_WIDTH, @@ -246,9 +240,10 @@ gdk_texture_init (GdkTexture *self) * @surface: a cairo image surface * * Creates a new texture object representing the surface. + * * @surface must be an image surface with format CAIRO_FORMAT_ARGB32. * - * Returns: a new #GdkTexture + * Returns: a new `GdkTexture` */ GdkTexture * gdk_texture_new_for_surface (cairo_surface_t *surface) @@ -279,11 +274,11 @@ gdk_texture_new_for_surface (cairo_surface_t *surface) /** * gdk_texture_new_for_pixbuf: - * @pixbuf: a #GdkPixbuf + * @pixbuf: a `GdkPixbuf` * - * Creates a new texture object representing the #GdkPixbuf. + * Creates a new texture object representing the `GdkPixbuf`. * - * Returns: a new #GdkTexture + * Returns: a new `GdkTexture` */ GdkTexture * gdk_texture_new_for_pixbuf (GdkPixbuf *pixbuf) @@ -316,16 +311,16 @@ 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 supported formats are PNG and JPEG, though more formats might be - * available. + * + * The file format is detected automatically. The supported formats + * are PNG and JPEG, though more formats might be available. * * It is a fatal error if @resource_path does not specify a valid * image resource and the program will abort if that happens. * If you are unsure about the validity of a resource, use - * gdk_texture_new_from_file() to load it. + * [ctor@Gdk.Texture.new_from_file] to load it. * - * Return value: A newly-created texture + * Return value: A newly-created `GdkTexture` */ GdkTexture * gdk_texture_new_from_resource (const char *resource_path) @@ -348,18 +343,18 @@ gdk_texture_new_from_resource (const char *resource_path) /** * gdk_texture_new_from_file: - * @file: #GFile to load + * @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. - * The supported formats are PNG and JPEG, though more formats might be - * available. + * + * The file format is detected automatically. The supported formats + * are PNG and JPEG, though more formats might be available. * * If %NULL is returned, then @error will be set. * - * Return value: A newly-created #GdkTexture or %NULL if an error occurred. - **/ + * Return value: A newly-created `GdkTexture` or %NULL if an error occurred. + */ GdkTexture * gdk_texture_new_from_file (GFile *file, GError **error) @@ -388,11 +383,11 @@ gdk_texture_new_from_file (GFile *file, /** * gdk_texture_get_width: - * @texture: a #GdkTexture + * @texture: a `GdkTexture` * * Returns the width of @texture, in pixels. * - * Returns: the width of the #GdkTexture + * Returns: the width of the `GdkTexture` */ int gdk_texture_get_width (GdkTexture *texture) @@ -404,11 +399,11 @@ gdk_texture_get_width (GdkTexture *texture) /** * gdk_texture_get_height: - * @texture: a #GdkTexture + * @texture: a `GdkTexture` * * Returns the height of the @texture, in pixels. * - * Returns: the height of the #GdkTexture + * Returns: the height of the `GdkTexture` */ int gdk_texture_get_height (GdkTexture *texture) @@ -456,21 +451,22 @@ gdk_texture_download_area (GdkTexture *texture, /** * gdk_texture_download: - * @texture: a #GdkTexture + * @texture: a `GdkTexture` * @data: (array): pointer to enough memory to be filled with the * downloaded data of @texture * @stride: rowstride in bytes * - * Downloads the @texture into local memory. This may be - * an expensive operation, as the actual texture data may - * reside on a GPU or on a remote display server. + * Downloads the @texture into local memory. + * + * This may be an expensive operation, as the actual texture data + * may reside on a GPU or on a remote display server. * * The data format of the downloaded data is equivalent to * %CAIRO_FORMAT_ARGB32, so every downloaded pixel requires * 4 bytes of memory. * * Downloading a texture into a Cairo image surface: - * |[ + * ```c * surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32, * gdk_texture_get_width (texture), * gdk_texture_get_height (texture)); @@ -478,7 +474,7 @@ gdk_texture_download_area (GdkTexture *texture, * cairo_image_surface_get_data (surface), * cairo_image_surface_get_stride (surface)); * cairo_surface_mark_dirty (surface); - * ]| + * ``` */ void gdk_texture_download (GdkTexture *texture, @@ -536,18 +532,18 @@ gdk_texture_get_render_data (GdkTexture *self, /** * gdk_texture_save_to_png: - * @texture: a #GdkTexture + * @texture: a `GdkTexture` * @filename: the filename to store to * * Store the given @texture to the @filename as a PNG file. * * This is a utility function intended for debugging and testing. * If you want more control over formats, proper error handling or - * want to store to a #GFile or other location, you might want to + * want to store to a `GFile` or other location, you might want to * look into using the gdk-pixbuf library. * * Returns: %TRUE if saving succeeded, %FALSE on failure. - **/ + */ gboolean gdk_texture_save_to_png (GdkTexture *texture, const char *filename) diff --git a/gdk/gdktoplevel.c b/gdk/gdktoplevel.c index 13eb38cda1..80b1a4285d 100644 --- a/gdk/gdktoplevel.c +++ b/gdk/gdktoplevel.c @@ -27,17 +27,13 @@ #include /** - * SECTION:gdktoplevel - * @Short_description: Interface for toplevel surfaces - * @Title: Toplevels - * @See_also: #GdkSurface, #GdkPopup + * GdkToplevel: * - * A #GdkToplevel is a freestanding toplevel surface. + * 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. + * 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) @@ -119,53 +115,109 @@ gdk_toplevel_default_init (GdkToplevelInterface *iface) iface->inhibit_system_shortcuts = gdk_toplevel_default_inhibit_system_shortcuts; iface->restore_system_shortcuts = gdk_toplevel_default_restore_system_shortcuts; + /** + * GdkToplevel:state: + * + * The state of the toplevel. + */ g_object_interface_install_property (iface, g_param_spec_flags ("state", P_("State"), P_("State"), GDK_TYPE_TOPLEVEL_STATE, 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)); + + /** + * GdkToplevel:title: + * + * The title of the surface. + */ g_object_interface_install_property (iface, g_param_spec_string ("title", "Title", "The title of the surface", NULL, G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY)); + + /** + * GdkToplevel:startup-id: + * + * The startup ID of the surface. + * + * See [class@Gdk.AppLaunchContext] for more information about + * startup feedback. + */ g_object_interface_install_property (iface, g_param_spec_string ("startup-id", "Startup ID", "The startup ID of the surface", NULL, G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY)); + + /** + * GdkToplevel:transient-for: + * + * The transient parent of the surface. + */ g_object_interface_install_property (iface, g_param_spec_object ("transient-for", "Transient For", "The transient parent of the surface", GDK_TYPE_SURFACE, G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY)); + + /** + * GdkToplevel:modal: + * + * Whether the surface is modal. + */ g_object_interface_install_property (iface, g_param_spec_boolean ("modal", "Modal", "Whether the surface is modal", FALSE, G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY)); + + /** + * GdkToplevel:icon-list: + * + * A list of textures to use as icon. + */ g_object_interface_install_property (iface, g_param_spec_pointer ("icon-list", "Icon List", "The list of icon textures", G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY)); + + /** + * GdkToplevel:decorated: + * + * Whether the window manager should add decorations. + */ g_object_interface_install_property (iface, g_param_spec_boolean ("decorated", "Decorated", "Decorated", FALSE, G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY)); + + /** + * GdkToplevel:deletable: + * + * Whether the window manager should allow to close the surface. + */ g_object_interface_install_property (iface, g_param_spec_boolean ("deletable", "Deletable", "Deletable", FALSE, G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY)); + + /** + * GdkToplevel:fullscreen-mode: + * + * The fullscreen mode of the surface. + */ g_object_interface_install_property (iface, g_param_spec_enum ("fullscreen-mode", "Fullscreen mode", @@ -173,6 +225,12 @@ gdk_toplevel_default_init (GdkToplevelInterface *iface) GDK_TYPE_FULLSCREEN_MODE, GDK_FULLSCREEN_ON_CURRENT_MONITOR, G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY)); + + /** + * GdkToplevel:shortcuts-inhibited: + * + * Whether the surface should inhibit keyboard shortcuts. + */ g_object_interface_install_property (iface, g_param_spec_boolean ("shortcuts-inhibited", "Shortcuts inhibited", @@ -182,19 +240,21 @@ gdk_toplevel_default_init (GdkToplevelInterface *iface) /** * GdkToplevel::compute-size: - * @toplevel: a #GdkToplevel - * @size: (type Gdk.ToplevelSize) (out caller-allocates): a #GdkToplevelSize + * @toplevel: a `GdkToplevel` + * @size: (type Gdk.ToplevelSize) (out caller-allocates): a `GdkToplevelSize` * - * Compute the desired size of the toplevel, given the information passed via - * the #GdkToplevelSize object. + * Emitted when the size for the surface needs to be computed, when + * it is present. * - * It will normally be emitted during or after gdk_toplevel_present(), - * depending on the configuration received by the windowing system. It may - * also be emitted at any other point in time, in response to the windowing - * system spontaneously changing the configuration. + * It will normally be emitted during or after [method@Gdk.Toplevel.present], + * depending on the configuration received by the windowing system. + * It may also be emitted at any other point in time, in response + * to the windowing system spontaneously changing the configuration. * - * It is the responsibility of the GdkToplevel user to handle this signal; - * failing to do so will result in an arbitrary size being used as a result. + * It is the responsibility of the toplevel user to handle this signal + * and compute the desired size of the toplevel, given the information + * passed via the [struct@Gdk.ToplevelSize] object. Failing to do so + * will result in an arbitrary size being used as a result. */ signals[COMPUTE_SIZE] = g_signal_new ("compute-size", @@ -227,16 +287,17 @@ gdk_toplevel_install_properties (GObjectClass *object_class, /** * gdk_toplevel_present: - * @toplevel: the #GdkToplevel to show - * @layout: the #GdkToplevelLayout object used to layout + * @toplevel: the `GdkToplevel` to show + * @layout: the `GdkToplevelLayout` object used to layout + * + * Present @toplevel after having processed the `GdkToplevelLayout` rules. * - * Present @toplevel after having processed the #GdkToplevelLayout rules. * If the toplevel was previously not showing, it will be showed, * otherwise it will change layout according to @layout. * - * GDK may emit the 'compute-size' signal to let the user of this toplevel - * compute the preferred size of the toplevel surface. See - * #GdkToplevel::compute-size for details. + * GDK may emit the [signal@Gdk.Toplevel::compute-size] signal to let + * the user of this toplevel compute the preferred size of the toplevel + * surface. * * Presenting is asynchronous and the specified layout parameters are not * guaranteed to be respected. @@ -253,7 +314,7 @@ gdk_toplevel_present (GdkToplevel *toplevel, /** * gdk_toplevel_minimize: - * @toplevel: a #GdkToplevel + * @toplevel: a `GdkToplevel` * * Asks to minimize the @toplevel. * @@ -271,7 +332,7 @@ gdk_toplevel_minimize (GdkToplevel *toplevel) /** * gdk_toplevel_lower: - * @toplevel: a #GdkToplevel + * @toplevel: a `GdkToplevel` * * Asks to lower the @toplevel below other windows. * @@ -289,13 +350,13 @@ gdk_toplevel_lower (GdkToplevel *toplevel) /** * gdk_toplevel_focus: - * @toplevel: a #GdkToplevel + * @toplevel: a `GdkToplevel` * @timestamp: timestamp of the event triggering the surface focus * * Sets keyboard focus to @surface. * - * In most cases, gtk_window_present_with_time() should be used - * on a #GtkWindow, rather than calling this function. + * In most cases, [method@Gtk.Window.present_with_time] should be + * used on a [class@Gtk.Window], rather than calling this function. */ void gdk_toplevel_focus (GdkToplevel *toplevel, @@ -308,10 +369,10 @@ gdk_toplevel_focus (GdkToplevel *toplevel, /** * gdk_toplevel_get_state: - * @toplevel: a #GdkToplevel + * @toplevel: a `GdkToplevel` * - * Gets the bitwise OR of the currently active surface state flags, - * from the #GdkToplevelState enumeration. + * Gets the bitwise or of the currently active surface state flags, + * from the `GdkToplevelState` enumeration. * * Returns: surface state bitfield */ @@ -329,10 +390,12 @@ gdk_toplevel_get_state (GdkToplevel *toplevel) /** * gdk_toplevel_set_title: - * @toplevel: a #GdkToplevel + * @toplevel: a `GdkToplevel` * @title: title of @surface * - * Sets the title of a toplevel surface, to be displayed in the titlebar, + * Sets the title of a toplevel surface. + * + * The title maybe be displayed in the titlebar, * in lists of windows, etc. */ void @@ -346,11 +409,14 @@ gdk_toplevel_set_title (GdkToplevel *toplevel, /** * gdk_toplevel_set_startup_id: - * @toplevel: a #GdkToplevel + * @toplevel: a `GdkToplevel` * @startup_id: a string with startup-notification identifier * - * When using GTK, typically you should use gtk_window_set_startup_id() - * instead of this low-level function. + * Sets the startup notification ID. + * + * When using GTK, typically you should use + * [method@Gtk.Window.set_startup_id] instead of this + * low-level function. */ void gdk_toplevel_set_startup_id (GdkToplevel *toplevel, @@ -363,16 +429,18 @@ gdk_toplevel_set_startup_id (GdkToplevel *toplevel, /** * gdk_toplevel_set_transient_for: - * @toplevel: a #GdkToplevel - * @parent: another toplevel #GdkSurface + * @toplevel: a `GdkToplevel` + * @parent: another toplevel `GdkSurface` * - * Indicates to the window manager that @surface is a transient dialog - * associated with the application surface @parent. This allows the - * window manager to do things like center @surface on @parent and - * keep @surface above @parent. + * Sets a transient-for parent. * - * See gtk_window_set_transient_for() if you’re using #GtkWindow or - * #GtkDialog. + * Indicates to the window manager that @surface is a transient + * dialog associated with the application surface @parent. This + * allows the window manager to do things like center @surface + * on @parent and keep @surface above @parent. + * + * See [method@Gtk.Window.set_transient_for] if you’re using + * [class@Gtk.Window] or [class@Gtk.Dialog]. */ void gdk_toplevel_set_transient_for (GdkToplevel *toplevel, @@ -385,16 +453,18 @@ gdk_toplevel_set_transient_for (GdkToplevel *toplevel, /** * gdk_toplevel_set_modal: - * @toplevel: A toplevel surface + * @toplevel: a `GdkToplevel` * @modal: %TRUE if the surface is modal, %FALSE otherwise. * + * Sets the toplevel to be modal. + * * The application can use this hint to tell the * window manager that a certain surface has modal * behaviour. The window manager can use this information * to handle modal surfaces in a special way. * * You should only use this on surfaces for which you have - * previously called gdk_toplevel_set_transient_for(). + * previously called [method@Gdk.Toplevel.set_transient_for]. */ void gdk_toplevel_set_modal (GdkToplevel *toplevel, @@ -407,9 +477,9 @@ gdk_toplevel_set_modal (GdkToplevel *toplevel, /** * gdk_toplevel_set_icon_list: - * @toplevel: a #GdkToplevel + * @toplevel: a `GdkToplevel` * @surfaces: (transfer none) (element-type GdkTexture): - * A list of textures to use as icon, of different sizes + * A list of textures to use as icon, of different sizes * * Sets a list of icons for the surface. * @@ -432,8 +502,8 @@ gdk_toplevel_set_icon_list (GdkToplevel *toplevel, /** * gdk_toplevel_show_window_menu: - * @toplevel: a #GdkToplevel - * @event: a #GdkEvent to show the menu for + * @toplevel: a `GdkToplevel` + * @event: a `GdkEvent` to show the menu for * * Asks the windowing system to show the window menu. * @@ -455,9 +525,11 @@ gdk_toplevel_show_window_menu (GdkToplevel *toplevel, /** * gdk_toplevel_set_decorated: - * @toplevel: a #GdkToplevel + * @toplevel: a `GdkToplevel` * @decorated: %TRUE to request decorations * + * Sets the toplevel to be decorated. + * * Setting @decorated to %FALSE hints the desktop environment * that the surface has its own, client-side decorations and * does not need to have window decorations added. @@ -473,9 +545,11 @@ gdk_toplevel_set_decorated (GdkToplevel *toplevel, /** * gdk_toplevel_set_deletable: - * @toplevel: a #GdkToplevel + * @toplevel: a `GdkToplevel` * @deletable: %TRUE to request a delete button * + * Sets the toplevel to be deletable. + * * Setting @deletable to %TRUE hints the desktop environment * that it should offer the user a way to close the surface. */ @@ -490,7 +564,7 @@ gdk_toplevel_set_deletable (GdkToplevel *toplevel, /** * gdk_toplevel_supports_edge_constraints: - * @toplevel: a #GdkToplevel + * @toplevel: a `GdkToplevel` * * Returns whether the desktop environment supports * tiled window states. @@ -508,17 +582,18 @@ gdk_toplevel_supports_edge_constraints (GdkToplevel *toplevel) /** * gdk_toplevel_inhibit_system_shortcuts: - * @toplevel: the #GdkToplevel requesting system keyboard shortcuts - * @event: (nullable): the #GdkEvent that is triggering the inhibit - * request, or %NULL if none is available. + * @toplevel: a `GdkToplevel` + * @event: (nullable): the `GdkEvent` that is triggering the inhibit + * request, or %NULL if none is available * - * Requests that the @toplevel inhibit the system shortcuts, asking the - * desktop environment/windowing system to let all keyboard events reach - * the surface, as long as it is focused, instead of triggering system - * actions. + * Requests that the @toplevel inhibit the system shortcuts. + * + * This is asking the desktop environment/windowing system to let all + * keyboard events reach the surface, as long as it is focused, instead + * of triggering system actions. * * If granted, the rerouting remains active until the default shortcuts - * processing is restored with gdk_toplevel_restore_system_shortcuts(), + * processing is restored with [method@Gdk.Toplevel.restore_system_shortcuts], * or the request is revoked by the desktop environment, windowing system * or the user. * @@ -531,8 +606,7 @@ gdk_toplevel_supports_edge_constraints (GdkToplevel *toplevel) * or deny the request or even choose to ignore the request entirely. * * The caller can be notified whenever the request is granted or revoked - * by listening to the GdkToplevel::shortcuts-inhibited property. - * + * by listening to the [property@Gdk.Toplevel:shortcuts-inhibited] property. */ void gdk_toplevel_inhibit_system_shortcuts (GdkToplevel *toplevel, @@ -546,10 +620,12 @@ gdk_toplevel_inhibit_system_shortcuts (GdkToplevel *toplevel, /** * gdk_toplevel_restore_system_shortcuts: - * @toplevel: a #GdkToplevel + * @toplevel: a `GdkToplevel` * * Restore default system keyboard shortcuts which were previously - * requested to be inhibited by gdk_toplevel_inhibit_system_shortcuts(). + * inhibited. + * + * This undoes the effect of [method@Gdk.Toplevel.inhibit_system_shortcuts]. */ void gdk_toplevel_restore_system_shortcuts (GdkToplevel *toplevel) @@ -561,15 +637,17 @@ gdk_toplevel_restore_system_shortcuts (GdkToplevel *toplevel) /** * gdk_toplevel_begin_resize: - * @toplevel: a #GdkToplevel + * @toplevel: a `GdkToplevel` * @edge: the edge or corner from which the drag is started * @device: (nullable): the device used for the operation * @button: the button being used to drag, or 0 for a keyboard-initiated drag * @x: surface X coordinate of mouse click that began the drag * @y: surface Y coordinate of mouse click that began the drag - * @timestamp: timestamp of mouse click that began the drag (use gdk_event_get_time()) + * @timestamp: timestamp of mouse click that began the drag (use + * [method@Gdk.Event.get_time]) + * + * Begins an interactive resize operation. * - * Begins an interactive resize operation (for a toplevel surface). * You might use this function to implement a “window resize grip.” */ void @@ -607,9 +685,11 @@ gdk_toplevel_begin_resize (GdkToplevel *toplevel, * @button: the button being used to drag, or 0 for a keyboard-initiated drag * @x: surface X coordinate of mouse click that began the drag * @y: surface Y coordinate of mouse click that began the drag - * @timestamp: timestamp of mouse click that began the drag + * @timestamp: timestamp of mouse click that began the drag (use + * [method@Gdk.Event.get_time]) + * + * Begins an interactive move operation. * - * Begins an interactive move operation (for a toplevel surface). * You might use this function to implement draggable titlebars. */ void diff --git a/gdk/gdktoplevel.h b/gdk/gdktoplevel.h index fb29315710..1d3f9c627d 100644 --- a/gdk/gdktoplevel.h +++ b/gdk/gdktoplevel.h @@ -60,9 +60,8 @@ typedef enum * @GDK_FULLSCREEN_ON_CURRENT_MONITOR: Fullscreen on current monitor only. * @GDK_FULLSCREEN_ON_ALL_MONITORS: Span across all monitors when fullscreen. * - * Indicates which monitor (in a multi-head setup) a surface should span over - * when in fullscreen mode. - **/ + * Indicates which monitor a surface should span over when in fullscreen mode. + */ typedef enum { GDK_FULLSCREEN_ON_CURRENT_MONITOR, @@ -90,10 +89,11 @@ typedef enum * * Specifies the state of a toplevel surface. * - * On platforms that support information about individual edges, the %GDK_TOPLEVEL_STATE_TILED - * state will be set whenever any of the individual tiled states is set. On platforms - * that lack that support, the tiled state will give an indication of tiledness without - * any of the per-edge states being set. + * On platforms that support information about individual edges, the + * %GDK_TOPLEVEL_STATE_TILED state will be set whenever any of the individual + * tiled states is set. On platforms that lack that support, the tiled state + * will give an indication of tiledness without any of the per-edge states + * being set. */ typedef enum { @@ -118,11 +118,6 @@ typedef enum #define GDK_TYPE_TOPLEVEL (gdk_toplevel_get_type ()) -/** - * GdkToplevel: - * - * An interface for top level surfaces. - */ GDK_AVAILABLE_IN_ALL G_DECLARE_INTERFACE (GdkToplevel, gdk_toplevel, GDK, TOPLEVEL, GObject) diff --git a/gdk/gdktoplevellayout.c b/gdk/gdktoplevellayout.c index 0de2720b00..a950710dd4 100644 --- a/gdk/gdktoplevellayout.c +++ b/gdk/gdktoplevellayout.c @@ -23,16 +23,16 @@ #include "gdkmonitor.h" /** - * SECTION:gdktoplevellayout - * @Title: GdkToplevelLayout - * @Short_description: Information for presenting toplevels + * GdkToplevelLayout: + * + * The `GdkToplevelLayout` struct contains information that + * is necessary to present a sovereign window on screen. + * + * The `GdkToplevelLayout` gdk_toplevel_present(). * * Toplevel surfaces are sovereign windows that can be presented * to the user in various states (maximized, on all workspaces, * etc). - * - * The GdkToplevelLayout struct contains information that - * is necessary to do so, and is passed to gdk_toplevel_present(). */ struct _GdkToplevelLayout { diff --git a/gdk/gdktoplevelsize.c b/gdk/gdktoplevelsize.c index 66a4ddeadb..895b54033f 100644 --- a/gdk/gdktoplevelsize.c +++ b/gdk/gdktoplevelsize.c @@ -21,13 +21,10 @@ #include "gdktoplevelsizeprivate.h" /** - * SECTION:gdktoplevelsize - * @Title: GdkToplevelSize - * @Short_description: Information for computing toplevel size + * GdkToplevelSize: * - * The GdkToplevelSIze struct contains information that may be useful - * for users of GdkToplevel to compute a surface size. It also carries - * information back with the computational result. + * The `GdkToplevelSize` struct contains information that is useful + * to compute the size of a toplevel size. */ G_DEFINE_POINTER_TYPE (GdkToplevelSize, gdk_toplevel_size) @@ -51,7 +48,7 @@ gdk_toplevel_size_init (GdkToplevelSize *size, /** * gdk_toplevel_size_get_bounds: - * @size: a #GdkToplevelSize + * @size: a `GdkToplevelSize` * @bounds_width: (out): return location for width * @bounds_height: (out): return location for height * @@ -77,14 +74,16 @@ gdk_toplevel_size_get_bounds (GdkToplevelSize *size, /** * gdk_toplevel_size_set_size: - * @size: a #GdkToplevelSize + * @size: a `GdkToplevelSize` * @width: the width * @height: the height * - * Sets the size the toplevel prefers to be resized to. The size should be - * within the bounds (see gdk_toplevel_size_get_bounds()). The set size should - * be considered as a hint, and should not be assumed to be respected by the - * windowing system, or backend. + * Sets the size the toplevel prefers to be resized to. + * + * The size should be within the bounds (see + * [method@Gdk.ToplevelSize.get_bounds]). The set size should + * be considered as a hint, and should not be assumed to be + * respected by the windowing system, or backend. */ void gdk_toplevel_size_set_size (GdkToplevelSize *size, @@ -97,17 +96,19 @@ gdk_toplevel_size_set_size (GdkToplevelSize *size, /** * gdk_toplevel_size_set_min_size: - * @size: a #GdkToplevelSize + * @size: a `GdkToplevelSize` * @min_width: the minimum width * @min_height: the minimum height * + * Sets the minimum size of the toplevel. + * * The minimum size corresponds to the limitations the toplevel can be shrunk - * to, without resulting in incorrect painting. A user of a #GdkToplevel should + * to, without resulting in incorrect painting. A user of a `GdkToplevel` should * calculate these given both the existing size, and the bounds retrieved from - * the #GdkToplevelSize object. + * the `GdkToplevelSize` object. * * The minimum size should be within the bounds (see - * gdk_toplevel_size_get_bounds()). + * [method@Gdk.ToplevelSize.get_bounds]). */ void gdk_toplevel_size_set_min_size (GdkToplevelSize *size, @@ -120,12 +121,14 @@ gdk_toplevel_size_set_min_size (GdkToplevelSize *size, /** * gdk_toplevel_size_set_shadow_width: - * @size: a #GdkToplevelSize + * @size: a `GdkToplevelSize` * @left: width of the left part of the shadow * @right: width of the right part of the shadow * @top: height of the top part of the shadow * @bottom: height of the bottom part of the shadow * + * Sets the shadows size of the toplevel. + * * The shadow width corresponds to the part of the computed surface size * that would consist of the shadow margin surrounding the window, would * there be any. diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h index e35a9d9c6f..1c72061a61 100644 --- a/gdk/gdktypes.h +++ b/gdk/gdktypes.h @@ -53,16 +53,6 @@ G_BEGIN_DECLS */ #define GDK_CURRENT_TIME 0L -/** - * GdkRectangle: - * @x: the x coordinate of the top left corner - * @y: the y coordinate of the top left corner - * @width: the width of the rectangle - * @height: the height of the rectangle - * - * Defines the position and size of a rectangle. It is identical to - * #cairo_rectangle_int_t. - */ #ifdef __GI_SCANNER__ /* The introspection scanner is currently unable to lookup how * cairo_rectangle_int_t is actually defined. This prevents @@ -243,9 +233,7 @@ typedef enum { * @GDK_AXIS_SLIDER: the axis is used for pen slider information * @GDK_AXIS_LAST: a constant equal to the numerically highest axis value. * - * An enumeration describing the way in which a device - * axis (valuator) maps onto the predefined valuator - * types that GTK understands. + * Defines how device axes are interpreted by GTK. * * Note that the X and Y axes are not really needed; pointer devices * report their location via the x/y members of events regardless. Whether @@ -303,13 +291,13 @@ typedef enum * GdkDragAction: * @GDK_ACTION_COPY: Copy the data. * @GDK_ACTION_MOVE: Move the data, i.e. first copy it, then delete - * it from the source using the DELETE target of the X selection protocol. + * it from the source using the DELETE target of the X selection protocol. * @GDK_ACTION_LINK: Add a link to the data. Note that this is only - * useful if source and destination agree on what it means, and is not - * supported on all platforms. + * useful if source and destination agree on what it means, and is not + * supported on all platforms. * @GDK_ACTION_ASK: Ask the user what to do with the data. * - * Used in #GdkDrop and #GdkDrag to indicate the actions that the + * Used in `GdkDrop` and `GdkDrag` to indicate the actions that the * destination can and should do with the dropped data. */ typedef enum @@ -323,9 +311,10 @@ typedef enum /** * GDK_ACTION_ALL: * - * Defines all possible DND actions. This can be used in gdk_drop_status() - * messages when any drop can be accepted or a more specific drop method - * is not yet known. + * Defines all possible DND actions. + * + * This can be used in [method@Gdk.Drop.status] messages when any drop + * can be accepted or a more specific drop method is not yet known. */ #define GDK_ACTION_ALL (GDK_ACTION_COPY | GDK_ACTION_MOVE | GDK_ACTION_LINK) @@ -385,7 +374,7 @@ typedef struct _GdkKeymapKey GdkKeymapKey; * letter at level 0, and an uppercase letter at level 1, though only the * uppercase letter is printed. * - * A #GdkKeymapKey is a hardware key that can be mapped to a keyval. + * A `GdkKeymapKey` is a hardware key that can be mapped to a keyval. */ struct _GdkKeymapKey { diff --git a/gdk/gdkvulkancontext.c b/gdk/gdkvulkancontext.c index 13ba8dae8b..5fe6ad6512 100644 --- a/gdk/gdkvulkancontext.c +++ b/gdk/gdkvulkancontext.c @@ -28,27 +28,18 @@ #include "gdkinternals.h" #include "gdkintl.h" -/** - * SECTION:gdkvulkancontext - * @Title: GdkVulkanContext - * @Short_description: Vulkan draw context - * - * #GdkVulkanContext is an object representing the platform-specific - * Vulkan draw context. - * - * #GdkVulkanContexts are created for a #GdkSurface using - * gdk_surface_create_vulkan_context(), and the context will match the - * the characteristics of the surface. - * - * Support for #GdkVulkanContext is platform-specific, context creation - * can fail, returning %NULL context. - */ - /** * GdkVulkanContext: * - * The GdkVulkanContext struct contains only private fields and should not - * be accessed directly. + * `GdkVulkanContext` is an object representing the platform-specific + * Vulkan draw context. + * + * `GdkVulkanContext`s are created for a surface using + * [method@Gdk.Surface.create_vulkan_context], and the context will match + * the the characteristics of the surface. + * + * Support for `GdkVulkanContext` is platform-specific and context creation + * can fail, returning %NULL context. */ typedef struct _GdkVulkanContextPrivate GdkVulkanContextPrivate; @@ -540,8 +531,9 @@ gdk_vulkan_context_class_init (GdkVulkanContextClass *klass) * GdkVulkanContext::images-updated: * @context: the object on which the signal is emitted * - * This signal is emitted when the images managed by this context have - * changed. Usually this means that the swapchain had to be recreated, + * Emitted when the images managed by this context have changed. + * + * Usually this means that the swapchain had to be recreated, * for example in response to a change of the surface size. */ signals[IMAGES_UPDATED] = @@ -650,7 +642,7 @@ gdk_vulkan_context_initable_init (GInitableIface *iface) /** * gdk_vulkan_context_get_instance: - * @context: a #GdkVulkanContext + * @context: a `GdkVulkanContext` * * Gets the Vulkan instance that is associated with @context. * @@ -666,7 +658,7 @@ gdk_vulkan_context_get_instance (GdkVulkanContext *context) /** * gdk_vulkan_context_get_physical_device: - * @context: a #GdkVulkanContext + * @context: a `GdkVulkanContext` * * Gets the Vulkan physical device that this context is using. * @@ -698,7 +690,7 @@ gdk_vulkan_context_get_device (GdkVulkanContext *context) /** * gdk_vulkan_context_get_queue: - * @context: a #GdkVulkanContext + * @context: a `GdkVulkanContext` * * Gets the Vulkan queue that this context is using. * @@ -714,9 +706,10 @@ gdk_vulkan_context_get_queue (GdkVulkanContext *context) /** * gdk_vulkan_context_get_queue_family_index: - * @context: a #GdkVulkanContext + * @context: a `GdkVulkanContext` * * Gets the family index for the queue that this context is using. + * * See vkGetPhysicalDeviceQueueFamilyProperties(). * * Returns: the index @@ -731,7 +724,7 @@ gdk_vulkan_context_get_queue_family_index (GdkVulkanContext *context) /** * gdk_vulkan_context_get_image_format: - * @context: a #GdkVulkanContext + * @context: a `GdkVulkanContext` * * Gets the image format that this context is using. * @@ -749,7 +742,7 @@ gdk_vulkan_context_get_image_format (GdkVulkanContext *context) /** * gdk_vulkan_context_get_n_images: - * @context: a #GdkVulkanContext + * @context: a `GdkVulkanContext` * * Gets the number of images that this context is using in its swap chain. * @@ -767,7 +760,7 @@ gdk_vulkan_context_get_n_images (GdkVulkanContext *context) /** * gdk_vulkan_context_get_image: - * @context: a #GdkVulkanContext + * @context: a `GdkVulkanContext` * @id: the index of the image to return * * Gets the image with index @id that this context is using. @@ -788,12 +781,12 @@ gdk_vulkan_context_get_image (GdkVulkanContext *context, /** * gdk_vulkan_context_get_draw_index: - * @context: a #GdkVulkanContext + * @context: a `GdkVulkanContext` * * Gets the index of the image that is currently being drawn. * - * This function can only be used between gdk_draw_context_begin_frame() and - * gdk_draw_context_end_frame() calls. + * This function can only be used between [method@Gdk.DrawContext.begin_frame] + * and [method@Gdk.DrawContext.end_frame] calls. * * Returns: the index of the images that is being drawn */ @@ -810,13 +803,13 @@ gdk_vulkan_context_get_draw_index (GdkVulkanContext *context) /** * gdk_vulkan_context_get_draw_semaphore: - * @context: a #GdkVulkanContext + * @context: a `GdkVulkanContext` * * Gets the Vulkan semaphore that protects access to the image that is * currently being drawn. * - * This function can only be used between gdk_draw_context_begin_frame() and - * gdk_draw_context_end_frame() calls. + * This function can only be used between [method@Gdk.DrawContext.begin_frame] + * and [method@Gdk.DrawContext.end_frame] calls. * * Returns: (transfer none): the VkSemaphore */