[gtk/ebassi/gidocgen: 88/500] docs: Rework the gdk docs
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk/ebassi/gidocgen: 88/500] docs: Rework the gdk docs
- Date: Thu, 11 Mar 2021 16:48:02 +0000 (UTC)
commit 9132f1831ce50177f35b7a3b6a98c8db0e20487c
Author: Matthias Clasen <mclasen redhat com>
Date: Sun Feb 21 00:13:57 2021 -0500
docs: Rework the gdk docs
Convert links, make things more concise.
gdk/gdkapplaunchcontext.c | 54 ++---
gdk/gdkcairocontext.c | 29 +--
gdk/gdkclipboard.c | 309 ++++++++++++------------
gdk/gdkcontentdeserializer.c | 97 +++++---
gdk/gdkcontentdeserializer.h | 6 +-
gdk/gdkcontentformats.c | 247 +++++++++----------
gdk/gdkcontentprovider.c | 84 ++++---
gdk/gdkcontentprovider.h | 6 -
gdk/gdkcontentserializer.c | 95 +++++---
gdk/gdkcontentserializer.h | 6 +-
gdk/gdkcursor.c | 135 +++++++----
gdk/gdkdevice.c | 248 +++++++++++--------
gdk/gdkdevicepad.c | 51 ++--
gdk/gdkdevicetool.c | 69 ++++--
gdk/gdkdevicetool.h | 5 -
gdk/gdkdisplaymanager.c | 134 ++++++-----
gdk/gdkdrag.c | 146 ++++++------
gdk/gdkdrag.h | 2 +-
gdk/gdkdragsurface.c | 7 +-
gdk/gdkdrawcontext.c | 99 ++++----
gdk/gdkdrop.c | 181 +++++++-------
gdk/gdkevents.c | 230 ++++++++++--------
gdk/gdkevents.h | 21 +-
gdk/gdkframeclock.c | 221 ++++++++---------
gdk/gdkframeclock.h | 8 +-
gdk/gdkframetimings.c | 115 ++++-----
gdk/gdkglcontext.c | 182 +++++++-------
gdk/gdkgltexture.c | 23 +-
gdk/gdkgltexture.h | 5 -
gdk/gdkmemorytexture.c | 13 +-
gdk/gdkmemorytexture.h | 24 +-
gdk/gdkmonitor.c | 144 ++++++++---
gdk/gdkpaintable.c | 202 +++++++++-------
gdk/gdkpaintable.h | 29 +--
gdk/gdkpopup.c | 63 +++--
gdk/gdkpopup.h | 5 -
gdk/gdkpopuplayout.c | 96 ++++----
gdk/gdkrectangle.c | 50 ++--
gdk/gdkrgba.c | 102 ++++----
gdk/gdkseat.c | 145 ++++++-----
gdk/gdksnapshot.c | 8 +
gdk/gdksnapshot.h | 5 -
gdk/gdksurface.c | 557 +++++++++++++++++++++++--------------------
gdk/gdktexture.c | 84 ++++---
gdk/gdktoplevel.c | 224 +++++++++++------
gdk/gdktoplevel.h | 19 +-
gdk/gdktoplevellayout.c | 12 +-
gdk/gdktoplevelsize.c | 37 +--
gdk/gdktypes.h | 31 +--
gdk/gdkvulkancontext.c | 53 ++--
50 files changed, 2528 insertions(+), 2190 deletions(-)
---
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` handles launching an application in a graphical context.
*
- * 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.
+ * It is an implementation of `GAppLaunchContext` that provides startup
+ * notification and allows to launch applications on a specific screen
+ * or workspace.
*
* ## Launching an application
*
- * |[<!-- language="C" -->
+ * ```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
@@ -28,23 +28,14 @@
#include "gdkinternals.h"
/**
- * SECTION:gdkcairocontext
- * @Title: GdkCairoContext
- * @Short_description: Cairo draw context
+ * GdkCairoContext:
*
- * #GdkCairoContext is an object representing the platform-specific
+ * `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`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
@@ -33,33 +33,25 @@
#include <gobject/gvaluecollector.h>
/**
- * 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.
+ * GdkClipboard:
*
- * 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().
+ * The `GdkClipboard` object represents data shared between applications or
+ * inside an application.
*
- * 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 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 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:
+ * 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.
*
- * The GdkClipboard struct contains only private fields and should not be
- * accessed directly.
+ * 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.
*
- * Returns if the clipboard is local. A clipboard is considered local if it was
- * last claimed by the running application.
+ * A clipboard is considered local if it was last claimed
+ * by the running application.
*
- * Note that gdk_clipboard_get_content() may return %NULL even on a local
- * clipboard. In this case the clipboard is empty.
+ * 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.
*
- * 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.
+ * 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.
+ *
+ * If the clipboard is not local, this function does nothing but report success.
+ *
+ * The @callback must call [method@Gdk.Clipboard.store_finish].
*
- * This function is called automatically when gtk_main() or #GtkApplication
- * exit, so you likely don't need to call it.
- **/
+ * 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.
*
- * Finishes an asynchronous clipboard store started with gdk_clipboard_store_async().
+ * 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.
*
- * Finishes an asynchronous clipboard read started with gdk_clipboard_read_async().
+ * See [method@Gdk.Clipboard.read_async].
*
- * Returns: (transfer full) (nullable): a #GInputStream or %NULL on error.
- **/
+ * 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.
*
- * Finishes an asynchronous clipboard read started with
- * gdk_clipboard_read_value_async().
+ * See [method@Gdk.Clipboard.read_value_async].
*
- * Returns: (transfer none): a #GValue containing the result.
- **/
+ * 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`.
+ *
+ * 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 gdk_clipboard_read_value_async(). Use
- * that function or gdk_clipboard_read_async() directly if you need more
- * control over the operation.
- **/
+ * 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.
*
- * Finishes an asynchronous clipboard read started with
- * gdk_clipboard_read_texture_async().
+ * See [method@Gdk.Clipboard.read_texture_async].
*
- * Returns: (transfer full) (nullable): a new #GdkTexture or %NULL on error.
- **/
+ * 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 I/O priority for the current operation.
*
- * Gets the io priority that was passed to gdk_content_deserialize_async().
+ * This is the priority that was passed to [funccontent_deserialize_async].
*
- * Returns: the io priority for the current operation
+ * 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 for the current operation.
*
- * Gets the cancellable that was passed to gdk_content_deserialize_async().
+ * 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
- *
- * 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.
- *
- * GDK supports content in 2 forms: #GType and mime type.
- * Using #GTypes is meant only for in-process content transfers. Mime types
+ * GdkContentFormats:
+ *
+ * The `GdkContentFormats` structure is used to advertise and negotiate the
+ * format of content.
+ *
+ * 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.
- *
- * #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:
+ * 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.
*
- * 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.
+ *
+ * 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
+ * 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.
*
- * Finishes an asynchronous write operation started with
- * gdk_content_provider_write_mime_type_async().
+ * 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 I/O priority for the current operation.
*
- * Gets the io priority that was passed to gdk_content_serialize_async().
+ * This is the priority that was passed to [func@content_serialize_async].
*
- * Returns: the io priority for the current operation
+ * 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 the current operation.
*
- * Gets the data that was associated with @serializer via gdk_content_serializer_set_task_data().
+ * 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 <errno.h>
/**
- * SECTION:gdkcursor
- * @Short_description: Named and texture cursors
- * @Title: Cursors
+ * GdkCursor:
+ *
+ * `GdkCursor` is used to create and destroy cursors.
*
- * `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 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"
* -  "help"
@@ -319,7 +344,7 @@ gdk_cursor_equal (gconstpointer a,
* -  "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.
*
- * Returns the name of the cursor. If the cursor is not a named cursor, %NULL
- * will be returned.
+ * 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
+ * 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.
*
- * Returns the horizontal offset of the hotspot. The hotspot indicates the
- * pixel that will be directly above the cursor.
+ * 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.
*
- * Returns the vertical offset of the hotspot. The hotspot indicates the
- * pixel that will be directly above the cursor.
+ * 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`
+ *
+ * Emitted either when the the number of either axes or keys changes.
*
- * 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
+ * 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.
*
- * 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.
+ * This ID is retrieved from the device, and does not change.
*
- * This function, together with gdk_device_get_product_id(), can be used to eg.
- * compose #GSettings paths to store settings for this device.
+ * This function, together with [method@Gdk.Device.get_product_id],
+ * can be used to eg. compose `GSettings` paths to store settings
+ * for this device.
*
- * |[<!-- language="C" -->
+ * ```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.
*
- * 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.
+ * 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.
*
- * Retrieves whether the Caps Lock modifier of the
- * keyboard is locked, if @device is a keyboard device.
+ * 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.
*
- * Retrieves whether the Scroll Lock modifier of the
- * keyboard is locked, if @device is a keyboard device.
+ * 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.
*
- * Returns the direction of effective layout of the keyboard,
- * if @device is a keyboard device.
+ * 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 layouts for both right-to-left and
+ * left-to-right languages are in use on the keyboard.
*
- * 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.
+ * 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.
*
- * 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,
+ * 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}
- *
- * |[<!-- language="C" -->
+ * ```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,
- * |[<!-- language="C" -->
- * gdk_set_allowed_backends ("wayland,quartz,*");
- * ]|
- * instructs GDK to try the Wayland backend first,
- * followed by the Quartz backend, and then all
- * others.
- *
- * 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 x11, win32, quartz,
- * broadway, wayland. You can also include a * in the
- * list to try all remaining backends.
- *
- * This call must happen prior to gdk_display_open(),
- * gtk_init(), or gtk_init_check()
+ * For example:
+ *
+ * ```c
+ * gdk_set_allowed_backends ("wayland,macos,*");
+ * ```
+ *
+ * instructs GDK to try the Wayland backend first, followed by the
+ * MacOs backend, and then all others.
+ *
+ * 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).
+ *
+ * Applications can use [func@set_allowed_backends] to limit what
+ * backends wil be used.
*
- * Returns: (transfer none): The global #GdkDisplayManager singleton
- **/
+ * 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.
*
- * You will always interact with one of those subclasses.
+ * `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.
*
- * A GdkDrawContext is always associated with a single toplevel surface.
- */
-
-/**
- * GdkDrawContext:
+ * You will always interact with one of those subclasses.
*
- * 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.
*
- * 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.
+ * 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 gdk_draw_context_begin_frame()
- * and gdk_draw_context_end_frame() calls.
+ * 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().
*
- * 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.
+ * This makes the drawing available on screen.
+ * See [method@Gdk.DrawContext.begin_frame] for more details about drawing.
*
- * When using a #GdkGLContext, this function may call `glFlush()`
+ * 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
- *
- * 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
+ * @self: a `GdkDrop`
+ *
+ * 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.
+ *
+ * See [method Gdk Drop.read_async].
*
- * Returns: (nullable) (transfer full): the #GInputStream, or %NULL
+ * 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.
*
- * Finishes an async drop read started with
- * gdk_drop_read_value_async().
+ * See [method Gdk Drop.read_value_async].
*
- * Returns: (transfer none): a #GValue containing the result.
- **/
+ * 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.
*
- * Returns whether this event is an 'emulated' pointer event (typically
- * from a touch event), as opposed to a real one.
+ * 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
+ *
+ * Returns whether a `GdkEvent` should trigger a context menu,
+ * according to platform conventions.
*
- * This function returns whether a #GdkEvent should trigger a
- * context menu, according to platform conventions. The right
- * mouse button always triggers context menus.
+ * 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`
+ *
+ * Returns a `GdkDeviceTool` representing the tool that
+ * caused the event.
*
- * 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.
+ * If the was not generated by a device that supports
+ * different tools (such as a tablet), this function will
+ * return %NULL.
*
- * Note: the #GdkDeviceTools will be constant during
+ * 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`
+ *
+ * Retuns the event sequence to which the event belongs.
*
- * If @event is a touch event, returns the #GdkEventSequence
- * to which the event belongs. Otherwise, return %NULL.
+ * 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
- *
- * 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.
- *
- * #GdkFrameClock is designed to be compatible with an OpenGL-based
- * implementation or with mozRequestAnimationFrame in Firefox,
- * for example.
+ * 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.
+ *
+ * `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.
*
- * Gets the time that should currently be used for animations. Inside
- * the processing of a frame, it’s the time used to compute the
+ * 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
- *
- * 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.
+ * @frame_clock: a `GdkFrameClock`
+ *
+ * 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.
*
- * 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().
+ * 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
- * gdk_frame_clock_get_history_start().
+ * 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`
+ *
+ * Returns whether @timings are complete.
*
- * The timing information in a #GdkFrameTimings is filled in
+ * 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.
*
- * Reurns the presentation time. This is the time at which the frame
- * became visible to the user.
+ * 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
- *
- * 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.
+ * @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 [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:
*
- * |[<!-- language="C" -->
- * 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 whether the context is doing extra validations and runtime checking.
*
- * Retrieves the value set using gdk_gl_context_set_debug_enabled().
+ * 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 whether the context is forward-compatible.
*
- * Retrieves the value set using gdk_gl_context_set_forward_compatible().
+ * See [method@Gdk.GLContext.set_forward_compatible].
*
- * Returns: %TRUE if the context should be 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 <epoxy/gl.h>
+/**
+ * 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.
+ *
+ * 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.
+ * 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 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:
+ *
+ * `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.
- *
- * 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.
- *
- * 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` 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 [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
+ * [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 <errno.h>
#include <math.h>
-/**
- * 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.
*
- * Checks if an @rgba value is transparent. That is, drawing with the value
- * would not produce any change.
+ * 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.
*
- * Checks if an @rgba value is opaque. That is, drawing with the value
- * will not retain any results from previous contents.
+ * 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.
*
- * Releases a grab added through gdk_seat_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
@@ -52,27 +52,17 @@
#endif
/**
- * SECTION:gdksurface
- * @Short_description: Onscreen display areas in the target window system
- * @Title: Surfaces
- * @See_also: #GdkToplevel, #GdkPopup
+ * GdkSurface:
*
- * 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.
+ * A `GdkSurface` is a rectangular region on the screen.
*
- * 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:
+ * It’s a low-level object, used to implement high-level objects
+ * such as [class@Gtk.Window] or [class@Gtk.Dialog] in GTK.
*
- * The GdkSurface struct contains only private fields and
- * should not be accessed directly.
+ * 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
- * destroyed, but the children’s reference counts are not decremented.
+ * Destroys the window system resources associated with @surface and
+ * decrements @surface's reference count.
*
- * Note that a surface will not be destroyed automatically when its reference count
- * reaches zero. You must call this function yourself before that happens.
+ * 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.
+ */
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.
*
- * Checks whether the surface has been mapped (with gdk_toplevel_present()
- * or gdk_popup_present()).
+ * 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 layout phase from the surface's frame clock.
*
- * Request a %GDK_FRAME_CLOCK_PHASE_LAYOUT from the surface's
- * frame clock. See gdk_frame_clock_request_phase().
+ * 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
- *
- * A convenience wrapper around gdk_surface_invalidate_region()
- * which invalidates a rectangular region.
- * See gdk_surface_invalidate_region() for details.
- **/
+ * @surface: a `GdkSurface`
+ * @rect: (allow-none): rectangle to invalidate or %NULL to
+ * invalidate the whole surface
+ *
+ * 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.
*
- * Adds @region to the update area for @surface. The update area is
- * the region that needs to be redrawn, or “dirty region.”
+ * 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.
- **/
+ * 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 and modifier state.
*
- * Obtains the current device position in doubles and modifier state.
- * The position is given in coordinates relative to the upper left
- * corner of @surface.
+ * 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
+ * `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.
+ * 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 gdk_surface_set_cursor() to unset the
- * cursor of the 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.
- *
- * 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.
- *
- * 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
- **/
+ * @surface: a `GdkSurface`
+ * @device: a pointer `GdkDevice`
+ *
+ * Retrieves a `GdkCursor` pointer for the @device currently set on the
+ * specified `GdkSurface`.
+ *
+ * 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
- *
- * 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.
- **/
+ * @surface: a `GdkSurface`
+ * @device: a pointer `GdkDevice`
+ * @cursor: a `GdkCursor`
+ *
+ * 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.
*
- * 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().
- **/
+ * 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.
*
- * #GdkTexture is the basic element used to refer to pixel data.
- * It is primarily mean for pixel data that will not change over
+ * 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:
- * |[<!-- language="C" -->
+ * ```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 <math.h>
/**
- * 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.
*
- * 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.
+ * 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
@@ -29,28 +29,19 @@
#include "gdkintl.h"
/**
- * SECTION:gdkvulkancontext
- * @Title: GdkVulkanContext
- * @Short_description: Vulkan draw context
+ * GdkVulkanContext:
*
- * #GdkVulkanContext is an object representing the platform-specific
+ * `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.
+ * `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, context creation
+ * Support for `GdkVulkanContext` is platform-specific and context creation
* can fail, returning %NULL context.
*/
-/**
- * GdkVulkanContext:
- *
- * The GdkVulkanContext struct contains only private fields and should not
- * be accessed directly.
- */
-
typedef struct _GdkVulkanContextPrivate GdkVulkanContextPrivate;
struct _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
*/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
