AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

docs: Rework the gdk docs

Browse Source 
Convert links, make things more concise.
This commit is contained in:
Matthias Clasen 2021-02-21 00:13:57 -05:00 committed by Emmanuele Bassi
parent 3d04c0f4be
commit 9132f1831c
50 changed files with 2518 additions and 2180 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
gdk/gdkapplaunchcontext.c
View File

@ -26,18 +26,17 @@
/**
* SECTION:gdkapplaunchcontext
* @Short_description: Startup notification for applications
* @Title: Application launching
* GdkAppLaunchContext:
*
* GdkAppLaunchContext is an implementation of #GAppLaunchContext that
* handles launching an application in a graphical context. It provides
* startup notification and allows to launch applications on a specific
* screen or workspace.
* `GdkAppLaunchContext` handles launching an application in a graphical context.
*
* It is an implementation of `GAppLaunchContext` that provides startup
* notification and allows to launch applications on a specific screen
* or workspace.
*
* ## Launching an application
*
* |[<!-- 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

31
gdk/gdkcairocontext.c
View File

@ -27,24 +27,15 @@
#include "gdkcairo.h"
#include "gdkinternals.h"
/**
* SECTION:gdkcairocontext
* @Title: GdkCairoContext
* @Short_description: Cairo draw context
*
* #GdkCairoContext is an object representing the platform-specific
* draw context.
*
* #GdkCairoContexts are created for a #GdkDisplay using
* gdk_surface_create_cairo_context(), and the context can then be used
* to draw on that #GdkSurface.
*/
/**
* GdkCairoContext:
*
* The GdkCairoContext struct contains only private fields and should not
* be accessed directly.
* `GdkCairoContext` is an object representing the platform-specific
* draw context.
*
* `GdkCairoContext`s are created for a surface using
* [method@Gdk.Surface.create_cairo_context], and the context can then be used
* to draw on that surface.
*/
typedef struct _GdkCairoContextPrivate GdkCairoContextPrivate;
@ -70,15 +61,17 @@ gdk_cairo_context_init (GdkCairoContext *self)
* gdk_cairo_context_cairo_create:
* @self: a #GdkCairoContext that is currently drawing
*
* Retrieves a Cairo context to be used to draw on the #GdkSurface
* of @context. A call to gdk_draw_context_begin_frame() with this
* Retrieves a Cairo context to be used to draw on the `GdkSurface`
* of @context.
*
* A call to [method@Gdk.DrawContext.begin_frame] with this
* @context must have been done or this function will return %NULL.
*
* The returned context is guaranteed to be valid until
* gdk_draw_context_end_frame() is called.
* [method@Gdk.DrawContext.end_frame] is called.
*
* Returns: (transfer full) (nullable): a Cairo context to be used
* to draw the contents of the #GdkSurface. %NULL is returned
* to draw the contents of the `GdkSurface`. %NULL is returned
* when @context is not drawing.
*/
cairo_t *

313
gdk/gdkclipboard.c
View File

@ -32,34 +32,26 @@
#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.
*
* To get a GdkClipboard object, use gdk_display_get_clipboard() or
* gdk_display_get_primary_clipboard(). You can find out about the data that
* is currently available in a clipboard using gdk_clipboard_get_formats().
*
* To make text or image data available in a clipboard, use gdk_clipboard_set_text() or
* gdk_clipboard_set_texture(). For other data, you can use gdk_clipboard_set_content(),
* which takes a #GdkContentProvider object.
*
* To read textual or image data from a clipboard, use gdk_clipboard_read_text_async() or
* gdk_clipboard_read_texture_async(). For other data, use gdk_clipboard_read_async(),
* which provides a #GInputStream object.
*/
/**
* GdkClipboard:
*
* The GdkClipboard struct contains only private fields and should not be
* accessed directly.
* The `GdkClipboard` object represents data shared between applications or
* inside an application.
*
* To get a `GdkClipboard` object, use [method@Gdk.Display.get_clipboard] or
* [method@Gdk.Display.get_primary_clipboard]. You can find out about the data
* that is currently available in a clipboard using
* [method@Gdk.Clipboard.get_formats].
*
* To make text or image data available in a clipboard, use
* [method@Gdk.Clipboard.set_text] or [method@Gdk.Clipboard.set_texture].
* For other data, you can use [method@Gdk.Clipboard.set_content], which
* takes a [class@Gdk.ContentProvider] object.
*
* To read textual or image data from a clipboard, use
* [method@Gdk.Clipboard.read_text_async] or
* [method@Gdk.Clipboard.read_texture_async]. For other data, use
* [method@Gdk.Clipboard.read_async], which provides a `GInputStream` object.
*/
typedef struct _GdkClipboardPrivate GdkClipboardPrivate;
@ -362,7 +354,7 @@ gdk_clipboard_class_init (GdkClipboardClass *class)
/**
* GdkClipboard:display:
*
* The #GdkDisplay that the clipboard belongs to.
* The `GdkDisplay` that the clipboard belongs to.
*/
properties[PROP_DISPLAY] =
g_param_spec_object ("display",
@ -405,7 +397,7 @@ gdk_clipboard_class_init (GdkClipboardClass *class)
/**
* GdkClipboard:content:
*
* The #GdkContentProvider or %NULL if the clipboard is empty or contents are
* The `GdkContentProvider` or %NULL if the clipboard is empty or contents are
* provided otherwise.
*/
properties[PROP_CONTENT] =
@ -421,7 +413,7 @@ gdk_clipboard_class_init (GdkClipboardClass *class)
* GdkClipboard::changed:
* @clipboard: the object on which the signal was emitted
*
* The ::changed signal is emitted when the clipboard changes ownership.
* Emitted when the clipboard changes ownership.
*/
signals[CHANGED] =
g_signal_new ("changed",
@ -445,12 +437,12 @@ gdk_clipboard_init (GdkClipboard *clipboard)
/**
* gdk_clipboard_get_display:
* @clipboard: a #GdkClipboard
* @clipboard: a `GdkClipboard`
*
* Gets the #GdkDisplay that the clipboard was created for.
* Gets the `GdkDisplay` that the clipboard was created for.
*
* Returns: (transfer none): a #GdkDisplay
**/
* Returns: (transfer none): a `GdkDisplay`
*/
GdkDisplay *
gdk_clipboard_get_display (GdkClipboard *clipboard)
{
@ -463,12 +455,12 @@ gdk_clipboard_get_display (GdkClipboard *clipboard)
/**
* gdk_clipboard_get_formats:
* @clipboard: a #GdkClipboard
* @clipboard: a `GdkClipboard`
*
* Gets the formats that the clipboard can provide its current contents in.
*
* Returns: (transfer none): The formats of the clipboard
**/
*/
GdkContentFormats *
gdk_clipboard_get_formats (GdkClipboard *clipboard)
{
@ -481,16 +473,18 @@ gdk_clipboard_get_formats (GdkClipboard *clipboard)
/**
* gdk_clipboard_is_local:
* @clipboard: a #GdkClipboard
* @clipboard: a `GdkClipboard`
*
* Returns if the clipboard is local. A clipboard is considered local if it was
* last claimed by the running application.
* Returns if the clipboard is local.
*
* Note that gdk_clipboard_get_content() may return %NULL even on a local
* clipboard. In this case the clipboard is empty.
* A clipboard is considered local if it was last claimed
* by the running application.
*
* Note that [method@Gdk.Clipboard.get_content] may return %NULL
* even on a local clipboard. In this case the clipboard is empty.
*
* Returns: %TRUE if the clipboard is local
**/
*/
gboolean
gdk_clipboard_is_local (GdkClipboard *clipboard)
{
@ -503,15 +497,16 @@ gdk_clipboard_is_local (GdkClipboard *clipboard)
/**
* gdk_clipboard_get_content:
* @clipboard: a #GdkClipboard
* @clipboard: a `GdkClipboard`
*
* Returns the #GdkContentProvider currently set on @clipboard. If the
* @clipboard is empty or its contents are not owned by the current process,
* %NULL will be returned.
* Returns the `GdkContentProvider` currently set on @clipboard.
*
* If the @clipboard is empty or its contents are not owned by the
* current process, %NULL will be returned.
*
* Returns: (transfer none) (nullable): The content of a clipboard or %NULL
* if the clipboard does not maintain any content.
**/
*/
GdkContentProvider *
gdk_clipboard_get_content (GdkClipboard *clipboard)
{
@ -524,20 +519,26 @@ gdk_clipboard_get_content (GdkClipboard *clipboard)
/**
* gdk_clipboard_store_async:
* @clipboard: a #GdkClipboard
* @io_priority: the [I/O priority][io-priority]
* of the request.
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @clipboard: a `GdkClipboard`
* @io_priority: the I/O priority of the request.
* @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
* @callback: (scope async): callback to call when the request is satisfied
* @user_data: (closure): the data to pass to callback function
*
* Asynchronously instructs the @clipboard to store its contents remotely to
* preserve them for later usage. If the clipboard is not local, this function
* does nothing but report success.
* Asynchronously instructs the @clipboard to store its contents remotely.
*
* This function is called automatically when gtk_main() or #GtkApplication
* exit, so you likely don't need to call it.
**/
* If the clipboard is not local, this function does nothing but report success.
*
* The @callback must call [method@Gdk.Clipboard.store_finish].
*
* The purpose of this call is to preserve clipboard contents beyond the
* lifetime of an application, so this function is typically called on
* exit. Depending on the platform, the functionality may not be available
* unless a "clipboard manager" is running.
*
* This function is called automatically when a [class@Gtk.Application] is
* shut down, so you likely don't need to call it.
*/
void
gdk_clipboard_store_async (GdkClipboard *clipboard,
int io_priority,
@ -571,15 +572,16 @@ gdk_clipboard_store_async (GdkClipboard *clipboard,
/**
* gdk_clipboard_store_finish:
* @clipboard: a #GdkClipboard
* @result: a #GAsyncResult
* @error: a #GError location to store the error occurring, or %NULL to
* ignore.
* @clipboard: a `GdkClipboard`
* @result: a `GAsyncResult`
* @error: a `GError` location to store the error occurring, or %NULL to ignore.
*
* Finishes an asynchronous clipboard store started with gdk_clipboard_store_async().
* Finishes an asynchronous clipboard store.
*
* See [method@Gdk.Clipboard.store_async].
*
* Returns: %TRUE if storing was successful.
**/
*/
gboolean
gdk_clipboard_store_finish (GdkClipboard *clipboard,
GAsyncResult *result,
@ -632,22 +634,22 @@ gdk_clipboard_read_internal (GdkClipboard *clipboard,
/**
* gdk_clipboard_read_async:
* @clipboard: a #GdkClipboard
* @clipboard: a `GdkClipboard`
* @mime_types: a %NULL-terminated array of mime types to choose from
* @io_priority: the [I/O priority][io-priority]
* of the request.
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @io_priority: the I/O priority of the request
* @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
* @callback: (scope async): callback to call when the request is satisfied
* @user_data: (closure): the data to pass to callback function
*
* Asynchronously requests an input stream to read the @clipboard's
* contents from. When the operation is finished @callback will be called.
* You can then call gdk_clipboard_read_finish() to get the result of the
* operation.
* contents from.
*
* When the operation is finished @callback will be called. You must then
* call [method@Gdk.Clipboard.read_finish] to get the result of the operation.
*
* The clipboard will choose the most suitable mime type from the given list
* to fulfill the request, preferring the ones listed first.
**/
* to fulfill the request, preferring the ones listed first.
*/
void
gdk_clipboard_read_async (GdkClipboard *clipboard,
const char **mime_types,
@ -672,17 +674,18 @@ gdk_clipboard_read_async (GdkClipboard *clipboard,
/**
* gdk_clipboard_read_finish:
* @clipboard: a #GdkClipboard
* @result: a #GAsyncResult
* @clipboard: a `GdkClipboard`
* @result: a `GAsyncResult`
* @out_mime_type: (out) (allow-none) (transfer none): pointer to store
* the chosen mime type in or %NULL
* @error: a #GError location to store the error occurring, or %NULL to
* ignore.
* @error: a `GError` location to store the error occurring, or %NULL to ignore.
*
* Finishes an asynchronous clipboard read started with gdk_clipboard_read_async().
* Finishes an asynchronous clipboard read.
*
* Returns: (transfer full) (nullable): a #GInputStream or %NULL on error.
**/
* See [method@Gdk.Clipboard.read_async].
*
* Returns: (transfer full) (nullable): a `GInputStream` or %NULL on error.
*/
GInputStream *
gdk_clipboard_read_finish (GdkClipboard *clipboard,
GAsyncResult *result,
@ -827,23 +830,23 @@ gdk_clipboard_read_value_internal (GdkClipboard *clipboard,
/**
* gdk_clipboard_read_value_async:
* @clipboard: a #GdkClipboard
* @type: a #GType to read
* @io_priority: the [I/O priority][io-priority]
* of the request.
* @clipboard: a `GdkClipboard`
* @type: a `GType` to read
* @io_priority: the I/O priority of the request
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @callback: (scope async): callback to call when the request is satisfied
* @user_data: (closure): the data to pass to callback function
*
* Asynchronously request the @clipboard contents converted to the given
* @type. When the operation is finished @callback will be called.
* You can then call gdk_clipboard_read_value_finish() to get the resulting
* #GValue.
* @type.
*
* For local clipboard contents that are available in the given #GType, the
* value will be copied directly. Otherwise, GDK will try to use
* gdk_content_deserialize_async() to convert the clipboard's data.
**/
* When the operation is finished @callback will be called. You must then call
* [method@Gdk.Clipboard.read_value_finish] to get the resulting `GValue`.
*
* For local clipboard contents that are available in the given `GType`,
* the value will be copied directly. Otherwise, GDK will try to use
* [func@content_deserialize_async] to convert the clipboard's data.
*/
void
gdk_clipboard_read_value_async (GdkClipboard *clipboard,
GType type,
@ -867,16 +870,16 @@ gdk_clipboard_read_value_async (GdkClipboard *clipboard,
/**
* gdk_clipboard_read_value_finish:
* @clipboard: a #GdkClipboard
* @result: a #GAsyncResult
* @error: a #GError location to store the error occurring, or %NULL to
* ignore.
* @clipboard: a `GdkClipboard`
* @result: a `GAsyncResult`
* @error: a GError` location to store the error occurring, or %NULL to ignore
*
* Finishes an asynchronous clipboard read started with
* gdk_clipboard_read_value_async().
* Finishes an asynchronous clipboard read.
*
* Returns: (transfer none): a #GValue containing the result.
**/
* See [method@Gdk.Clipboard.read_value_async].
*
* Returns: (transfer none): a `GValue` containing the result.
*/
const GValue *
gdk_clipboard_read_value_finish (GdkClipboard *clipboard,
GAsyncResult *result,
@ -891,19 +894,20 @@ gdk_clipboard_read_value_finish (GdkClipboard *clipboard,
/**
* gdk_clipboard_read_texture_async:
* @clipboard: a #GdkClipboard
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @clipboard: a `GdkClipboard`
* @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
* @callback: (scope async): callback to call when the request is satisfied
* @user_data: (closure): the data to pass to callback function
*
* Asynchronously request the @clipboard contents converted to a #GdkPixbuf.
* When the operation is finished @callback will be called. You can then
* call gdk_clipboard_read_texture_finish() to get the result.
* Asynchronously request the @clipboard contents converted to a `GdkPixbuf`.
*
* This is a simple wrapper around gdk_clipboard_read_value_async(). Use
* that function or gdk_clipboard_read_async() directly if you need more
* control over the operation.
**/
* When the operation is finished @callback will be called. You must then
* call [method@Gdk.Clipboard.read_texture_finish] to get the result.
*
* This is a simple wrapper around [method@Gdk.Clipboard.read_value_async].
* Use that function or [methos@Gdk.Clipboard.read_async] directly if you
* need more control over the operation.
*/
void
gdk_clipboard_read_texture_async (GdkClipboard *clipboard,
GCancellable *cancellable,
@ -925,16 +929,16 @@ gdk_clipboard_read_texture_async (GdkClipboard *clipboard,
/**
* gdk_clipboard_read_texture_finish:
* @clipboard: a #GdkClipboard
* @result: a #GAsyncResult
* @error: a #GError location to store the error occurring, or %NULL to
* ignore.
* @clipboard: a `GdkClipboard`
* @result: a `GAsyncResult`
* @error: a `GError` location to store the error occurring, or %NULL to ignore
*
* Finishes an asynchronous clipboard read started with
* gdk_clipboard_read_texture_async().
* Finishes an asynchronous clipboard read.
*
* Returns: (transfer full) (nullable): a new #GdkTexture or %NULL on error.
**/
* See [method@Gdk.Clipboard.read_texture_async].
*
* Returns: (transfer full) (nullable): a new `GdkTexture` or %NULL on error
*/
GdkTexture *
gdk_clipboard_read_texture_finish (GdkClipboard *clipboard,
GAsyncResult *result,
@ -955,19 +959,20 @@ gdk_clipboard_read_texture_finish (GdkClipboard *clipboard,
/**
* gdk_clipboard_read_text_async:
* @clipboard: a #GdkClipboard
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @clipboard: a `GdkClipboard`
* @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore
* @callback: (scope async): callback to call when the request is satisfied
* @user_data: (closure): the data to pass to callback function
*
* Asynchronously request the @clipboard contents converted to a string.
* When the operation is finished @callback will be called. You can then
* call gdk_clipboard_read_text_finish() to get the result.
*
* This is a simple wrapper around gdk_clipboard_read_value_async(). Use
* that function or gdk_clipboard_read_async() directly if you need more
* control over the operation.
**/
* When the operation is finished @callback will be called. You must then
* call [method@Gdk.Clipboard.read_text_finish] to get the result.
*
* This is a simple wrapper around [method@Gdk.Clipboard.read_value_async].
* Use that function or [method@Gdk.Clipboard.read_async] directly if you
* need more control over the operation.
*/
void
gdk_clipboard_read_text_async (GdkClipboard *clipboard,
GCancellable *cancellable,
@ -989,16 +994,16 @@ gdk_clipboard_read_text_async (GdkClipboard *clipboard,
/**
* gdk_clipboard_read_text_finish:
* @clipboard: a #GdkClipboard
* @result: a #GAsyncResult
* @error: a #GError location to store the error occurring, or %NULL to
* ignore.
* @clipboard: a `GdkClipboard`
* @result: a `GAsyncResult`
* @error: a `GError` location to store the error occurring, or %NULL to ignore
*
* Finishes an asynchronous clipboard read started with
* gdk_clipboard_read_text_async().
* Finishes an asynchronous clipboard read.
*
* Returns: (transfer full) (nullable): a new string or %NULL on error.
**/
* See [method@Gdk.Clipboard.read_text_async].
*
* Returns: (transfer full) (nullable): a new string or %NULL on error
*/
char *
gdk_clipboard_read_text_finish (GdkClipboard *clipboard,
GAsyncResult *result,
@ -1188,13 +1193,14 @@ gdk_clipboard_claim_remote (GdkClipboard *clipboard,
/**
* gdk_clipboard_set_content:
* @clipboard: a #GdkClipboard
* @clipboard: a `GdkClipboard`
* @provider: (transfer none) (allow-none): the new contents of @clipboard or
* %NULL to clear the clipboard
*
* Sets a new content provider on @clipboard. The clipboard will claim the
* #GdkDisplay's resources and advertise these new contents to other
* applications.
* Sets a new content provider on @clipboard.
*
* The clipboard will claim the `GdkDisplay`'s resources and advertise
* these new contents to other applications.
*
* In the rare case of a failure, this function will return %FALSE. The
* clipboard will then continue reporting its old contents and ignore
@ -1205,7 +1211,7 @@ gdk_clipboard_claim_remote (GdkClipboard *clipboard,
* transfer the contents and then request that format from @provider.
*
* Returns: %TRUE if setting the clipboard succeeded
**/
*/
gboolean
gdk_clipboard_set_content (GdkClipboard *clipboard,
GdkContentProvider *provider)
@ -1242,16 +1248,19 @@ gdk_clipboard_set_content (GdkClipboard *clipboard,
/**
* gdk_clipboard_set:
* @clipboard: a #GdkClipboard
* @clipboard: a `GdkClipboard`
* @type: type of value to set
* @...: value contents conforming to @type
*
* Sets the clipboard to contain the value collected from the given
* varargs.
**/
* Sets the clipboard to contain the value collected from the given varargs.
*
* ```c
* gdk_clipboard_set (clipboard, GTK_TYPE_TEXT_BUFFER, buffer);
* ```
*/
void
gdk_clipboard_set (GdkClipboard *clipboard,
GType type,
gdk_clipboard_set (GdkClipboard *clipboard,
GType type,
...)
{
va_list args;
@ -1265,13 +1274,12 @@ gdk_clipboard_set (GdkClipboard *clipboard,
/**
* gdk_clipboard_set_valist: (skip)
* @clipboard: a #GdkClipboard
* @clipboard: a `GdkClipboard`
* @type: type of value to set
* @args: varargs containing the value of @type
*
* Sets the clipboard to contain the value collected from the given
* @args.
**/
* Sets the clipboard to contain the value collected from the given @args.
*/
void
gdk_clipboard_set_valist (GdkClipboard *clipboard,
GType type,
@ -1301,11 +1309,11 @@ gdk_clipboard_set_valist (GdkClipboard *clipboard,
/**
* gdk_clipboard_set_value: (rename-to gdk_clipboard_set)
* @clipboard: a #GdkClipboard
* @value: a #GValue to set
* @clipboard: a `GdkClipboard`
* @value: a `GValue` to set
*
* Sets the @clipboard to contain the given @value.
**/
*/
void
gdk_clipboard_set_value (GdkClipboard *clipboard,
const GValue *value)
@ -1323,11 +1331,11 @@ gdk_clipboard_set_value (GdkClipboard *clipboard,
/**
* gdk_clipboard_set_text: (skip)
* @clipboard: a #GdkClipboard
* @clipboard: a `GdkClipboard`
* @text: Text to put into the clipboard
*
* Puts the given @text into the clipboard.
**/
*/
void
gdk_clipboard_set_text (GdkClipboard *clipboard,
const char *text)
@ -1339,11 +1347,11 @@ gdk_clipboard_set_text (GdkClipboard *clipboard,
/**
* gdk_clipboard_set_texture: (skip)
* @clipboard: a #GdkClipboard
* @texture: a #GdkTexture to put into the clipboard
* @clipboard: a `GdkClipboard`
* @texture: a `GdkTexture` to put into the clipboard
*
* Puts the given @texture into the clipboard.
**/
*/
void
gdk_clipboard_set_texture (GdkClipboard *clipboard,
GdkTexture *texture)
@ -1353,4 +1361,3 @@ gdk_clipboard_set_texture (GdkClipboard *clipboard,
gdk_clipboard_set (clipboard, GDK_TYPE_TEXTURE, texture);
}

97
gdk/gdkcontentdeserializer.c
View File

@ -30,13 +30,19 @@
/**
* SECTION:gdkcontentdeserializer
* @Short_description: Deserialize content for transfer
* @Title: GdkContentDeserializer
* @See_also: #GdkContentSerializer
* GdkContentDeserializer:
*
* A GdkContentDeserializer is used to deserialize content received via
* A `GdkContentDeserializer` is used to deserialize content received via
* inter-application data transfers.
*
* The `GdkContentDeserializer` transforms serialized content that is
* identified by a mime type into an object identified by a GType.
*
* GTK provides serializers and deserializers for common data types
* such as text, colors, images or file lists. To register your own
* deserialization functions, use [func@content_register_deserializer].
*
* Also see [class@Gdk.ContentSerializer].
*/
typedef struct _Deserializer Deserializer;
@ -166,7 +172,7 @@ gdk_content_deserializer_run (const char *mime_type,
/**
* gdk_content_deserializer_get_mime_type:
* @deserializer: a #GdkContentDeserializer
* @deserializer: a `GdkContentDeserializer`
*
* Gets the mime type to deserialize from.
*
@ -182,7 +188,7 @@ gdk_content_deserializer_get_mime_type (GdkContentDeserializer *deserializer)
/**
* gdk_content_deserializer_get_gtype:
* @deserializer: a #GdkContentDeserializer
* @deserializer: a `GdkContentDeserializer`
*
* Gets the GType to create an instance of.
*
@ -198,11 +204,11 @@ gdk_content_deserializer_get_gtype (GdkContentDeserializer *deserializer)
/**
* gdk_content_deserializer_get_value:
* @deserializer: a #GdkContentDeserializer
* @deserializer: a `GdkContentDeserializer`
*
* Gets the #GValue to store the deserialized object in.
* Gets the `GValue` to store the deserialized object in.
*
* Returns: (transfer none): the #GValue for the current operation
* Returns: (transfer none): the `GValue` for the current operation
*/
GValue *
gdk_content_deserializer_get_value (GdkContentDeserializer *deserializer)
@ -214,9 +220,11 @@ gdk_content_deserializer_get_value (GdkContentDeserializer *deserializer)
/**
* gdk_content_deserializer_get_input_stream:
* @deserializer: a #GdkContentDeserializer
* @deserializer: a `GdkContentDeserializer`
*
* Gets the input stream that was passed to gdk_content_deserialize_async().
* Gets the input stream for the current operation.
*
* This is the stream that was passed to [func@content_deserialize_async].
*
* Returns: (transfer none): the input stream for the current operation
*/
@ -230,11 +238,13 @@ gdk_content_deserializer_get_input_stream (GdkContentDeserializer *deserializer)
/**
* gdk_content_deserializer_get_priority:
* @deserializer: a #GdkContentDeserializer
* @deserializer: a `GdkContentDeserializer`
*
* Gets the io priority that was passed to gdk_content_deserialize_async().
* Gets the I/O priority for the current operation.
*
* Returns: the io priority for the current operation
* This is the priority that was passed to [funccontent_deserialize_async].
*
* Returns: the I/O priority for the current operation
*/
int
gdk_content_deserializer_get_priority (GdkContentDeserializer *deserializer)
@ -246,9 +256,11 @@ gdk_content_deserializer_get_priority (GdkContentDeserializer *deserializer)
/**
* gdk_content_deserializer_get_cancellable:
* @deserializer: a #GdkContentDeserializer
* @deserializer: a `GdkContentDeserializer`
*
* Gets the cancellable that was passed to gdk_content_deserialize_async().
* Gets the cancellable for the current operation.
*
* This is the `GCancellable` that was passed to [func@content_deserialize_async].
*
* Returns: (transfer none): the cancellable for the current operation
*/
@ -262,7 +274,7 @@ gdk_content_deserializer_get_cancellable (GdkContentDeserializer *deserializer)
/**
* gdk_content_deserializer_get_user_data:
* @deserializer: a #GdkContentDeserializer
* @deserializer: a `GdkContentDeserializer`
*
* Gets the user data that was passed when the deserializer was registered.
*
@ -278,7 +290,7 @@ gdk_content_deserializer_get_user_data (GdkContentDeserializer *deserializer)
/**
* gdk_content_deserializer_set_task_data:
* @deserializer: a #GdkContentDeserializer
* @deserializer: a `GdkContentDeserializer`
* @data: data to associate with this operation
* @notify: destroy notify for @data
*
@ -300,9 +312,11 @@ gdk_content_deserializer_set_task_data (GdkContentDeserializer *deserializer,
/**
* gdk_content_deserializer_get_task_data:
* @deserializer: a #GdkContentDeserializer
* @deserializer: a `GdkContentDeserializer`
*
* Gets the data that was associated with @deserializer via gdk_content_deserializer_set_task_data().
* Gets the data that was associated with the current operation.
*
* See [method@Gdk.ContentDeserializer.set_task_data].
*
* Returns: (transfer none): the task data for @deserializer
*/
@ -329,7 +343,7 @@ gdk_content_deserializer_emit_callback (gpointer data)
/**
* gdk_content_deserializer_return_success:
* @deserializer: a #GdkContentDeserializer
* @deserializer: a `GdkContentDeserializer`
*
* Indicate that the deserialization has been successfully completed.
*/
@ -349,10 +363,11 @@ gdk_content_deserializer_return_success (GdkContentDeserializer *deserializer)
/**
* gdk_content_deserializer_return_error:
* @deserializer: a #GdkContentDeserializer
* @error: a #GError
* @deserializer: a `GdkContentDeserializer`
* @error: a `GError`
*
* Indicate that the deserialization has ended with an error.
*
* This function consumes @error.
*/
void
@ -376,8 +391,7 @@ gdk_content_deserializer_return_error (GdkContentDeserializer *deserializer,
* @data: data that @deserialize can access
* @notify: destroy notify for @data
*
* Registers a function to create objects of a given @type from
* a serialized representation with the given mime type.
* Registers a function to deserialize object of a given type.
*/
void
gdk_content_register_deserializer (const char *mime_type,
@ -424,18 +438,18 @@ lookup_deserializer (const char *mime_type,
deserializer->type == type)
return deserializer;
}
return NULL;
}
/**
* gdk_content_formats_union_deserialize_gtypes:
* @formats: (transfer full): a #GdkContentFormats
* @formats: (transfer full): a `GdkContentFormats`
*
* Add GTypes for mime types in @formats for which deserializers are
* registered.
*
* Return: a new #GdkContentFormats
* Return: a new `GdkContentFormats`
*/
GdkContentFormats *
gdk_content_formats_union_deserialize_gtypes (GdkContentFormats *formats)
@ -465,12 +479,12 @@ gdk_content_formats_union_deserialize_gtypes (GdkContentFormats *formats)
/**
* gdk_content_formats_union_deserialize_mime_types:
* @formats: (transfer full): a #GdkContentFormats
* @formats: (transfer full): a `GdkContentFormats`
*
* Add mime types for GTypes in @formats for which deserializers are
* registered.
*
* Return: a new #GdkContentFormats
* Return: a new `GdkContentFormats`
*/
GdkContentFormats *
gdk_content_formats_union_deserialize_mime_types (GdkContentFormats *formats)
@ -511,17 +525,21 @@ deserialize_not_found (GdkContentDeserializer *deserializer)
/**
* gdk_content_deserialize_async:
* @stream: a #GInputStream to read the serialized content from
* @stream: a `GInputStream` to read the serialized content from
* @mime_type: the mime type to deserialize from
* @type: the GType to deserialize from
* @io_priority: the io priority of the operation
* @cancellable: (nullable): optional #GCancellable object
* @io_priority: the I/O priority of the operation
* @cancellable: (nullable): optional `GCancellable` object
* @callback: (scope async): callback to call when the operation is done
* @user_data: (closure): data to pass to the callback function
*
* Read content from the given input stream and deserialize it, asynchronously.
* When the operation is finished, @callback will be called. You can then
* call gdk_content_deserialize_finish() to get the result of the operation.
*
* The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers
* indicate a higher priority.
*
* When the operation is finished, @callback will be called. You must then
* call [func@content_deserialize_finish] to get the result of the operation.
*/
void
gdk_content_deserialize_async (GInputStream *stream,
@ -553,14 +571,15 @@ gdk_content_deserialize_async (GInputStream *stream,
/**
* gdk_content_deserialize_finish:
* @result: the #GAsyncResult
* @result: the `GAsyncResult`
* @value: return location for the result of the operation
* @error: return location for an error
*
* Finishes a content deserialization operation.
*
* Returns: %TRUE if the operation was successful. In this case, @value is set.
* %FALSE if an error occurred. In this case, @error is set
* Returns: %TRUE if the operation was successful. In this case,
* @value is set. %FALSE if an error occurred. In this case,
* @error is set
*/
gboolean
gdk_content_deserialize_finish (GAsyncResult *result,

6
gdk/gdkcontentdeserializer.h
View File

@ -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.

243
gdk/gdkcontentformats.c
View File

@ -16,46 +16,40 @@
*/
/**
* SECTION:gdkcontentformats
* @Title: Content Formats
* @Short_description: Advertising and negotiating of content
* exchange formats
* @See_also: #GdkDrag, #GdkDrop, #GdkClipboard, #GdkContentProvider
* GdkContentFormats:
*
* This section describes the #GdkContentFormats structure that is used to
* advertise and negotiate the format of content passed between different
* widgets, windows or applications using for example the clipboard or
* drag'n'drop.
* The `GdkContentFormats` structure is used to advertise and negotiate the
* format of content.
*
* GDK supports content in 2 forms: #GType and mime type.
* Using #GTypes is meant only for in-process content transfers. Mime types
* You will encounter `GdkContentFormats` when interacting with objects
* controlling operations that pass data between different widgets, window
* or application, like [class@Gdk.Drag], [class@Gdk.Drop],
* [class@Gdk.Clipboard] or [class@Gdk.ContentProvider].
*
* GDK supports content in 2 forms: `GType` and mime type.
* Using `GTypes` is meant only for in-process content transfers. Mime types
* are meant to be used for data passing both in-process and out-of-process.
* The details of how data is passed is described in the documentation of
* the actual implementations.
* the actual implementations. To transform between the two forms,
* [class@Gdk.ContentSerializer] and [class@Gdk.ContentDeserializer] are used.
*
* A #GdkContentFormats describes a set of possible formats content can be
* exchanged in. It is assumed that this set is ordered. #GTypes are more
* important than mime types. Order between different #GTypes or mime types
* A `GdkContentFormats` describes a set of possible formats content can be
* exchanged in. It is assumed that this set is ordered. `GTypes` are more
* important than mime types. Order between different `GTypes` or mime types
* is the order they were added in, most important first. Functions that
* care about order, such as gdk_content_formats_union() will describe in
* their documentation how they interpret that order, though in general the
* care about order, such as [method@Gdk.ContentFormats.union], will describe
* in their documentation how they interpret that order, though in general the
* order of the first argument is considered the primary order of the result,
* followed by the order of further arguments.
*
* For debugging purposes, the function gdk_content_formats_to_string() exists.
* It will print a comma-seperated formats of formats from most important to least
* important.
* For debugging purposes, the function [method@Gdk.ContentFormats.to_string]
* exists. It will print a comma-separated list of formats from most important
* to least important.
*
* #GdkContentFormats is an immutable struct. After creation, you cannot change
* the types it represents. Instead, new #GdkContentFormats have to be created.
* The #GdkContentFormatsBuilder structure is meant to help in this endeavor.
*/
/**
* GdkContentFormats:
*
* A #GdkContentFormats struct is a reference counted struct
* and should be treated as opaque.
* `GdkContentFormats` is an immutable struct. After creation, you cannot change
* the types it represents. Instead, new `GdkContentFormats` have to be created.
* The [struct@Gdk.ContentFormatsBuilder]` structure is meant to help in this
* endeavor.
*/
#include "config.h"
@ -92,7 +86,7 @@ G_DEFINE_BOXED_TYPE (GdkContentFormats, gdk_content_formats,
*
* Returns: An interned string for the canonicalized mime type
* or %NULL if the string wasn't a valid mime type
**/
*/
const char *
gdk_intern_mime_type (const char *string)
{
@ -134,15 +128,15 @@ gdk_content_formats_new_take (GType * gtypes,
* @mime_types: (array length=n_mime_types) (allow-none): Pointer to an
* array of mime types
* @n_mime_types: number of entries in @mime_types.
*
* Creates a new #GdkContentFormats from an array of mime types.
*
* Creates a new `GdkContentFormats` from an array of mime types.
*
* The mime types must be valid and different from each other or the
* behavior of the return value is undefined. If you cannot guarantee
* this, use #GdkContentFormatsBuilder instead.
*
* Returns: (transfer full): the new #GdkContentFormats.
**/
* this, use `GdkContentFormatsBuilder` instead.
*
* Returns: (transfer full): the new `GdkContentFormats`.
*/
GdkContentFormats *
gdk_content_formats_new (const char **mime_types,
guint n_mime_types)
@ -165,12 +159,12 @@ gdk_content_formats_new (const char **mime_types,
/**
* gdk_content_formats_new_for_gtype:
* @type: a $GType
* @type: a `GType`
*
* Creates a new #GdkContentFormats for a given #GType.
* Creates a new `GdkContentFormats` for a given `GType`.
*
* Returns: a new #GdkContentFormats
**/
* Returns: a new `GdkContentFormats`
*/
GdkContentFormats *
gdk_content_formats_new_for_gtype (GType type)
{
@ -187,12 +181,12 @@ gdk_content_formats_new_for_gtype (GType type)
/**
* gdk_content_formats_ref:
* @formats: a #GdkContentFormats
*
* Increases the reference count of a #GdkContentFormats by one.
* @formats: a `GdkContentFormats`
*
* Returns: the passed in #GdkContentFormats.
**/
* Increases the reference count of a `GdkContentFormats` by one.
*
* Returns: the passed in `GdkContentFormats`.
*/
GdkContentFormats *
gdk_content_formats_ref (GdkContentFormats *formats)
{
@ -205,12 +199,13 @@ gdk_content_formats_ref (GdkContentFormats *formats)
/**
* gdk_content_formats_unref:
* @formats: a #GdkContentFormats
*
* Decreases the reference count of a #GdkContentFormats by one.
* @formats: a `GdkContentFormats`
*
* Decreases the reference count of a `GdkContentFormats` by one.
*
* If the resulting reference count is zero, frees the formats.
**/
void
*/
void
gdk_content_formats_unref (GdkContentFormats *formats)
{
g_return_if_fail (formats != NULL);
@ -227,15 +222,16 @@ gdk_content_formats_unref (GdkContentFormats *formats)
/**
* gdk_content_formats_print:
* @formats: a #GdkContentFormats
* @string: a #GString to print into
* @formats: a `GdkContentFormats`
* @string: a `GString` to print into
*
* Prints the given @formats into a string for human consumption.
*
* This is meant for debugging and logging.
*
* The form of the representation may change at any time and is
* not guaranteed to stay identical.
**/
*/
void
gdk_content_formats_print (GdkContentFormats *formats,
GString *string)
@ -263,14 +259,15 @@ gdk_content_formats_print (GdkContentFormats *formats,
/**
* gdk_content_formats_to_string:
* @formats: a #GdkContentFormats
* @formats: a `GdkContentFormats`
*
* Prints the given @formats into a human-readable string.
* This is a small wrapper around gdk_content_formats_print() to help
* when debugging.
*
* This is a small wrapper around [method@Gdk.ContentFormats.print]
* to help when debugging.
*
* Returns: (transfer full): a new string
**/
*/
char *
gdk_content_formats_to_string (GdkContentFormats *formats)
{
@ -286,13 +283,13 @@ gdk_content_formats_to_string (GdkContentFormats *formats)
/**
* gdk_content_formats_union:
* @first: (transfer full): the #GdkContentFormats to merge into
* @second: (transfer none): the #GdkContentFormats to merge from
* @first: (transfer full): the `GdkContentFormats` to merge into
* @second: (transfer none): the `GdkContentFormats` to merge from
*
* Append all missing types from @second to @first, in the order
* they had in @second.
*
* Returns: a new #GdkContentFormats
* Returns: a new `GdkContentFormats`
*/
GdkContentFormats *
gdk_content_formats_union (GdkContentFormats *first,
@ -329,8 +326,8 @@ gdk_content_formats_contain_interned_mime_type (const GdkContentFormats *formats
/**
* gdk_content_formats_match:
* @first: the primary #GdkContentFormats to intersect
* @second: the #GdkContentFormats to intersect with
* @first: the primary `GdkContentFormats` to intersect
* @second: the `GdkContentFormats` to intersect with
*
* Checks if @first and @second have any matching formats.
*
@ -349,15 +346,16 @@ gdk_content_formats_match (const GdkContentFormats *first,
/**
* gdk_content_formats_match_gtype:
* @first: the primary #GdkContentFormats to intersect
* @second: the #GdkContentFormats to intersect with
* @first: the primary `GdkContentFormats` to intersect
* @second: the `GdkContentFormats` to intersect with
*
* Finds the first #GType from @first that is also contained
* in @second. If no matching #GType is found, %G_TYPE_INVALID
* is returned.
* Finds the first `GType` from @first that is also contained
* in @second.
*
* Returns: The first common #GType or %G_TYPE_INVALID if none.
**/
* If no matching `GType` is found, %G_TYPE_INVALID is returned.
*
* Returns: The first common `GType` or %G_TYPE_INVALID if none.
*/
GType
gdk_content_formats_match_gtype (const GdkContentFormats *first,
const GdkContentFormats *second)
@ -378,15 +376,16 @@ gdk_content_formats_match_gtype (const GdkContentFormats *first,
/**
* gdk_content_formats_match_mime_type:
* @first: the primary #GdkContentFormats to intersect
* @second: the #GdkContentFormats to intersect with
* @first: the primary `GdkContentFormats` to intersect
* @second: the `GdkContentFormats` to intersect with
*
* Finds the first mime type from @first that is also contained
* in @second. If no matching mime type is found, %NULL is
* returned.
* in @second.
*
* If no matching mime type is found, %NULL is returned.
*
* Returns: (nullable): The first common mime type or %NULL if none.
**/
*/
const char *
gdk_content_formats_match_mime_type (const GdkContentFormats *first,
const GdkContentFormats *second)
@ -407,13 +406,13 @@ gdk_content_formats_match_mime_type (const GdkContentFormats *first,
/**
* gdk_content_formats_contain_gtype:
* @formats: a #GdkContentFormats
* @type: the #GType to search for
* @formats: a `GdkContentFormats`
* @type: the `GType` to search for
*
* Checks if a given #GType is part of the given @formats.
* Checks if a given `GType` is part of the given @formats.
*
* Returns: %TRUE if the #GType was found
**/
*/
gboolean
gdk_content_formats_contain_gtype (const GdkContentFormats *formats,
GType type)
@ -433,13 +432,13 @@ gdk_content_formats_contain_gtype (const GdkContentFormats *formats,
/**
* gdk_content_formats_contain_mime_type:
* @formats: a #GdkContentFormats
* @formats: a `GdkContentFormats`
* @mime_type: the mime type to search for
*
* Checks if a given mime type is part of the given @formats.
*
* Returns: %TRUE if the mime_type was found
**/
*/
gboolean
gdk_content_formats_contain_mime_type (const GdkContentFormats *formats,
const char *mime_type)
@ -453,18 +452,19 @@ gdk_content_formats_contain_mime_type (const GdkContentFormats *formats,
/**
* gdk_content_formats_get_gtypes:
* @formats: a #GdkContentFormats
* @formats: a `GdkContentFormats`
* @n_gtypes: (out) (optional): optional pointer to take the
* number of #GTypes contained in the return value
*
* Gets the #GTypes included in @formats. Note that @formats may not
* contain any #GTypes, in particular when they are empty. In that
* case %NULL will be returned.
* Gets the `GTypes` included in @formats.
*
* Note that @formats may not contain any #GTypes, in particular when
* they are empty. In that case %NULL will be returned.
*
* Returns: (transfer none) (nullable) (array length=n_gtypes):
* %G_TYPE_INVALID-terminated array of types included in @formats or
* %NULL if none.
**/
*/
const GType *
gdk_content_formats_get_gtypes (const GdkContentFormats *formats,
gsize *n_gtypes)
@ -479,18 +479,19 @@ gdk_content_formats_get_gtypes (const GdkContentFormats *formats,
/**
* gdk_content_formats_get_mime_types:
* @formats: a #GdkContentFormats
* @formats: a `GdkContentFormats`
* @n_mime_types: (out) (allow-none): optional pointer to take the
* number of mime types contained in the return value
*
* Gets the mime types included in @formats. Note that @formats may not
* contain any mime types, in particular when they are empty. In that
* case %NULL will be returned.
* Gets the mime types included in @formats.
*
* Returns: (transfer none) (nullable): %NULL-terminated array of
* Note that @formats may not contain any mime types, in particular
* when they are empty. In that case %NULL will be returned.
*
* Returns: (transfer none) (nullable): %NULL-terminated array of
* interned strings of mime types included in @formats or %NULL
* if none.
**/
*/
const char * const *
gdk_content_formats_get_mime_types (const GdkContentFormats *formats,
gsize *n_mime_types)
@ -506,9 +507,8 @@ gdk_content_formats_get_mime_types (const GdkContentFormats *formats,
/**
* GdkContentFormatsBuilder:
*
* A #GdkContentFormatsBuilder struct is an opaque struct. It is meant to
* not be kept around and only be used to create new #GdkContentFormats
* objects.
* A `GdkContentFormatsBuilder` is an auxiliary struct used to create
* new `GdkContentFormats`, and should not be kept around.
*/
struct _GdkContentFormatsBuilder
@ -532,12 +532,13 @@ G_DEFINE_BOXED_TYPE (GdkContentFormatsBuilder,
/**
* gdk_content_formats_builder_new:
*
* Create a new #GdkContentFormatsBuilder object. The resulting builder
* would create an empty #GdkContentFormats. Use addition functions to add
* types to it.
* Create a new `GdkContentFormatsBuilder` object.
*
* Returns: a new #GdkContentFormatsBuilder
**/
* The resulting builder would create an empty `GdkContentFormats`.
* Use addition functions to add types to it.
*
* Returns: a new `GdkContentFormatsBuilder`
*/
GdkContentFormatsBuilder *
gdk_content_formats_builder_new (void)
{
@ -551,15 +552,15 @@ gdk_content_formats_builder_new (void)
/**
* gdk_content_formats_builder_ref:
* @builder: a #GdkContentFormatsBuilder
* @builder: a `GdkContentFormatsBuilder`
*
* Acquires a reference on the given @builder.
*
* This function is intended primarily for bindings. #GdkContentFormatsBuilder objects
* should not be kept around.
* This function is intended primarily for bindings.
* `GdkContentFormatsBuilder` objects should not be kept around.
*
* Returns: (transfer none): the given #GdkContentFormatsBuilder with
* its reference count increased
* Returns: (transfer none): the given `GdkContentFormatsBuilder`
* with its reference count increased
*/
GdkContentFormatsBuilder *
gdk_content_formats_builder_ref (GdkContentFormatsBuilder *builder)
@ -581,7 +582,7 @@ gdk_content_formats_builder_clear (GdkContentFormatsBuilder *builder)
/**
* gdk_content_formats_builder_unref:
* @builder: a #GdkContentFormatsBuilder
* @builder: a `GdkContentFormatsBuilder`
*
* Releases a reference on the given @builder.
*/
@ -602,12 +603,12 @@ gdk_content_formats_builder_unref (GdkContentFormatsBuilder *builder)
/**
* gdk_content_formats_builder_free_to_formats: (skip)
* @builder: a #GdkContentFormatsBuilder
* @builder: a `GdkContentFormatsBuilder`
*
* Creates a new #GdkContentFormats from the current state of the
* Creates a new `GdkContentFormats` from the current state of the
* given @builder, and frees the @builder instance.
*
* Returns: (transfer full): the newly created #GdkContentFormats
* Returns: (transfer full): the newly created `GdkContentFormats`
* with all the formats added to @builder
*/
GdkContentFormats *
@ -626,17 +627,17 @@ gdk_content_formats_builder_free_to_formats (GdkContentFormatsBuilder *builder)
/**
* gdk_content_formats_builder_to_formats:
* @builder: a #GdkContentFormatsBuilder
* @builder: a `GdkContentFormats`Builder
*
* Creates a new #GdkContentFormats from the given @builder.
* Creates a new `GdkContentFormats` from the given @builder.
*
* The given #GdkContentFormatsBuilder is reset once this function returns;
* The given `GdkContentFormatsBuilder` is reset once this function returns;
* you cannot call this function multiple times on the same @builder instance.
*
* This function is intended primarily for bindings. C code should use
* gdk_content_formats_builder_free_to_formats().
* [method@Gdk.ContentFormatsBuilder.free_to_formats].
*
* Returns: (transfer full): the newly created #GdkContentFormats
* Returns: (transfer full): the newly created `GdkContentFormats`
* with all the formats added to @builder
*/
GdkContentFormats *
@ -674,12 +675,12 @@ gdk_content_formats_builder_to_formats (GdkContentFormatsBuilder *builder)
/**
* gdk_content_formats_builder_add_formats:
* @builder: a #GdkContentFormatsBuilder
* @builder: a `GdkContentFormatsBuilder`
* @formats: the formats to add
*
* Appends all formats from @formats to @builder, skipping those that
* already exist.
**/
*/
void
gdk_content_formats_builder_add_formats (GdkContentFormatsBuilder *builder,
const GdkContentFormats *formats)
@ -698,10 +699,10 @@ gdk_content_formats_builder_add_formats (GdkContentFormatsBuilder *builder,
/**
* gdk_content_formats_builder_add_gtype:
* @builder: a #GdkContentFormatsBuilder
* @type: a #GType
* @builder: a `GdkContentFormats`Builder
* @type: a `GType`
*
* Appends @gtype to @builder if it has not already been added.
* Appends @type to @builder if it has not already been added.
**/
void
gdk_content_formats_builder_add_gtype (GdkContentFormatsBuilder *builder,
@ -719,11 +720,11 @@ gdk_content_formats_builder_add_gtype (GdkContentFormatsBuilder *builder,
/**
* gdk_content_formats_builder_add_mime_type:
* @builder: a #GdkContentFormatsBuilder
* @builder: a `GdkContentFormatsBuilder`
* @mime_type: a mime type
*
* Appends @mime_type to @builder if it has not already been added.
**/
*/
void
gdk_content_formats_builder_add_mime_type (GdkContentFormatsBuilder *builder,
const char *mime_type)

84
gdk/gdkcontentprovider.c
View File

@ -25,20 +25,17 @@
#include "gdkintl.h"
/**
* SECTION:gdkcontentprovider
* @Short_description: Provides content for data transfer between applications
* @Title: GdkContentProvider
* @See_also: #GdkContentSerializer, #GdkContentDeserializer
* GdkContentProvider:
*
* A GdkContentProvider is used to provide content for the clipboard in
* a number of formats.
* A `GdkContentProvider` is used to provide content for the clipboard or
* for drag-and-drop operations in a number of formats.
*
* To create a GdkContentProvider, use gdk_content_provider_new_for_value() or
* gdk_content_provider_new_for_bytes().
* To create a `GdkContentProvider`, use [ctor@Gdk.ContentProvider.new_for_value]
* or [ctor@Gdk.ContentProvider.new_for_bytes].
*
* GDK knows how to handle common text and image formats out-of-the-box. See
* #GdkContentSerializer and #GdkContentDeserializer if you want to add support
* for application-specific data formats.
* [class@Gdk.ContentSerializer] and [class@Gdk.ContentDeserializer] if you want
* to add support for application-specific data formats.
*/
typedef struct _GdkContentProviderPrivate GdkContentProviderPrivate;
@ -226,7 +223,7 @@ gdk_content_provider_init (GdkContentProvider *provider)
* Gets the formats that the provider can provide its current contents in.
*
* Returns: (transfer full): The formats of the provider
**/
*/
GdkContentFormats *
gdk_content_provider_ref_formats (GdkContentProvider *provider)
{
@ -240,13 +237,14 @@ gdk_content_provider_ref_formats (GdkContentProvider *provider)
* @provider: a #GdkContentProvider
*
* Gets the formats that the provider suggests other applications to store
* the data in.
* the data in.
*
* An example of such an application would be a clipboard manager.
*
* This can be assumed to be a subset of gdk_content_provider_ref_formats().
* This can be assumed to be a subset of [method@Gdk.ContentProvider.ref_formats].
*
* Returns: (transfer full): The storable formats of the provider
**/
*/
GdkContentFormats *
gdk_content_provider_ref_storable_formats (GdkContentProvider *provider)
{
@ -257,9 +255,9 @@ gdk_content_provider_ref_storable_formats (GdkContentProvider *provider)
/**
* gdk_content_provider_content_changed:
* @provider: a #GdkContentProvider
* @provider: a `GdkContentProvider`
*
* Emits the #GdkContentProvider::content-changed signal.
* Emits the ::content-changed signal.
*/
void
gdk_content_provider_content_changed (GdkContentProvider *provider)
@ -273,26 +271,27 @@ gdk_content_provider_content_changed (GdkContentProvider *provider)
/**
* gdk_content_provider_write_mime_type_async:
* @provider: a #GdkContentProvider
* @provider: a `GdkContentProvider`
* @mime_type: the mime type to provide the data in
* @stream: the #GOutputStream to write to
* @io_priority: the [I/O priority][io-priority]
* of the request.
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @stream: the `GOutputStream` to write to
* @io_priority: I/O priority of the request.
* @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
* @callback: (scope async): callback to call when the request is satisfied
* @user_data: (closure): the data to pass to callback function
*
* Asynchronously writes the contents of @provider to @stream in the given
* @mime_type. When the operation is finished @callback will be called. You
* can then call gdk_content_provider_write_mime_type_finish() to get the
* result of the operation.
* @mime_type.
*
* When the operation is finished @callback will be called. You must then call
* [method@Gdk.ContentProvider.write_mime_type_finish] to get the result
* of the operation.
*
* The given mime type does not need to be listed in the formats returned by
* gdk_content_provider_ref_formats(). However, if the given #GType is not
* supported, #G_IO_ERROR_NOT_SUPPORTED will be reported.
* [method@Gdk.ContentProvider.ref_formats]. However, if the given `GType` is
* not supported, #G_IO_ERROR_NOT_SUPPORTED will be reported.
*
* The given @stream will not be closed.
**/
*/
void
gdk_content_provider_write_mime_type_async (GdkContentProvider *provider,
const char *mime_type,
@ -318,17 +317,17 @@ gdk_content_provider_write_mime_type_async (GdkContentProvider *provider,
/**
* gdk_content_provider_write_mime_type_finish:
* @provider: a #GdkContentProvider
* @result: a #GAsyncResult
* @error: a #GError location to store the error occurring, or %NULL to
* ignore.
* @provider: a `GdkContentProvider`
* @result: a `GAsyncResult`
* @error: a `GError` location to store the error occurring, or %NULL to ignore
*
* Finishes an asynchronous write operation started with
* gdk_content_provider_write_mime_type_async().
* Finishes an asynchronous write operation.
*
* See [method@Gdk.ContentProvider.write_mime_type_async].
*
* Returns: %TRUE if the operation was completed successfully. Otherwise
* @error will be set to describe the failure.
**/
*/
gboolean
gdk_content_provider_write_mime_type_finish (GdkContentProvider *provider,
GAsyncResult *result,
@ -342,22 +341,21 @@ gdk_content_provider_write_mime_type_finish (GdkContentProvider *provider,
/**
* gdk_content_provider_get_value:
* @provider: a #GdkContentProvider
* @value: the #GValue to fill
* @error: a #GError location to store the error occurring, or %NULL to
* ignore.
* @provider: a `GdkContentProvider`
* @value: the `GValue` to fill
* @error: a `GError` location to store the error occurring, or %NULL to ignore
*
* Gets the contents of @provider stored in @value.
*
* The @value will have been initialized to the #GType the value should be
* provided in. This given #GType does not need to be listed in the formats
* returned by gdk_content_provider_ref_formats(). However, if the given
* #GType is not supported, this operation can fail and
* The @value will have been initialized to the `GType` the value should be
* provided in. This given `GType` does not need to be listed in the formats
* returned by [method@Gdk.ContentProvider.ref_formats]. However, if the
* given `GType` is not supported, this operation can fail and
* #G_IO_ERROR_NOT_SUPPORTED will be reported.
*
* Returns: %TRUE if the value was set successfully. Otherwise
* @error will be set to describe the failure.
**/
*/
gboolean
gdk_content_provider_get_value (GdkContentProvider *provider,
GValue *value,

6
gdk/gdkcontentprovider.h
View File

@ -38,12 +38,6 @@ G_BEGIN_DECLS
typedef struct _GdkContentProviderClass GdkContentProviderClass;
/**
* GdkContentProvider:
*
* Should not be directly accessed.
*/
struct _GdkContentProvider
{
GObject parent;

95
gdk/gdkcontentserializer.c
View File

@ -32,13 +32,20 @@
/**
* SECTION:gdkcontentserializer
* @Short_description: Serialize content for transfer
* @Title: GdkContentSerializer
* @See_also: #GdkContentDeserializer, #GdkContentProvider
* GdkContentSerializer:
*
* A GdkContentSerializer is used to serialize content for inter-application
* data transfers.
* A `GdkContentSerializer` is used to serialize content for
* inter-application data transfers.
*
* The `GdkContentSerializer` transforms an object that is identified
* by a GType into a serialized form (i.e. a byte stream) that is
* identified by a mime type.
*
* GTK provides serializers and deserializers for common data types
* such as text, colors, images or file lists. To register your own
* serialization functions, use [func@content_register_serializer].
*
* Also see [class@Gdk.ContentDeserializer].
*/
typedef struct _Serializer Serializer;
@ -169,7 +176,7 @@ gdk_content_serializer_run (const char *mime_type,
/**
* gdk_content_serializer_get_mime_type:
* @serializer: a #GdkContentSerializer
* @serializer: a `GdkContentSerializer`
*
* Gets the mime type to serialize to.
*
@ -185,11 +192,11 @@ gdk_content_serializer_get_mime_type (GdkContentSerializer *serializer)
/**
* gdk_content_serializer_get_gtype:
* @serializer: a #GdkContentSerializer
* @serializer: a `GdkContentSerializer`
*
* Gets the GType to of the object to serialize.
* Gets the `GType` to of the object to serialize.
*
* Returns: the GType for the current operation
* Returns: the `GType` for the current operation
*/
GType
gdk_content_serializer_get_gtype (GdkContentSerializer *serializer)
@ -201,11 +208,11 @@ gdk_content_serializer_get_gtype (GdkContentSerializer *serializer)
/**
* gdk_content_serializer_get_value:
* @serializer: a #GdkContentSerializer
* @serializer: a `GdkContentSerializer`
*
* Gets the #GValue to read the object to serialize from.
* Gets the `GValue` to read the object to serialize from.
*
* Returns: (transfer none): the #GValue for the current operation
* Returns: (transfer none): the `GValue` for the current operation
*/
const GValue *
gdk_content_serializer_get_value (GdkContentSerializer *serializer)
@ -217,9 +224,11 @@ gdk_content_serializer_get_value (GdkContentSerializer *serializer)
/**
* gdk_content_serializer_get_output_stream:
* @serializer: a #GdkContentSerializer
* @serializer: a `GdkContentSerializer`
*
* Gets the output stream that was passed to gdk_content_serialize_async().
* Gets the output stream for the current operation.
*
* This is the stream that was passed to [func@content_serialize_async].
*
* Returns: (transfer none): the output stream for the current operation
*/
@ -233,11 +242,13 @@ gdk_content_serializer_get_output_stream (GdkContentSerializer *serializer)
/**
* gdk_content_serializer_get_priority:
* @serializer: a #GdkContentSerializer
* @serializer: a `GdkContentSerializer`
*
* Gets the io priority that was passed to gdk_content_serialize_async().
* Gets the I/O priority for the current operation.
*
* Returns: the io priority for the current operation
* This is the priority that was passed to [func@content_serialize_async].
*
* Returns: the I/O priority for the current operation
*/
int
gdk_content_serializer_get_priority (GdkContentSerializer *serializer)
@ -249,9 +260,11 @@ gdk_content_serializer_get_priority (GdkContentSerializer *serializer)
/**
* gdk_content_serializer_get_cancellable:
* @serializer: a #GdkContentSerializer
* @serializer: a `GdkContentSerializer`
*
* Gets the cancellable that was passed to gdk_content_serialize_async().
* Gets the cancellable for the current operation.
*
* This is the `GCancellable` that was passed to [content_serialize_async].
*
* Returns: (transfer none): the cancellable for the current operation
*/
@ -265,7 +278,7 @@ gdk_content_serializer_get_cancellable (GdkContentSerializer *serializer)
/**
* gdk_content_serializer_get_user_data:
* @serializer: a #GdkContentSerializer
* @serializer: a `GdkContentSerializer`
*
* Gets the user data that was passed when the serializer was registered.
*
@ -281,7 +294,7 @@ gdk_content_serializer_get_user_data (GdkContentSerializer *serializer)
/**
* gdk_content_serializer_set_task_data:
* @serializer: a #GdkContentSerializer
* @serializer: a `GdkContentSerializer`
* @data: data to associate with this operation
* @notify: destroy notify for @data
*
@ -303,9 +316,11 @@ gdk_content_serializer_set_task_data (GdkContentSerializer *serializer,
/**
* gdk_content_serializer_get_task_data:
* @serializer: a #GdkContentSerializer
* @serializer: a `GdkContentSerializer`
*
* Gets the data that was associated with @serializer via gdk_content_serializer_set_task_data().
* Gets the data that was associated with the current operation.
*
* See [method@Gdk.ContentSerializer.set_task_data].
*
* Returns: (transfer none): the task data for @serializer
*/
@ -332,7 +347,7 @@ gdk_content_serializer_emit_callback (gpointer data)
/**
* gdk_content_serializer_return_success:
* @serializer: a #GdkContentSerializer
* @serializer: a `GdkContentSerializer`
*
* Indicate that the serialization has been successfully completed.
*/
@ -352,10 +367,11 @@ gdk_content_serializer_return_success (GdkContentSerializer *serializer)
/**
* gdk_content_serializer_return_error:
* @serializer: a #GdkContentSerializer
* @error: a #GError
* @serializer: a `GdkContentSerializer`
* @error: a `GError`
*
* Indicate that the serialization has ended with an error.
*
* This function consumes @error.
*/
void
@ -379,8 +395,7 @@ gdk_content_serializer_return_error (GdkContentSerializer *serializer,
* @data: data that @serialize can access
* @notify: destroy notify for @data
*
* Registers a function to convert objects of the given @type to
* a serialized representation with the given mime type.
* Registers a function to serialize objects of a given type.
*/
void
gdk_content_register_serializer (GType type,
@ -433,12 +448,12 @@ lookup_serializer (const char *mime_type,
/**
* gdk_content_formats_union_serialize_gtypes:
* @formats: (transfer full): a #GdkContentFormats
* @formats: (transfer full): a `GdkContentFormats`
*
* Add GTypes for the mime types in @formats for which serializers are
* registered.
*
* Return: a new #GdkContentFormats
* Return: a new `GdkContentFormats`
*/
GdkContentFormats *
gdk_content_formats_union_serialize_gtypes (GdkContentFormats *formats)
@ -468,12 +483,12 @@ gdk_content_formats_union_serialize_gtypes (GdkContentFormats *formats)
/**
* gdk_content_formats_union_serialize_mime_types:
* @formats: (transfer full): a #GdkContentFormats
* @formats: (transfer full): a `GdkContentFormats`
*
* Add mime types for GTypes in @formats for which serializers are
* registered.
*
* Return: a new #GdkContentFormats
* Return: a new `GdkContentFormats`
*/
GdkContentFormats *
gdk_content_formats_union_serialize_mime_types (GdkContentFormats *formats)
@ -514,17 +529,21 @@ serialize_not_found (GdkContentSerializer *serializer)
/**
* gdk_content_serialize_async:
* @stream: a #GOutputStream to write the serialized content to
* @stream: a `GOutputStream` to write the serialized content to
* @mime_type: the mime type to serialize to
* @value: the content to serialize
* @io_priority: the io priority of the operation
* @io_priority: the I/O priority of the operation
* @cancellable: (nullable): optional #GCancellable object
* @callback: (scope async): callback to call when the operation is done
* @user_data: (closure): data to pass to the callback function
*
* Serialize content and write it to the given output stream, asynchronously.
* When the operation is finished, @callback will be called. You can then
* call gdk_content_serialize_finish() to get the result of the operation.
*
* The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers
* indicate a higher priority.
*
* When the operation is finished, @callback will be called. You must then
* call [func@content_serialize_finish] to get the result of the operation.
*/
void
gdk_content_serialize_async (GOutputStream *stream,
@ -556,7 +575,7 @@ gdk_content_serialize_async (GOutputStream *stream,
/**
* gdk_content_serialize_finish:
* @result: the #GAsyncResult
* @result: the `GAsyncResult`
* @error: return location for an error
*
* Finishes a content serialization operation.

6
gdk/gdkcontentserializer.h
View File

@ -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.

135
gdk/gdkcursor.c
View File

@ -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. Cursors are immutable
* objects, so once you created them, there is no way to modify them later.
* You should create a new cursor when you want to change something about
* it.
* `GdkCursor` is used to create and destroy cursors.
*
* Cursors are immutable objects, so once you created them, there is no way
* to modify them later. You should create a new cursor when you want to change
* something about it.
*
* Cursors by themselves are not very interesting: they must be bound to a
* window for users to see them. This is done with [method@Gdk.Surface.set_cursor]
* or [method@Gdk.Surface.set_device_cursor]. Applications will typically
* use higher-level GTK functions such as `gtk_widget_set_cursor()` instead.
* use higher-level GTK functions such as [method@Gtk.Widget.set_cursor]`
* instead.
*
* Cursors are not bound to a given [class@Gdk.Display], so they can be shared.
* However, the appearance of cursors may vary when used on different
@ -68,20 +68,11 @@
* and provide an image to use for the cursor.
*
* To ease work with unsupported cursors, a fallback cursor can be provided.
* If a [class@Gdk.Surface] cannot use a cursor because of the reasons mentioned above,
* it will try the fallback cursor. Fallback cursors can themselves have fallback
* cursors again, so it is possible to provide a chain of progressively easier
* to support cursors. If none of the provided cursors can be supported, the
* default cursor will be the ultimate fallback.
*/
/**
* GdkCursor:
*
* A #GdkCursor represents a cursor. Its contents are private.
*
* Cursors are immutable objects, so they can not change after
* they have been constructed.
* If a [class@Gdk.Surface] cannot use a cursor because of the reasons mentioned
* above, it will try the fallback cursor. Fallback cursors can themselves have
* fallback cursors again, so it is possible to provide a chain of progressively
* easier to support cursors. If none of the provided cursors can be supported,
* the default cursor will be the ultimate fallback.
*/
enum {
@ -178,6 +169,11 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
object_class->set_property = gdk_cursor_set_property;
object_class->finalize = gdk_cursor_finalize;
/**
* GdkCursor:fallback:
*
* Cursor to fall back to if this cursor cannot be displayed.
*/
g_object_class_install_property (object_class,
PROP_FALLBACK,
g_param_spec_object ("fallback",
@ -186,6 +182,12 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
GDK_TYPE_CURSOR,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
G_PARAM_STATIC_STRINGS));
/**
* GdkCursor:hotspot-x:
*
* X position of the cursor hotspot in the cursor image.
*/
g_object_class_install_property (object_class,
PROP_HOTSPOT_X,
g_param_spec_int ("hotspot-x",
@ -194,6 +196,12 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
0, G_MAXINT, 0,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
G_PARAM_STATIC_STRINGS));
/**
* GdkCursor:hotspot-y:
*
* Y position of the cursor hotspot in the cursor image.
*/
g_object_class_install_property (object_class,
PROP_HOTSPOT_Y,
g_param_spec_int ("hotspot-y",
@ -202,6 +210,14 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
0, G_MAXINT, 0,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
G_PARAM_STATIC_STRINGS));
/**
* GdkCursor:name:
*
* Name of this this cursor.
*
* The name will be %NULL if the cursor was created from a texture.
*/
g_object_class_install_property (object_class,
PROP_NAME,
g_param_spec_string ("name",
@ -210,6 +226,14 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
NULL,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
G_PARAM_STATIC_STRINGS));
/**
* GdkCursor:texture:
*
* The texture displayed by this cursor.
*
* The texture will be %NULL if the cursor was created from a name.
*/
g_object_class_install_property (object_class,
PROP_TEXTURE,
g_param_spec_object ("texture",
@ -274,7 +298,7 @@ gdk_cursor_equal (gconstpointer a,
/**
* gdk_cursor_new_from_name:
* @name: the name of the cursor
* @fallback: (allow-none): %NULL or the #GdkCursor to fall back to when
* @fallback: (allow-none): %NULL or the `GdkCursor` to fall back to when
* this one cannot be supported
*
* Creates a new cursor by looking up @name in the current cursor
@ -282,6 +306,7 @@ gdk_cursor_equal (gconstpointer a,
*
* A recommended set of cursor names that will work across different
* platforms can be found in the CSS specification:
*
* - "none"
* - ![](default_cursor.png) "default"
* - ![](help_cursor.png) "help"
@ -319,7 +344,7 @@ gdk_cursor_equal (gconstpointer a,
* - ![](zoom_out_cursor.png) "zoom-out"
*
*
* Returns: (nullable): a new #GdkCursor, or %NULL if there is no
* Returns: (nullable): a new `GdkCursor`, or %NULL if there is no
* cursor with the given name
*/
GdkCursor *
@ -340,12 +365,12 @@ gdk_cursor_new_from_name (const char *name,
* @texture: the texture providing the pixel data
* @hotspot_x: the horizontal offset of the “hotspot” of the cursor
* @hotspot_y: the vertical offset of the “hotspot” of the cursor
* @fallback: (allow-none): %NULL or the #GdkCursor to fall back to when
* @fallback: (allow-none): %NULL or the `GdkCursor` to fall back to when
* this one cannot be supported
*
* Creates a new cursor from a #GdkTexture.
* Creates a new cursor from a `GdkTexture`.
*
* Returns: a new #GdkCursor.
* Returns: a new `GdkCursor`
*/
GdkCursor *
gdk_cursor_new_from_texture (GdkTexture *texture,
@ -368,18 +393,18 @@ gdk_cursor_new_from_texture (GdkTexture *texture,
/**
* gdk_cursor_get_fallback:
* @cursor: a #GdkCursor.
* @cursor: a `GdkCursor`
*
* Returns the fallback for this @cursor. The fallback will be used if this
* cursor is not available on a given #GdkDisplay.
* Returns the fallback for this @cursor.
*
* For named cursors, this can happen when using nonstandard names or when
* using an incomplete cursor theme.
* For textured cursors, this can happen when the texture is too large or
* when the #GdkDisplay it is used on does not support textured cursors.
* The fallback will be used if this cursor is not available on a given
* `GdkDisplay`. For named cursors, this can happen when using nonstandard
* names or when using an incomplete cursor theme. For textured cursors,
* this can happen when the texture is too large or when the `GdkDisplay`
* it is used on does not support textured cursors.
*
* Returns: (transfer none) (nullable): the fallback of the cursor or %NULL to use
* the default cursor as fallback.
* Returns: (transfer none) (nullable): the fallback of the cursor or %NULL
* to use the default cursor as fallback.
*/
GdkCursor *
gdk_cursor_get_fallback (GdkCursor *cursor)
@ -391,13 +416,14 @@ gdk_cursor_get_fallback (GdkCursor *cursor)
/**
* gdk_cursor_get_name:
* @cursor: a #GdkCursor.
* @cursor: a `GdkCursor`
*
* Returns the name of the cursor. If the cursor is not a named cursor, %NULL
* will be returned.
* Returns the name of the cursor.
*
* Returns: (transfer none) (nullable): the name of the cursor or %NULL if it is not
* a named cursor
* If the cursor is not a named cursor, %NULL will be returned.
*
* Returns: (transfer none) (nullable): the name of the cursor or %NULL
* if it is not a named cursor
*/
const char *
gdk_cursor_get_name (GdkCursor *cursor)
@ -411,11 +437,12 @@ gdk_cursor_get_name (GdkCursor *cursor)
* gdk_cursor_get_texture:
* @cursor: a #GdkCursor.
*
* Returns the texture for the cursor. If the cursor is a named cursor, %NULL
* will be returned.
* Returns the texture for the cursor.
*
* Returns: (transfer none) (nullable): the texture for cursor or %NULL if it is a
* named cursor
* If the cursor is a named cursor, %NULL will be returned.
*
* Returns: (transfer none) (nullable): the texture for cursor or %NULL
* if it is a named cursor
*/
GdkTexture *
gdk_cursor_get_texture (GdkCursor *cursor)
@ -427,14 +454,15 @@ gdk_cursor_get_texture (GdkCursor *cursor)
/**
* gdk_cursor_get_hotspot_x:
* @cursor: a #GdkCursor.
* @cursor: a `GdkCursor`
*
* Returns the horizontal offset of the hotspot. The hotspot indicates the
* pixel that will be directly above the cursor.
* Returns the horizontal offset of the hotspot.
*
* The hotspot indicates the pixel that will be directly above the cursor.
*
* Note that named cursors may have a nonzero hotspot, but this function
* will only return the hotspot position for cursors created with
* gdk_cursor_new_from_texture().
* [ctor@Gdk.Cursor.new_from_texture].
*
* Returns: the horizontal offset of the hotspot or 0 for named cursors
*/
@ -448,14 +476,15 @@ gdk_cursor_get_hotspot_x (GdkCursor *cursor)
/**
* gdk_cursor_get_hotspot_y:
* @cursor: a #GdkCursor.
* @cursor: a `GdkCursor`
*
* Returns the vertical offset of the hotspot. The hotspot indicates the
* pixel that will be directly above the cursor.
* Returns the vertical offset of the hotspot.
*
* The hotspot indicates the pixel that will be directly above the cursor.
*
* Note that named cursors may have a nonzero hotspot, but this function
* will only return the hotspot position for cursors created with
* gdk_cursor_new_from_texture().
* [ctor@Gdk.Cursor.new_from_texture].
*
* Returns: the vertical offset of the hotspot or 0 for named cursors
*/

248
gdk/gdkdevice.c
View File

@ -26,24 +26,14 @@
#include "gdkintl.h"
#include "gdkkeysprivate.h"
/**
* SECTION:gdkdevice
* @Short_description: Object representing an input device
* @Title: GdkDevice
* @See_also: #GdkSeat
*
* The #GdkDevice object represents a single input device, such
* as a keyboard, a mouse, a touchpad, etc.
*
* See the #GdkSeat documentation for more information about the
* various kinds of devices, and their relationships.
*/
/**
* GdkDevice:
*
* The GdkDevice struct contains only private fields and
* should not be accessed directly.
* The `GdkDevice` object represents an input device, such
* as a keyboard, a mouse, or a touchpad.
*
* See the [class@Gdk.Seat] documentation for more information
* about the various kinds of devices, and their relationships.
*/
typedef struct _GdkAxisInfo GdkAxisInfo;
@ -182,7 +172,9 @@ gdk_device_class_init (GdkDeviceClass *klass)
/**
* GdkDevice:vendor-id:
*
* Vendor ID of this device, see gdk_device_get_vendor_id().
* Vendor ID of this device.
*
* See [method@Gdk.Device.get_vendor_id].
*/
device_props[PROP_VENDOR_ID] =
g_param_spec_string ("vendor-id",
@ -195,7 +187,9 @@ gdk_device_class_init (GdkDeviceClass *klass)
/**
* GdkDevice:product-id:
*
* Product ID of this device, see gdk_device_get_product_id().
* Product ID of this device.
*
* See [method@Gdk.Device.get_product_id].
*/
device_props[PROP_PRODUCT_ID] =
g_param_spec_string ("product-id",
@ -208,7 +202,7 @@ gdk_device_class_init (GdkDeviceClass *klass)
/**
* GdkDevice:seat:
*
* #GdkSeat of this device.
* `GdkSeat` of this device.
*/
device_props[PROP_SEAT] =
g_param_spec_object ("seat",
@ -222,6 +216,7 @@ gdk_device_class_init (GdkDeviceClass *klass)
* GdkDevice:num-touches:
*
* The maximal number of concurrent touches on a touch device.
*
* Will be 0 if the device is not a touch device or if the number
* of touches is unknown.
*/
@ -234,6 +229,11 @@ gdk_device_class_init (GdkDeviceClass *klass)
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
G_PARAM_STATIC_STRINGS);
/**
* GdkDevice:tool:
*
* The `GdkDeviceTool` that is currently used with this device.
*/
device_props[PROP_TOOL] =
g_param_spec_object ("tool",
P_("Tool"),
@ -241,6 +241,13 @@ gdk_device_class_init (GdkDeviceClass *klass)
GDK_TYPE_DEVICE_TOOL,
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
/**
* GdkDevice:direction:
*
* The direction of the current layout.
*
* This is only relevant for keyboard devices.
*/
device_props[PROP_DIRECTION] =
g_param_spec_enum ("direction",
P_("Direction"),
@ -248,6 +255,13 @@ gdk_device_class_init (GdkDeviceClass *klass)
PANGO_TYPE_DIRECTION, PANGO_DIRECTION_NEUTRAL,
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
/**
* GdkDevice:direction:
*
* Whether the device has both right-to-left and left-to-right layouts.
*
* This is only relevant for keyboard devices.
*/
device_props[PROP_HAS_BIDI_LAYOUTS] =
g_param_spec_boolean ("has-bidi-layouts",
P_("Has bidi layouts"),
@ -255,6 +269,13 @@ gdk_device_class_init (GdkDeviceClass *klass)
FALSE,
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
/**
* GdkDevice:caps-lock-state:
*
* Whether Caps Lock is on.
*
* This is only relevant for keyboard devices.
*/
device_props[PROP_CAPS_LOCK_STATE] =
g_param_spec_boolean ("caps-lock-state",
P_("Caps lock state"),
@ -262,6 +283,13 @@ gdk_device_class_init (GdkDeviceClass *klass)
FALSE,
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
/**
* GdkDevice:num-lock-state:
*
* Whether Num Lock is on.
*
* This is only relevant for keyboard devices.
*/
device_props[PROP_NUM_LOCK_STATE] =
g_param_spec_boolean ("num-lock-state",
P_("Num lock state"),
@ -269,6 +297,13 @@ gdk_device_class_init (GdkDeviceClass *klass)
FALSE,
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
/**
* GdkDevice:scroll-lock-state:
*
* Whether Scroll Lock is on.
*
* This is only relevant for keyboard devices.
*/
device_props[PROP_SCROLL_LOCK_STATE] =
g_param_spec_boolean ("scroll-lock-state",
P_("Scroll lock state"),
@ -276,6 +311,13 @@ gdk_device_class_init (GdkDeviceClass *klass)
FALSE,
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
/**
* GdkDevice:modifier-state:
*
* The current modifier state of the device.
*
* This is only relevant for keyboard devices.
*/
device_props[PROP_MODIFIER_STATE] =
g_param_spec_flags ("modifier-state",
P_("Modifier state"),
@ -287,11 +329,11 @@ gdk_device_class_init (GdkDeviceClass *klass)
/**
* GdkDevice::changed:
* @device: the #GdkDevice that changed.
* @device: the `GdkDevice`
*
* The ::changed signal is emitted either when the #GdkDevice
* has changed the number of either axes or keys. For example
* on X11 this will normally happen when the physical device
* Emitted either when the the number of either axes or keys changes.
*
* On X11 this will normally happen when the physical device
* routing events through the logical device changes (for
* example, user switches from the USB mouse to a tablet); in
* that case the logical device will change to reflect the axes
@ -307,11 +349,10 @@ gdk_device_class_init (GdkDeviceClass *klass)
/**
* GdkDevice::tool-changed:
* @device: the #GdkDevice that changed.
* @device: the `GdkDevice`
* @tool: The new current tool
*
* The ::tool-changed signal is emitted on pen/eraser
* #GdkDevices whenever tools enter or leave proximity.
* Emitted on pen/eraser devices whenever tools enter or leave proximity.
*/
signals[TOOL_CHANGED] =
g_signal_new (g_intern_static_string ("tool-changed"),
@ -478,19 +519,21 @@ gdk_device_get_property (GObject *object,
/**
* gdk_device_get_surface_at_position:
* @device: pointer #GdkDevice to query info to.
* @device: pointer `GdkDevice` to query info to
* @win_x: (out) (allow-none): return location for the X coordinate of the device location,
* relative to the surface origin, or %NULL.
* @win_y: (out) (allow-none): return location for the Y coordinate of the device location,
* relative to the surface origin, or %NULL.
*
* Obtains the surface underneath @device, returning the location of the device in @win_x and @win_y in
* double precision. Returns %NULL if the surface tree under @device is not known to GDK (for example,
* belongs to another application).
* Obtains the surface underneath @device, returning the location of the
* device in @win_x and @win_y
*
* Returns: (nullable) (transfer none): the #GdkSurface under the
* device position, or %NULL.
**/
* Returns %NULL if the surface tree under @device is not known to GDK
* (for example, belongs to another application).
*
* Returns: (nullable) (transfer none): the `GdkSurface` under the
* device position, or %NULL
*/
GdkSurface *
gdk_device_get_surface_at_position (GdkDevice *device,
double *win_x,
@ -514,13 +557,12 @@ gdk_device_get_surface_at_position (GdkDevice *device,
/**
* gdk_device_get_name:
* @device: a #GdkDevice
* @device: a GdkDevice`
*
* Determines the name of the device, suitable
* for showing in a user interface.
* The name of the device, suitable for showing in a user interface.
*
* Returns: a name
**/
*/
const char *
gdk_device_get_name (GdkDevice *device)
{
@ -531,14 +573,15 @@ gdk_device_get_name (GdkDevice *device)
/**
* gdk_device_get_has_cursor:
* @device: a #GdkDevice
* @device: a `GdkDevice`
*
* Determines whether the pointer follows device motion.
*
* This is not meaningful for keyboard devices, which
* don't have a pointer.
*
* Returns: %TRUE if the pointer follows device motion
**/
*/
gboolean
gdk_device_get_has_cursor (GdkDevice *device)
{
@ -549,12 +592,12 @@ gdk_device_get_has_cursor (GdkDevice *device)
/**
* gdk_device_get_source:
* @device: a #GdkDevice
* @device: a `GdkDevice`
*
* Determines the type of the device.
*
* Returns: a #GdkInputSource
**/
* Returns: a `GdkInputSource`
*/
GdkInputSource
gdk_device_get_source (GdkDevice *device)
{
@ -565,13 +608,13 @@ gdk_device_get_source (GdkDevice *device)
/**
* gdk_device_get_axis_use:
* @device: a pointer #GdkDevice.
* @index_: the index of the axis.
* @device: a pointer `GdkDevice`
* @index_: the index of the axi.
*
* Returns the axis use for @index_.
*
* Returns: a #GdkAxisUse specifying how the axis is used.
**/
* Returns: a `GdkAxisUse` specifying how the axis is used.
*/
GdkAxisUse
gdk_device_get_axis_use (GdkDevice *device,
guint index_)
@ -589,13 +632,12 @@ gdk_device_get_axis_use (GdkDevice *device,
/**
* gdk_device_get_display:
* @device: a #GdkDevice
* @device: a `GdkDevice`
*
* Returns the #GdkDisplay to which @device pertains.
* Returns the `GdkDisplay` to which @device pertains.
*
* Returns: (transfer none): a #GdkDisplay. This memory is owned
* by GTK, and must not be freed or unreffed.
**/
* Returns: (transfer none): a `GdkDisplay`
*/
GdkDisplay *
gdk_device_get_display (GdkDevice *device)
{
@ -616,13 +658,13 @@ _gdk_device_set_associated_device (GdkDevice *device,
/*
* gdk_device_list_physical_devices:
* @device: a logical #GdkDevice
* @device: a logical `GdkDevice`
*
* Returns the list of physical devices attached to the given logical
* #GdkDevice.
* `GdkDevice`.
*
* Returns: (nullable) (transfer container) (element-type GdkDevice):
* the list of physical devices attached to a logical #GdkDevice
* the list of physical devices attached to a logical `GdkDevice`
*/
GList *
gdk_device_list_physical_devices (GdkDevice *device)
@ -655,12 +697,12 @@ _gdk_device_remove_physical_device (GdkDevice *device,
/*
* gdk_device_get_n_axes:
* @device: a pointer #GdkDevice
* @device: a pointer `GdkDevice`
*
* Returns the number of axes the device currently has.
*
* Returns: the number of axes.
**/
*/
int
gdk_device_get_n_axes (GdkDevice *device)
{
@ -672,16 +714,16 @@ gdk_device_get_n_axes (GdkDevice *device)
/*
* gdk_device_get_axis: (skip)
* @device: a #GdkDevice
* @device: a `GdkDevice`
* @axes: (array): pointer to an array of axes
* @use: the use to look for
* @value: (out): location to store the found value.
* @value: (out): location to store the found value
*
* Interprets an array of double as axis values for a given device,
* and locates the value in the array for a given axis use.
* Interprets an array of `double` as axis values and get the value
* for a given axis use.
*
* Returns: %TRUE if the given axis use was found, otherwise %FALSE
**/
*/
gboolean
gdk_device_get_axis (GdkDevice *device,
double *axes,
@ -1073,16 +1115,17 @@ _gdk_device_surface_at_position (GdkDevice *device,
/**
* gdk_device_get_vendor_id:
* @device: a physical #GdkDevice
* @device: a physical `GdkDevice`
*
* Returns the vendor ID of this device, or %NULL if this information couldn't
* be obtained. This ID is retrieved from the device, and is thus constant for
* it.
* Returns the vendor ID of this device.
*
* This function, together with gdk_device_get_product_id(), can be used to eg.
* compose #GSettings paths to store settings for this device.
* This ID is retrieved from the device, and does not change.
*
* |[<!-- language="C" -->
* This function, together with [method@Gdk.Device.get_product_id],
* can be used to eg. compose `GSettings` paths to store settings
* for this device.
*
* ```c
* static GSettings *
* get_device_settings (GdkDevice *device)
* {
@ -1100,7 +1143,7 @@ _gdk_device_surface_at_position (GdkDevice *device,
*
* return settings;
* }
* ]|
* ```
*
* Returns: (nullable): the vendor ID, or %NULL
*/
@ -1114,11 +1157,12 @@ gdk_device_get_vendor_id (GdkDevice *device)
/**
* gdk_device_get_product_id:
* @device: a physical #GdkDevice
* @device: a physical `GdkDevice`
*
* Returns the product ID of this device, or %NULL if this information couldn't
* be obtained. This ID is retrieved from the device, and is thus constant for
* it. See gdk_device_get_vendor_id() for more information.
* Returns the product ID of this device.
*
* This ID is retrieved from the device, and does not change.
* See [method@Gdk.Device.get_vendor_id] for more information.
*
* Returns: (nullable): the product ID, or %NULL
*/
@ -1148,10 +1192,10 @@ gdk_device_set_seat (GdkDevice *device,
* gdk_device_get_seat:
* @device: A #GdkDevice
*
* Returns the #GdkSeat the device belongs to.
* Returns the `GdkSeat` the device belongs to.
*
* Returns: (transfer none): a #GdkSeat
**/
* Returns: (transfer none): a `GdkSeat`
*/
GdkSeat *
gdk_device_get_seat (GdkDevice *device)
{
@ -1175,7 +1219,7 @@ gdk_device_update_tool (GdkDevice *device,
/**
* gdk_device_get_num_touches:
* @device: a #GdkDevice
* @device: a `GdkDevice`
*
* Retrieves the number of touch points associated to @device.
*
@ -1191,11 +1235,11 @@ gdk_device_get_num_touches (GdkDevice *device)
/**
* gdk_device_get_device_tool:
* @device: a #GdkDevice
* @device: a `GdkDevice`
*
* Retrieves the #GdkDeviceTool associated to @device.
* Retrieves the current tool for @device.
*
* Returns: (transfer none): the #GdkDeviceTool
* Returns: (transfer none): the `GdkDeviceTool`, or %NULL
*/
GdkDeviceTool *
gdk_device_get_device_tool (GdkDevice *device)
@ -1207,10 +1251,11 @@ gdk_device_get_device_tool (GdkDevice *device)
/**
* gdk_device_get_caps_lock_state:
* @device: a #GdkDevice
* @device: a `GdkDevice`
*
* Retrieves whether the Caps Lock modifier of the
* keyboard is locked, if @device is a keyboard device.
* Retrieves whether the Caps Lock modifier of the keyboard is locked.
*
* This is only relevant for keyboard devices.
*
* Returns: %TRUE if Caps Lock is on for @device
*/
@ -1227,10 +1272,11 @@ gdk_device_get_caps_lock_state (GdkDevice *device)
/**
* gdk_device_get_num_lock_state:
* @device: a #GdkDevice
* @device: a ``GdkDevice`
*
* Retrieves whether the Num Lock modifier of the
* keyboard is locked, if @device is a keyboard device.
* Retrieves whether the Num Lock modifier of the keyboard is locked.
*
* This is only relevant for keyboard devices.
*
* Returns: %TRUE if Num Lock is on for @device
*/
@ -1247,10 +1293,11 @@ gdk_device_get_num_lock_state (GdkDevice *device)
/**
* gdk_device_get_scroll_lock_state:
* @device: a #GdkDevice
* @device: a `GdkDevice`
*
* Retrieves whether the Scroll Lock modifier of the
* keyboard is locked, if @device is a keyboard device.
* Retrieves whether the Scroll Lock modifier of the keyboard is locked.
*
* This is only relevant for keyboard devices.
*
* Returns: %TRUE if Scroll Lock is on for @device
*/
@ -1267,10 +1314,11 @@ gdk_device_get_scroll_lock_state (GdkDevice *device)
/**
* gdk_device_get_modifier_state:
* @device: a #GdkDevice
* @device: a `GdkDevice`
*
* Retrieves the current modifier state of the keyboard,
* if @device is a keyboard device.
* Retrieves the current modifier state of the keyboard.
*
* This is only relevant for keyboard devices.
*
* Returns: the current modifier state
*/
@ -1287,13 +1335,14 @@ gdk_device_get_modifier_state (GdkDevice *device)
/**
* gdk_device_get_direction:
* @device: a #GdkDevice
* @device: a `GdkDevice`
*
* Returns the direction of effective layout of the keyboard,
* if @device is a keyboard device.
* Returns the direction of effective layout of the keyboard.
*
* This is only relevant for keyboard devices.
*
* The direction of a layout is the direction of the majority
* of its symbols. See pango_unichar_direction().
* of its symbols. See [func@Pango.unichar_direction].
*
* Returns: %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL
* if it can determine the direction. %PANGO_DIRECTION_NEUTRAL
@ -1312,11 +1361,12 @@ gdk_device_get_direction (GdkDevice *device)
/**
* gdk_device_has_bidi_layouts:
* @device: a #GdkDevice
* @device: a `GdkDevice`
*
* Determines if keyboard layouts for both right-to-left and
* left-to-right languages are in use on the keyboard, if
* @device is a keyboard device.
* Determines if layouts for both right-to-left and
* left-to-right languages are in use on the keyboard.
*
* This is only relevant for keyboard devices.
*
* Returns: %TRUE if there are layouts with both directions,
* %FALSE otherwise

51
gdk/gdkdevicepad.c
View File

@ -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,

69
gdk/gdkdevicetool.c
View File

@ -23,6 +23,11 @@
#include "gdkinternals.h"
#include "gdkintl.h"
/**
* GdkDeviceTool:
*
* A physical tool associated to a `GdkDevice`.
*/
G_DEFINE_TYPE (GdkDeviceTool, gdk_device_tool, G_TYPE_OBJECT)
@ -101,6 +106,11 @@ gdk_device_tool_class_init (GdkDeviceToolClass *klass)
object_class->set_property = gdk_device_tool_set_property;
object_class->get_property = gdk_device_tool_get_property;
/**
* GdkDeviceTool:serial:
*
* The serial number of the tool.
*/
tool_props[TOOL_PROP_SERIAL] = g_param_spec_uint64 ("serial",
"Serial",
"Serial number",
@ -108,6 +118,12 @@ gdk_device_tool_class_init (GdkDeviceToolClass *klass)
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT_ONLY |
G_PARAM_STATIC_STRINGS);
/**
* GdkDeviceTool:tool-type:
*
* The type of the tool.
*/
tool_props[TOOL_PROP_TOOL_TYPE] = g_param_spec_enum ("tool-type",
"Tool type",
"Tool type",
@ -116,12 +132,24 @@ gdk_device_tool_class_init (GdkDeviceToolClass *klass)
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT_ONLY |
G_PARAM_STATIC_STRINGS);
/**
* GdkDeviceTool:axes:
*
* The axes of the tool.
*/
tool_props[TOOL_PROP_AXES] = g_param_spec_flags ("axes",
"Axes",
"Tool axes",
GDK_TYPE_AXIS_FLAGS, 0,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT_ONLY);
/**
* GdkDeviceTool:hardware-id:
*
* The hardware ID of the tool.
*/
tool_props[TOOL_PROP_HARDWARE_ID] = g_param_spec_uint64 ("hardware-id",
"Hardware ID",
"Hardware ID",
@ -154,13 +182,15 @@ gdk_device_tool_new (guint64 serial,
/**
* gdk_device_tool_get_serial:
* @tool: a #GdkDeviceTool
* @tool: a `GdkDeviceTool`
*
* Gets the serial of this tool, this value can be used to identify a
* physical tool (eg. a tablet pen) across program executions.
* Gets the serial number of this tool.
*
* This value can be used to identify a physical tool
* (eg. a tablet pen) across program executions.
*
* Returns: The serial ID for this tool
**/
*/
guint64
gdk_device_tool_get_serial (GdkDeviceTool *tool)
{
@ -171,20 +201,22 @@ gdk_device_tool_get_serial (GdkDeviceTool *tool)
/**
* gdk_device_tool_get_hardware_id:
* @tool: a #GdkDeviceTool
* @tool: a `GdkDeviceTool`
*
* Gets the hardware ID of this tool, or 0 if it's not known. When
* non-zero, the identificator is unique for the given tool model,
* Gets the hardware ID of this tool, or 0 if it's not known.
*
* When non-zero, the identificator is unique for the given tool model,
* meaning that two identical tools will share the same @hardware_id,
* but will have different serial numbers (see gdk_device_tool_get_serial()).
* but will have different serial numbers (see
* [method@Gdk.DeviceTool.get_serial]).
*
* This is a more concrete (and device specific) method to identify
* a #GdkDeviceTool than gdk_device_tool_get_tool_type(), as a tablet
* may support multiple devices with the same #GdkDeviceToolType,
* but having different hardware identificators.
* a `GdkDeviceTool` than [method@Gdk.DeviceTool.get_tool_type],
* as a tablet may support multiple devices with the same
* `GdkDeviceToolType`, but different hardware identificators.
*
* Returns: The hardware identificator of this tool.
**/
*/
guint64
gdk_device_tool_get_hardware_id (GdkDeviceTool *tool)
{
@ -195,13 +227,14 @@ gdk_device_tool_get_hardware_id (GdkDeviceTool *tool)
/**
* gdk_device_tool_get_tool_type:
* @tool: a #GdkDeviceTool
* @tool: a `GdkDeviceTool`
*
* Gets the #GdkDeviceToolType of the tool.
* Gets the `GdkDeviceToolType` of the tool.
*
* Returns: The physical type for this tool. This can be used to figure out what
* sort of pen is being used, such as an airbrush or a pencil.
**/
* Returns: The physical type for this tool. This can be used to
* figure out what sort of pen is being used, such as an airbrush
* or a pencil.
*/
GdkDeviceToolType
gdk_device_tool_get_tool_type (GdkDeviceTool *tool)
{
@ -212,7 +245,7 @@ gdk_device_tool_get_tool_type (GdkDeviceTool *tool)
/**
* gdk_device_tool_get_axes:
* @tool: a #GdkDeviceTool
* @tool: a `GdkDeviceTool`
*
* Gets the axes of the tool.
*

5
gdk/gdkdevicetool.h
View File

@ -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;
/**

128
gdk/gdkdisplaymanager.c
View File

@ -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.
* For example:
*
* If the `GDK_BACKEND` environment variable
* is set, it determines what backends are tried in what
* order, while still respecting the set of allowed backends
* that are specified by this function.
* ```c
* gdk_set_allowed_backends ("wayland,macos,*");
* ```
*
* The possible backend names are x11, win32, quartz,
* broadway, wayland. You can also include a * in the
* list to try all remaining backends.
* instructs GDK to try the Wayland backend first, followed by the
* MacOs backend, and then all others.
*
* This call must happen prior to gdk_display_open(),
* gtk_init(), or gtk_init_check()
* If the `GDK_BACKEND` environment variable is set, it determines
* what backends are tried in what order, while still respecting the
* set of allowed backends that are specified by this function.
*
* The possible backend names are:
*
* - `broadway`
* - `macos`
* - `wayland`.
* - `win32`
* - `x11`
*
* You can also include a `*` in the list to try all remaining backends.
*
* This call must happen prior to functions that open a display, such
* as [func@Gdk.Display.open], `gtk_init()`, or `gtk_init_check()`
* in order to take effect.
*/
void
@ -275,16 +280,18 @@ static GdkBackend gdk_backends[] = {
/**
* gdk_display_manager_get:
*
* Gets the singleton #GdkDisplayManager object.
* Gets the singleton `GdkDisplayManager` object.
*
* When called for the first time, this function consults the
* `GDK_BACKEND` environment variable to find out which
* of the supported GDK backends to use (in case GDK has been compiled
* with multiple backends). Applications can use gdk_set_allowed_backends()
* to limit what backends can be used.
* `GDK_BACKEND` environment variable to find out which of the
* supported GDK backends to use (in case GDK has been compiled
* with multiple backends).
*
* Returns: (transfer none): The global #GdkDisplayManager singleton
**/
* Applications can use [func@set_allowed_backends] to limit what
* backends wil be used.
*
* Returns: (transfer none): The global `GdkDisplayManager` singleton
*/
GdkDisplayManager*
gdk_display_manager_get (void)
{
@ -298,11 +305,11 @@ gdk_display_manager_get (void)
/**
* gdk_display_manager_get_default_display:
* @manager: a #GdkDisplayManager
* @manager: a `GdkDisplayManager`
*
* Gets the default #GdkDisplay.
* Gets the default `GdkDisplay`.
*
* Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if
* Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL if
* there is no default display.
*/
GdkDisplay *
@ -314,12 +321,13 @@ gdk_display_manager_get_default_display (GdkDisplayManager *manager)
/**
* gdk_display_get_default:
*
* Gets the default #GdkDisplay. This is a convenience
* function for:
* Gets the default `GdkDisplay`.
*
* This is a convenience function for:
* `gdk_display_manager_get_default_display (gdk_display_manager_get ())`.
*
* Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if
* there is no default display.
* Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL if
* there is no default display
*/
GdkDisplay *
gdk_display_get_default (void)
@ -329,11 +337,11 @@ gdk_display_get_default (void)
/**
* gdk_display_manager_set_default_display:
* @manager: a #GdkDisplayManager
* @display: a #GdkDisplay
* @manager: a `GdkDisplayManager`
* @display: a `GdkDisplay`
*
* Sets @display as the default display.
**/
*/
void
gdk_display_manager_set_default_display (GdkDisplayManager *manager,
GdkDisplay *display)
@ -348,14 +356,14 @@ gdk_display_manager_set_default_display (GdkDisplayManager *manager,
/**
* gdk_display_manager_list_displays:
* @manager: a #GdkDisplayManager
* @manager: a `GdkDisplayManager`
*
* List all currently open displays.
*
* Returns: (transfer container) (element-type GdkDisplay): a newly
* allocated #GSList of #GdkDisplay objects. Free with g_slist_free()
* allocated `GSList` of `GdkDisplay` objects. Free with g_slist_free()
* when you are done with it.
**/
*/
GSList *
gdk_display_manager_list_displays (GdkDisplayManager *manager)
{
@ -364,13 +372,13 @@ gdk_display_manager_list_displays (GdkDisplayManager *manager)
/**
* gdk_display_manager_open_display:
* @manager: a #GdkDisplayManager
* @manager: a `GdkDisplayManager`
* @name: the name of the display to open
*
* Opens a display.
*
* Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if the
* display could not be opened
* Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL
* if the display could not be opened
*/
GdkDisplay *
gdk_display_manager_open_display (GdkDisplayManager *manager,

146
gdk/gdkdrag.c
View File

@ -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)
{

2
gdk/gdkdrag.h
View File

@ -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,

7
gdk/gdkdragsurface.c
View File

@ -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
*

99
gdk/gdkdrawcontext.c
View File

@ -27,24 +27,17 @@
#include "gdkprofilerprivate.h"
/**
* SECTION:gdkdrawcontext
* @Title: GdkDrawContext
* @Short_description: Base class for draw contexts
* GdkDrawContext:
*
* #GdkDrawContext is the base object used by contexts implementing different
* rendering methods, such as #GdkGLContext or #GdkVulkanContext. It provides
* shared functionality between those contexts.
* Base class for objects implementing different rendering methods.
*
* `GdkDrawContext` is the base object used by contexts implementing different
* rendering methods, such as [class@Gdk.CairoContext] or [class@Gdk.GLContext].
* It provides shared functionality between those contexts.
*
* You will always interact with one of those subclasses.
*
* A GdkDrawContext is always associated with a single toplevel surface.
*/
/**
* GdkDrawContext:
*
* The GdkDrawContext struct contains only private fields and should not
* be accessed directly.
* A `GdkDrawContext` is always associated with a single toplevel surface.
*/
typedef struct _GdkDrawContextPrivate GdkDrawContextPrivate;
@ -148,7 +141,7 @@ gdk_draw_context_class_init (GdkDrawContextClass *klass)
/**
* GdkDrawContext:display:
*
* The #GdkDisplay used to create the #GdkDrawContext.
* The `GdkDisplay` used to create the `GdkDrawContext`.
*/
pspecs[PROP_DISPLAY] =
g_param_spec_object ("display",
@ -161,7 +154,7 @@ gdk_draw_context_class_init (GdkDrawContextClass *klass)
/**
* GdkDrawContext:surface:
*
* The #GdkSurface the context is bound to.
* The `GdkSurface` the context is bound to.
*/
pspecs[PROP_SURFACE] =
g_param_spec_object ("surface",
@ -186,16 +179,16 @@ gdk_draw_context_init (GdkDrawContext *self)
/**
* gdk_draw_context_is_in_frame:
* @context: a #GdkDrawContext
* @context: a `GdkDrawContext`
*
* Returns %TRUE if @context is in the process of drawing to its surface
* after a call to gdk_draw_context_begin_frame() and not yet having called
* gdk_draw_context_end_frame().
* In this situation, drawing commands may be effecting the contents of a
* @context's surface.
* Returns %TRUE if @context is in the process of drawing to its surface.
*
* Returns: %TRUE if the context is between gdk_draw_context_begin_frame()
* and gdk_draw_context_end_frame() calls.
* This is the case between calls to [method@Gdk.DrawContext.begin_frame]
* and [method@Gdk.DrawContext.end_frame]. In this situation, drawing commands
* may be effecting the contents of the @context's surface.
*
* Returns: %TRUE if the context is between [method@Gdk.DrawContext.begin_frame]
* and [method@Gdk.DrawContext.end_frame] calls.
*/
gboolean
gdk_draw_context_is_in_frame (GdkDrawContext *context)
@ -209,9 +202,9 @@ gdk_draw_context_is_in_frame (GdkDrawContext *context)
/*< private >
* gdk_draw_context_surface_resized:
* @context: a #GdkDrawContext
* @context: a `GdkDrawContext`
*
* Called by the #GdkSurface the @context belongs to when the size of the surface
* Called by the surface the @context belongs to when the size of the surface
* changes.
*/
void
@ -222,11 +215,11 @@ gdk_draw_context_surface_resized (GdkDrawContext *context)
/**
* gdk_draw_context_get_display:
* @context: a #GdkDrawContext
* @context: a `GdkDrawContext`
*
* Retrieves the #GdkDisplay the @context is created for
* Retrieves the `GdkDisplay` the @context is created for
*
* Returns: (nullable) (transfer none): a #GdkDisplay or %NULL
* Returns: (nullable) (transfer none): a `GdkDisplay` or %NULL
*/
GdkDisplay *
gdk_draw_context_get_display (GdkDrawContext *context)
@ -240,9 +233,9 @@ gdk_draw_context_get_display (GdkDrawContext *context)
/**
* gdk_draw_context_get_surface:
* @context: a #GdkDrawContext
* @context: a `GdkDrawContext`
*
* Retrieves the #GdkSurface used by the @context.
* Retrieves the surface that @context is bound to.
*
* Returns: (nullable) (transfer none): a #GdkSurface or %NULL
*/
@ -258,7 +251,7 @@ gdk_draw_context_get_surface (GdkDrawContext *context)
/**
* gdk_draw_context_begin_frame:
* @context: the context used to draw the frame
* @context: the `GdkDrawContext` used to draw the frame
* @region: minimum region that should be drawn
*
* Indicates that you are beginning the process of redrawing @region
@ -267,23 +260,24 @@ gdk_draw_context_get_surface (GdkDrawContext *context)
* Calling this function begins a drawing operation using @context on the
* surface that @context was created from. The actual requirements and
* guarantees for the drawing operation vary for different implementations
* of drawing, so a #GdkCairoContext and a #GdkGLContext need to be treated
* differently.
* of drawing, so a [class@Gdk.CairoContext] and a [class@Gdk.GLContext]
* need to be treated differently.
*
* A call to this function is a requirement for drawing and must be followed
* by a call to gdk_draw_context_end_frame(), which will complete the
* drawing operation and ensure the contents become visible on screen.
* A call to this function is a requirement for drawing and must be
* followed by a call to [method@Gdk.DrawContext.end_frame], which will
* complete the drawing operation and ensure the contents become visible
* on screen.
*
* Note that the @region passed to this function is the minimum region that
* needs to be drawn and depending on implementation, windowing system and
* hardware in use, it might be necessary to draw a larger region. Drawing
* implementation must use gdk_draw_context_get_frame_region() to query the
* region that must be drawn.
* implementation must use [method@Gdk.DrawContext.get_frame_region() to
* query the region that must be drawn.
*
* When using GTK, the widget system automatically places calls to
* gdk_draw_context_begin_frame() and gdk_draw_context_end_frame() via the
* use of #GskRenderers, so application code does not need to call these
* functions explicitly.
* use of [class@Gsk.Renderer]s, so application code does not need to call
* these functions explicitly.
*/
void
gdk_draw_context_begin_frame (GdkDrawContext *context,
@ -342,13 +336,14 @@ region_get_pixels (cairo_region_t *region)
/**
* gdk_draw_context_end_frame:
* @context: a #GdkDrawContext
* @context: a `GdkDrawContext`
*
* Ends a drawing operation started with gdk_draw_context_begin_frame()
* and makes the drawing available on screen. See that function for more
* details about drawing.
* Ends a drawing operation started with gdk_draw_context_begin_frame().
*
* When using a #GdkGLContext, this function may call `glFlush()`
* This makes the drawing available on screen.
* See [method@Gdk.DrawContext.begin_frame] for more details about drawing.
*
* When using a [class@Gdk.GLContext], this function may call `glFlush()`
* implicitly before returning; it is not recommended to call `glFlush()`
* explicitly before calling this function.
*/
@ -389,14 +384,14 @@ gdk_draw_context_end_frame (GdkDrawContext *context)
* gdk_draw_context_get_frame_region:
* @context: a #GdkDrawContext
*
* Retrieves the region that is currently in the process of being repainted.
* Retrieves the region that is currently being repainted.
*
* After a call to gdk_draw_context_begin_frame() this function will return
* a union of the region passed to that function and the area of the surface
* that the @context determined needs to be repainted.
* After a call to [method@Gdk.DrawContext.begin_frame] this function will
* return a union of the region passed to that function and the area of the
* surface that the @context determined needs to be repainted.
*
* If @context is not in between calls to gdk_draw_context_begin_frame() and
* gdk_draw_context_end_frame(), %NULL will be returned.
* If @context is not in between calls to [method@Gdk.DrawContext.begin_frame]
* and [method@Gdk.DrawContext.end_frame], %NULL will be returned.
*
* Returns: (transfer none) (nullable): a Cairo region or %NULL if not drawing
* a frame.

179
gdk/gdkdrop.c
View File

@ -18,17 +18,14 @@
*/
/**
* SECTION:gdkdrop
* @Title: Drag And Drop
* @Short_description: Functions for controlling drag and drop handling
* GdkDrop:
*
* These functions provide a low-level interface for drag and drop.
* The `GdkDrop` object represents the target of an ongoing DND operation.
*
* The `GdkDrop` object represents the target side of an ongoing DND operation.
* Possible drop sites get informed about the status of the ongoing drag operation
* with events of type %GDK_DRAG_ENTER, %GDK_DRAG_LEAVE, %GDK_DRAG_MOTION and
* %GDK_DROP_START. The `GdkDrop` object can be obtained from these
* [class@Gdk.Event] types using [method@Gdk.DndEvent.get_drop].
* Possible drop sites get informed about the status of the ongoing drag
* operation with events of type %GDK_DRAG_ENTER, %GDK_DRAG_LEAVE,
* %GDK_DRAG_MOTION and %GDK_DROP_START. The `GdkDrop` object can be obtained
* from these [class@Gdk.Event] types using [method@Gdk.DNDEvent.get_drop].
*
* The actual data transfer is initiated from the target side via an async
* read, using one of the `GdkDrop` methods for this purpose:
@ -88,13 +85,6 @@ static GParamSpec *properties[N_PROPERTIES] = { NULL, };
G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GdkDrop, gdk_drop, G_TYPE_OBJECT)
/**
* GdkDrop:
*
* The GdkDrop struct contains only private fields and
* should not be accessed directly.
*/
static void
gdk_drop_default_status (GdkDrop *self,
GdkDragAction actions,
@ -345,7 +335,7 @@ gdk_drop_class_init (GdkDropClass *klass)
/**
* GdkDrop:device:
*
* The #GdkDevice performing the drop
* The `GdkDevice` performing the drop
*/
properties[PROP_DEVICE] =
g_param_spec_object ("device",
@ -360,7 +350,7 @@ gdk_drop_class_init (GdkDropClass *klass)
/**
* GdkDrop:display:
*
* The #GdkDisplay that the drop belongs to.
* The `GdkDisplay` that the drop belongs to.
*/
properties[PROP_DISPLAY] =
g_param_spec_object ("display",
@ -374,7 +364,7 @@ gdk_drop_class_init (GdkDropClass *klass)
/**
* GdkDrop:drag:
*
* The #GdkDrag that initiated this drop
* The `GdkDrag` that initiated this drop
*/
properties[PROP_DRAG] =
g_param_spec_object ("drag",
@ -404,7 +394,7 @@ gdk_drop_class_init (GdkDropClass *klass)
/**
* GdkDrop:surface:
*
* The #GdkSurface the drop happens on
* The `GdkSurface` the drop happens on
*/
properties[PROP_SURFACE] =
g_param_spec_object ("surface",
@ -426,12 +416,12 @@ gdk_drop_init (GdkDrop *self)
/**
* gdk_drop_get_display:
* @self: a #GdkDrop
* @self: a `GdkDrop`
*
* Gets the #GdkDisplay that @self was created for.
* Gets the `GdkDisplay` that @self was created for.
*
* Returns: (transfer none): a #GdkDisplay
**/
* Returns: (transfer none): a `GdkDisplay`
*/
GdkDisplay *
gdk_drop_get_display (GdkDrop *self)
{
@ -444,12 +434,12 @@ gdk_drop_get_display (GdkDrop *self)
/**
* gdk_drop_get_device:
* @self: a #GdkDrop
* @self: a `GdkDrop`
*
* Returns the #GdkDevice performing the drop.
* Returns the `GdkDevice` performing the drop.
*
* Returns: (transfer none): The #GdkDevice performing the drop.
**/
* Returns: (transfer none): The `GdkDevice` performing the drop.
*/
GdkDevice *
gdk_drop_get_device (GdkDrop *self)
{
@ -462,13 +452,13 @@ gdk_drop_get_device (GdkDrop *self)
/**
* gdk_drop_get_formats:
* @self: a #GdkDrop
* @self: a `GdkDrop`
*
* Returns the #GdkContentFormats that the drop offers the data
* Returns the `GdkContentFormats` that the drop offers the data
* to be read in.
*
* Returns: (transfer none): The possible #GdkContentFormats
**/
* Returns: (transfer none): The possible `GdkContentFormats`
*/
GdkContentFormats *
gdk_drop_get_formats (GdkDrop *self)
{
@ -481,12 +471,12 @@ gdk_drop_get_formats (GdkDrop *self)
/**
* gdk_drop_get_surface:
* @self: a #GdkDrop
* @self: a `GdkDrop`
*
* Returns the #GdkSurface performing the drop.
* Returns the `GdkSurface` performing the drop.
*
* Returns: (transfer none): The #GdkSurface performing the drop.
**/
* Returns: (transfer none): The `GdkSurface` performing the drop.
*/
GdkSurface *
gdk_drop_get_surface (GdkDrop *self)
{
@ -499,23 +489,25 @@ gdk_drop_get_surface (GdkDrop *self)
/**
* gdk_drop_get_actions:
* @self: a #GdkDrop
* @self: a `GdkDrop`
*
* Returns the possible actions for this #GdkDrop. If this value
* contains multiple actions - ie gdk_drag_action_is_unique()
* returns %FALSE for the result - gdk_drop_finish() must choose
* the action to use when accepting the drop. This will only
* happen if you passed %GDK_ACTION_ASK as one of the possible
* actions in gdk_drop_status(). %GDK_ACTION_ASK itself will not
* Returns the possible actions for this `GdkDrop`.
*
* If this value contains multiple actions - i.e.
* [func@Gdk.DragAction.is_unique] returns %FALSE for the result -
* [method@Gdk.Drop.finish] must choose the action to use when
* accepting the drop. This will only happen if you passed
* %GDK_ACTION_ASK as one of the possible actions in
* [method@Gdk.Drop.status]. %GDK_ACTION_ASK itself will not
* be included in the actions returned by this function.
*
* This value may change over the lifetime of the #GdkDrop both
* as a response to source side actions as well as to calls to
* gdk_drop_status() or gdk_drop_finish(). The source side will
* not change this value anymore once a drop has started.
* This value may change over the lifetime of the [class@Gdk.Drop]
* both as a response to source side actions as well as to calls to
* [method@Gdk.Drop.status] or [method@Gdk.Drop.finish]. The source
* side will not change this value anymore once a drop has started.
*
* Returns: The possible #GdkDragActions
**/
* Returns: The possible `GdkDragActions`
*/
GdkDragAction
gdk_drop_get_actions (GdkDrop *self)
{
@ -546,15 +538,15 @@ gdk_drop_set_actions (GdkDrop *self,
/**
* gdk_drop_get_drag:
* @self: a #GdkDrop
* @self: a `GdkDrop`
*
* If this is an in-app drag-and-drop operation, returns the #GdkDrag
* If this is an in-app drag-and-drop operation, returns the `GdkDrag`
* that corresponds to this drop.
*
* If it is not, %NULL is returned.
*
* Returns: (transfer none) (nullable): the corresponding #GdkDrag
**/
* Returns: (transfer none) (nullable): the corresponding `GdkDrag`
*/
GdkDrag *
gdk_drop_get_drag (GdkDrop *self)
{
@ -567,16 +559,16 @@ gdk_drop_get_drag (GdkDrop *self)
/**
* gdk_drop_status:
* @self: a #GdkDrop
* @self: a `GdkDrop`
* @actions: Supported actions of the destination, or 0 to indicate
* that a drop will not be accepted
* @preferred: A unique action that's a member of @actions indicating the
* preferred action.
* preferred action
*
* Selects all actions that are potentially supported by the destination.
*
* When calling this function, do not restrict the passed in actions to
* the ones provided by gdk_drop_get_actions(). Those actions may
* the ones provided by [method@Gdk.Drop.get_actions]. Those actions may
* change in the future, even depending on the actions you provide here.
*
* The @preferred action is a hint to the drag'n'drop mechanism about which
@ -606,15 +598,14 @@ gdk_drop_status (GdkDrop *self,
/**
* gdk_drop_finish:
* @self: a #GdkDrop
* @action: the action performed by the destination or 0 if the drop
* failed
* @self: a `GdkDrop`
* @action: the action performed by the destination or 0 if the drop failed
*
* Ends the drag operation after a drop.
*
*
* The @action must be a single action selected from the actions
* available via gdk_drop_get_actions().
**/
* available via [method@Gdk.Drop.get_actions].
*/
void
gdk_drop_finish (GdkDrop *self,
GdkDragAction action)
@ -664,17 +655,17 @@ gdk_drop_read_internal (GdkDrop *self,
/**
* gdk_drop_read_async:
* @self: a #GdkDrop
* @self: a `GdkDrop`
* @mime_types: (array zero-terminated=1) (element-type utf8):
* pointer to an array of mime types
* @io_priority: the io priority for the read operation
* @cancellable: (allow-none): optional #GCancellable object,
* @io_priority: the I/O priority for the read operation
* @cancellable: (allow-none): optional `GCancellable` object,
* %NULL to ignore
* @callback: (scope async): a #GAsyncReadyCallback to call when
* @callback: (scope async): a `GAsyncReadyCallback` to call when
* the request is satisfied
* @user_data: (closure): the data to pass to @callback
*
* Asynchronously read the dropped data from a #GdkDrop
* Asynchronously read the dropped data from a `GdkDrop`
* in a format that complies with one of the mime types.
*/
void
@ -701,14 +692,16 @@ gdk_drop_read_async (GdkDrop *self,
/**
* gdk_drop_read_finish:
* @self: a #GdkDrop
* @result: a #GAsyncResult
* @self: a `GdkDrop`
* @result: a `GAsyncResult`
* @out_mime_type: (out) (type utf8): return location for the used mime type
* @error: (allow-none): location to store error information on failure, or %NULL
*
* Finishes an async drop read operation, see gdk_drop_read_async().
* Finishes an async drop read operation.
*
* Returns: (nullable) (transfer full): the #GInputStream, or %NULL
* See [method@Gdk.Drop.read_async].
*
* Returns: (nullable) (transfer full): the `GInputStream`, or %NULL
*/
GInputStream *
gdk_drop_read_finish (GdkDrop *self,
@ -851,23 +844,24 @@ gdk_drop_read_value_internal (GdkDrop *self,
/**
* gdk_drop_read_value_async:
* @self: a #GdkDrop
* @type: a #GType to read
* @io_priority: the [I/O priority][io-priority]
* of the request.
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @self: a `GdkDrop`
* @type: a `GType` to read
* @io_priority: the I/O priority of the request.
* @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
* @callback: (scope async): callback to call when the request is satisfied
* @user_data: (closure): the data to pass to callback function
*
* Asynchronously request the drag operation's contents converted to the given
* @type. When the operation is finished @callback will be called.
* You can then call gdk_drop_read_value_finish() to get the resulting
* #GValue.
* Asynchronously request the drag operation's contents converted
* to the given @type.
*
* For local drag'n'drop operations that are available in the given #GType, the
* value will be copied directly. Otherwise, GDK will try to use
* gdk_content_deserialize_async() to convert the data.
**/
* When the operation is finished @callback will be called. You must
* then call [method@Gdk.Drop.read_value_finish] to get the resulting
* `GValue`.
*
* For local drag'n'drop operations that are available in the given
* `GType`, the value will be copied directly. Otherwise, GDK will
* try to use [func@Gdk.content_deserialize_async] to convert the data.
*/
void
gdk_drop_read_value_async (GdkDrop *self,
GType type,
@ -891,16 +885,16 @@ gdk_drop_read_value_async (GdkDrop *self,
/**
* gdk_drop_read_value_finish:
* @self: a #GdkDrop
* @result: a #GAsyncResult
* @error: a #GError location to store the error occurring, or %NULL to
* ignore.
* @self: a `GdkDrop`
* @result: a `GAsyncResult`
* @error: a `GError` location to store the error occurring, or %NULL to ignore
*
* Finishes an async drop read started with
* gdk_drop_read_value_async().
* Finishes an async drop read.
*
* Returns: (transfer none): a #GValue containing the result.
**/
* See [method@Gdk.Drop.read_value_async].
*
* Returns: (transfer none): a `GValue` containing the result.
*/
const GValue *
gdk_drop_read_value_finish (GdkDrop *self,
GAsyncResult *result,
@ -1019,4 +1013,3 @@ gdk_drop_emit_drop_event (GdkDrop *self,
gdk_drop_do_emit_event (event, dont_queue);
}

230
gdk/gdkevents.c
View File

@ -41,8 +41,8 @@
/**
* GdkEvent: (ref-func gdk_event_ref) (unref-func gdk_event_unref)
*
* `GdkEvent` and its derived types are immutable data structures,
* created by GTK itself to represent windowing system events.
* `GdkEvent`s are immutable data structures, created by GDK to
* represent windowing system events.
*
* In GTK applications the events are handled automatically by toplevel
* widgets and passed on to the event controllers of appropriate widgets,
@ -52,7 +52,7 @@
/**
* GdkEventSequence:
*
* GdkEventSequence is an opaque type representing a sequence
* `GdkEventSequence` is an opaque type representing a sequence
* of related touch events.
*/
@ -338,9 +338,9 @@ static GType gdk_event_types[GDK_EVENT_LAST];
/*< private >
* GDK_EVENT_TYPE_SLOT:
* @ETYPE: a #GdkEventType
* @ETYPE: a `GdkEvent`Type
*
* Associates a #GdkEvent type with the given #GdkEventType enumeration.
* Associates a `GdkEvent` type with the given `GdkEvent`Type enumeration.
*
* This macro can only be used with %GDK_DEFINE_EVENT_TYPE.
*/
@ -350,10 +350,10 @@ static GType gdk_event_types[GDK_EVENT_LAST];
* GDK_DEFINE_EVENT_TYPE:
* @TypeName: the type name, in camel case
* @type_name: the type name, in snake case
* @type_info: the address of the #GdkEventTypeInfo for the event type
* @type_info: the address of the `GdkEvent`TypeInfo for the event type
* @_C_: custom code to call after registering the event type
*
* Registers a new #GdkEvent subclass with the given @TypeName and @type_info.
* Registers a new `GdkEvent` subclass with the given @TypeName and @type_info.
*
* Similarly to %G_DEFINE_TYPE_WITH_CODE, this macro will generate a `get_type()`
* function that registers the event type.
@ -381,15 +381,15 @@ type_name ## _get_type (void) \
/*< private >
* gdk_event_alloc:
* @event_type: the #GdkEventType to allocate
* @event_type: the `GdkEvent`Type to allocate
* @surface: (nullable): the #GdkSurface of the event
* @device: (nullable): the #GdkDevice of the event
* @time_: the event serial
*
* Allocates a #GdkEvent for the given @event_type, and sets its
* Allocates a `GdkEvent` for the given @event_type, and sets its
* common fields with the given parameters.
*
* Returns: (transfer full): the newly allocated #GdkEvent instance
* Returns: (transfer full): the newly allocated `GdkEvent` instance
*/
static gpointer
gdk_event_alloc (GdkEventType event_type,
@ -820,7 +820,7 @@ _gdk_event_queue_flush (GdkDisplay *display)
/**
* gdk_event_ref:
* @event: a #GdkEvent
* @event: a `GdkEvent`
*
* Increase the ref count of @event.
*
@ -838,10 +838,11 @@ gdk_event_ref (GdkEvent *event)
/**
* gdk_event_unref:
* @event: (transfer full): a #GdkEvent
* @event: (transfer full): a `GdkEvent`
*
* Decrease the ref count of @event, and free it
* if the last reference is dropped.
* Decrease the ref count of @event.
*
* If the last reference is dropped, the structure is freed.
*/
void
gdk_event_unref (GdkEvent *event)
@ -854,10 +855,11 @@ gdk_event_unref (GdkEvent *event)
/**
* gdk_event_get_pointer_emulated:
* @event: a #GdkEvent
* @event: a `GdkEvent`
*
* Returns whether this event is an 'emulated' pointer event (typically
* from a touch event), as opposed to a real one.
* Returns whether this event is an 'emulated' pointer event.
*
* Emulated pointer events typically originate from a touch events.
*
* Returns: %TRUE if this event is emulated
*/
@ -893,7 +895,7 @@ gdk_event_get_pointer_emulated (GdkEvent *event)
/**
* gdk_event_get_axis:
* @event: a #GdkEvent
* @event: a `GdkEvent`
* @axis_use: the axis use to look for
* @value: (out): location to store the value found
*
@ -901,7 +903,7 @@ gdk_event_get_pointer_emulated (GdkEvent *event)
* an event structure.
*
* Returns: %TRUE if the specified axis was found, otherwise %FALSE
**/
*/
gboolean
gdk_event_get_axis (GdkEvent *event,
GdkAxisUse axis_use,
@ -936,17 +938,18 @@ gdk_event_get_axis (GdkEvent *event,
/**
* gdk_event_triggers_context_menu:
* @event: a #GdkEvent, currently only button events are meaningful values
* @event: a `GdkEvent`, currently only button events are meaningful values
*
* This function returns whether a #GdkEvent should trigger a
* context menu, according to platform conventions. The right
* mouse button always triggers context menus.
* Returns whether a `GdkEvent` should trigger a context menu,
* according to platform conventions.
*
* The right mouse button typically triggers context menus.
*
* This function should always be used instead of simply checking for
* event->button == %GDK_BUTTON_SECONDARY.
*
* Returns: %TRUE if the event should trigger a context menu.
**/
*/
gboolean
gdk_event_triggers_context_menu (GdkEvent *event)
{
@ -997,12 +1000,14 @@ gdk_events_get_axis_distances (GdkEvent *event1,
/**
* gdk_events_get_distance:
* @event1: first #GdkEvent
* @event2: second #GdkEvent
* @event1: first `GdkEvent`
* @event2: second `GdkEvent`
* @distance: (out): return location for the distance
*
* If both events have X/Y information, the distance between both coordinates
* (as in a straight line going from @event1 to @event2) will be returned.
* Returns the distance between the event locations.
*
* This assumes that both events have X/Y information.
* If not, this function returns %FALSE.
*
* Returns: %TRUE if the distance could be calculated.
**/
@ -1018,17 +1023,21 @@ gdk_events_get_distance (GdkEvent *event1,
/**
* gdk_events_get_angle:
* @event1: first #GdkEvent
* @event2: second #GdkEvent
* @event1: first `GdkEvent`
* @event2: second `GdkEvent`
* @angle: (out): return location for the relative angle between both events
*
* If both events contain X/Y information, this function will return %TRUE
* and return in @angle the relative angle from @event1 to @event2. The rotation
* direction for positive angles is from the positive X axis towards the positive
* Y axis.
* Returns the relative angle from @event1 to @event2.
*
* The relative angle is the angle between the X axis and the line
* through both events' positions. The rotation direction for positive
* angles is from the positive X axis towards the positive Y axis.
*
* This assumes that both events have X/Y information.
* If not, this function returns %FALSE.
*
* Returns: %TRUE if the angle could be calculated.
**/
*/
gboolean
gdk_events_get_angle (GdkEvent *event1,
GdkEvent *event2,
@ -1060,16 +1069,18 @@ gdk_events_get_angle (GdkEvent *event1,
/**
* gdk_events_get_center:
* @event1: first #GdkEvent
* @event2: second #GdkEvent
* @event1: first `GdkEvent`
* @event2: second `GdkEvent`
* @x: (out): return location for the X coordinate of the center
* @y: (out): return location for the Y coordinate of the center
*
* If both events contain X/Y information, the center of both coordinates
* will be returned in @x and @y.
* Returns the point halfway between the events' positions.
*
* This assumes that both events have X/Y information.
* If not, this function returns %FALSE.
*
* Returns: %TRUE if the center could be calculated.
**/
*/
gboolean
gdk_events_get_center (GdkEvent *event1,
GdkEvent *event2,
@ -1111,14 +1122,14 @@ G_DEFINE_BOXED_TYPE (GdkEventSequence, gdk_event_sequence,
/**
* gdk_event_get_axes:
* @event: a #GdkEvent
* @event: a `GdkEvent`
* @axes: (transfer none) (out) (array length=n_axes): the array of values for all axes
* @n_axes: (out): the length of array
*
* Extracts all axis values from an event.
*
* Returns: %TRUE on success, otherwise %FALSE
**/
*/
gboolean
gdk_event_get_axes (GdkEvent *event,
double **axes,
@ -1147,11 +1158,11 @@ gdk_event_dup_axes (GdkEvent *event)
/**
* gdk_event_get_event_type:
* @event: a #GdkEvent
* @event: a `GdkEvent`
*
* Retrieves the type of the event.
*
* Returns: a #GdkEventType
* Returns: a `GdkEvent`Type
*/
GdkEventType
gdk_event_get_event_type (GdkEvent *event)
@ -1163,9 +1174,9 @@ gdk_event_get_event_type (GdkEvent *event)
/**
* gdk_event_get_surface:
* @event: a #GdkEvent
* @event: a `GdkEvent`
*
* Extracts the #GdkSurface associated with an event.
* Extracts the surface associated with an event.
*
* Returns: (transfer none): The #GdkSurface associated with the event
*/
@ -1179,7 +1190,7 @@ gdk_event_get_surface (GdkEvent *event)
/**
* gdk_event_get_seat:
* @event: a #GdkEvent
* @event: a `GdkEvent`
*
* Returns the seat that originated the event.
*
@ -1195,7 +1206,7 @@ gdk_event_get_seat (GdkEvent *event)
/**
* gdk_event_get_device:
* @event: a #GdkEvent.
* @event: a `GdkEvent`.
*
* Returns the device of an event.
*
@ -1211,16 +1222,18 @@ gdk_event_get_device (GdkEvent *event)
/**
* gdk_event_get_device_tool:
* @event: a #GdkEvent
* @event: a `GdkEvent`
*
* If the event was generated by a device that supports
* different tools (eg. a tablet), this function will
* return a #GdkDeviceTool representing the tool that
* caused the event. Otherwise, %NULL will be returned.
* Returns a `GdkDeviceTool` representing the tool that
* caused the event.
*
* Note: the #GdkDeviceTools will be constant during
* If the was not generated by a device that supports
* different tools (such as a tablet), this function will
* return %NULL.
*
* Note: the `GdkDeviceTool` will be constant during
* the application lifetime, if settings must be stored
* persistently across runs, see gdk_device_tool_get_serial()
* persistently across runs, see [method@Gdk.DeviceTool.get_serial].
*
* Returns: (transfer none) (nullable): The current device tool, or %NULL
**/
@ -1234,13 +1247,15 @@ gdk_event_get_device_tool (GdkEvent *event)
/**
* gdk_event_get_time:
* @event: a #GdkEvent
* @event: a `GdkEvent`
*
* Returns the time stamp from @event, if there is one; otherwise
* returns #GDK_CURRENT_TIME.
* Returns the timestamp of @event.
*
* Returns: time stamp field from @event
**/
* Not all events have timestamps. In that case, this function
* returns %GDK_CURRENT_TIME.
*
* Returns: timestamp field from @event
*/
guint32
gdk_event_get_time (GdkEvent *event)
{
@ -1251,9 +1266,9 @@ gdk_event_get_time (GdkEvent *event)
/**
* gdk_event_get_display:
* @event: a #GdkEvent
* @event: a `GdkEvent`
*
* Retrieves the #GdkDisplay associated to the @event.
* Retrieves the display associated to the @event.
*
* Returns: (transfer none) (nullable): a #GdkDisplay
*/
@ -1270,10 +1285,12 @@ gdk_event_get_display (GdkEvent *event)
/**
* gdk_event_get_event_sequence:
* @event: a #GdkEvent
* @event: a `GdkEvent`
*
* If @event is a touch event, returns the #GdkEventSequence
* to which the event belongs. Otherwise, return %NULL.
* Retuns the event sequence to which the event belongs.
*
* Related touch events are connected in a sequence. Other
* events typically don't have event sequence information.
*
* Returns: (transfer none): the event sequence that the event belongs to
*/
@ -1287,12 +1304,12 @@ gdk_event_get_event_sequence (GdkEvent *event)
/**
* gdk_event_get_modifier_state:
* @event: a #GdkEvent
* @event: a `GdkEvent`
*
* Returns the modifier state field of an event.
*
* Returns: the modifier state of @event
**/
*/
GdkModifierType
gdk_event_get_modifier_state (GdkEvent *event)
{
@ -1303,12 +1320,12 @@ gdk_event_get_modifier_state (GdkEvent *event)
/**
* gdk_event_get_position:
* @event: a #GdkEvent
* @event: a `GdkEvent`
* @x: (out): location to put event surface x coordinate
* @y: (out): location to put event surface y coordinate
*
* Extract the event surface relative x/y coordinates from an event.
**/
*/
gboolean
gdk_event_get_position (GdkEvent *event,
double *x,
@ -1324,7 +1341,7 @@ gdk_event_get_position (GdkEvent *event,
/**
* GdkButtonEvent:
*
* An event related to a button on a pointer device/
* An event related to a button on a pointer device.
*/
static void
@ -1484,8 +1501,8 @@ GDK_DEFINE_EVENT_TYPE (GdkKeyEvent, gdk_key_event,
/*< private >
* gdk_key_event_new:
* @type: the event type, either %GDK_KEY_PRESS or %GDK_KEY_RELEASE
* @surface: the #GdkSurface of the event
* @device: the #GdkDevice related to the event
* @surface: the surface of the event
* @device: the device related to the event
* @time: the event's timestamp
* @keycode: the keycode of the event
* @state: the modifiers state
@ -1493,9 +1510,9 @@ GDK_DEFINE_EVENT_TYPE (GdkKeyEvent, gdk_key_event,
* @translated: the translated key data for the given @state
* @no_lock: the translated key data without the given @state
*
* Creates a new #GdkKeyEvent.
* Creates a new `GdkKeyEvent`.
*
* Returns: (transfer full) (type GdkKeyEvent): the newly created #GdkEvent
* Returns: (transfer full) (type GdkKeyEvent): the newly created `GdkEvent`
*/
GdkEvent *
gdk_key_event_new (GdkEventType type,
@ -1671,17 +1688,20 @@ gdk_key_event_is_modifier (GdkEvent *event)
/**
* gdk_key_event_matches:
* @event: (type GdkKeyEvent): a key #GdkEvent
* @event: (type GdkKeyEvent): a key `GdkEvent`
* @keyval: the keyval to match
* @modifiers: the modifiers to match
*
* Matches a key event against a keyboard shortcut that is specified
* as a keyval and modifiers. Partial matches are possible where the
* combination matches if the currently active group is ignored.
* Matches a key event against a keyval and modifiers.
*
* This is typically used to trigger keyboard shortcuts such as Ctrl-C.
*
* Partial matches are possible where the combination matches
* if the currently active group is ignored.
*
* Note that we ignore Caps Lock for matching.
*
* Returns: a GdkKeyMatch value describing whether @event matches
* Returns: a `GdkKeyMatch` value describing whether @event matches
*/
GdkKeyMatch
gdk_key_event_matches (GdkEvent *event,
@ -1773,12 +1793,14 @@ gdk_key_event_matches (GdkEvent *event,
/**
* gdk_key_event_get_match:
* @event: (type GdkKeyEvent): a key #GdkEvent
* @event: (type GdkKeyEvent): a key `GdkEvent`
* @keyval: (out): return location for a keyval
* @modifiers: (out): return location for modifiers
*
* Gets a keyval and modifier combination that will cause
* gdk_key_event_matches() to successfully match the given event.
* Gets a keyval and modifier combination that will match
* the event.
*
* See [method@Gdk.KeyEvent.matches].
*
* Returns: %TRUE on success
*/
@ -2153,7 +2175,7 @@ gdk_delete_event_new (GdkSurface *surface)
/**
* GdkFocusEvent:
*
* An event related to a focus change.
* An event related to a keyboard focus change.
*/
static const GdkEventTypeInfo gdk_focus_event_info = {
@ -2345,11 +2367,13 @@ gdk_scroll_event_get_deltas (GdkEvent *event,
* gdk_scroll_event_is_stop:
* @event: (type GdkScrollEvent): a scroll event
*
* Check whether a scroll event is a stop scroll event. Scroll sequences
* with smooth scroll information may provide a stop scroll event once the
* interaction with the device finishes, e.g. by lifting a finger. This
* stop scroll event is the signal that a widget may trigger kinetic
* scrolling based on the current velocity.
* Check whether a scroll event is a stop scroll event.
*
* Scroll sequences with smooth scroll information may provide
* a stop scroll event once the interaction with the device finishes,
* e.g. by lifting a finger. This stop scroll event is the signal
* that a widget may trigger kinetic scrolling based on the current
* velocity.
*
* Stop scroll events always have a delta of 0/0.
*
@ -2373,7 +2397,12 @@ gdk_scroll_event_is_stop (GdkEvent *event)
/**
* GdkTouchpadEvent:
*
* An event related to a touchpad device.
* An event related to a gesture on a touchpad device.
*
* Unlike touchscreens, where the windowing system sends basic
* sequences of begin, update, end events, and leaves gesture
* recognition to the clients, touchpad gestures are typically
* processed by the system, resulting in these events.
*/
static GdkModifierType
@ -2469,7 +2498,7 @@ gdk_touchpad_event_new_pinch (GdkSurface *surface,
/**
* gdk_touchpad_event_get_gesture_phase:
* @event: (type GdkTouchpadEvent): a touchpad #GdkEvent
* @event: (type GdkTouchpadEvent): a touchpad event
*
* Extracts the touchpad gesture phase from a touchpad event.
*
@ -2514,7 +2543,7 @@ gdk_touchpad_event_get_n_fingers (GdkEvent *event)
* @dy: (out): return location for y
*
* Extracts delta information from a touchpad event.
**/
*/
void
gdk_touchpad_event_get_deltas (GdkEvent *event,
double *dx,
@ -2680,7 +2709,7 @@ gdk_pad_event_new_group_mode (GdkSurface *surface,
* a pad event.
*
* Returns: the button of @event
**/
*/
guint
gdk_pad_event_get_button (GdkEvent *event)
{
@ -2700,7 +2729,7 @@ gdk_pad_event_get_button (GdkEvent *event)
* @value: (out): Return location for the axis value
*
* Extracts the information from a pad strip or ring event.
**/
*/
void
gdk_pad_event_get_axis_value (GdkEvent *event,
guint *index,
@ -2723,7 +2752,7 @@ gdk_pad_event_get_axis_value (GdkEvent *event,
* @mode: (out): return location for the mode
*
* Extracts group and mode information from a pad event.
**/
*/
void
gdk_pad_event_get_group_mode (GdkEvent *event,
guint *group,
@ -2850,16 +2879,17 @@ gdk_motion_event_new (GdkSurface *surface,
/**
* gdk_event_get_history:
* @event: a motion or scroll #GdkEvent
* @event: a motion or scroll event
* @out_n_coords: (out): Return location for the length of the returned array
*
* Retrieves the history of the @event, as a list of time and coordinates.
* Retrieves the history of the device that @event is for, as a list of
* time and coordinates.
*
* The history includes events that are not delivered to the application
* because they occurred in the same frame as @event.
* The history includes positions that are not delivered as separate events
* to the application because they occurred in the same frame as @event.
*
* Note that only motion and scroll events record history, and motion
* events only if one of the mouse buttons is down.
* events do it only if one of the mouse buttons is down.
*
* Returns: (transfer container) (array length=out_n_coords) (nullable): an
* array of time and coordinates
@ -3053,7 +3083,7 @@ gdk_dnd_event_new (GdkEventType type,
* gdk_dnd_event_get_drop:
* @event: (type GdkDNDEvent): a DND event
*
* Gets the #GdkDrop from a DND event.
* Gets the `GdkDrop` object from a DND event.
*
* Returns: (transfer none) (nullable): the drop
**/

21
gdk/gdkevents.h
View File

@ -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,

215
gdk/gdkframeclock.c
View File

@ -28,52 +28,43 @@
#include "gdkinternals.h"
/**
* SECTION:gdkframeclock
* @Title: GdkFrameClock
* @Short_description: Synchronizes painting to a surface
* GdkFrameClock:
*
* A #GdkFrameClock tells the application when to update and repaint
* a surface. This may be synced to the vertical refresh rate of the
* monitor, for example. Even when the frame clock uses a simple timer
* rather than a hardware-based vertical sync, the frame clock helps
* because it ensures everything paints at the same time (reducing the
* total number of frames). The frame clock can also automatically
* stop painting when it knows the frames will not be visible, or
* scale back animation framerates.
* A `GdkFrameClock` tells the application when to update and repaint
* a surface.
*
* #GdkFrameClock is designed to be compatible with an OpenGL-based
* implementation or with mozRequestAnimationFrame in Firefox,
* for example.
* This may be synced to the vertical refresh rate of the monitor, for example.
* Even when the frame clock uses a simple timer rather than a hardware-based
* vertical sync, the frame clock helps because it ensures everything paints at
* the same time (reducing the total number of frames).
*
* The frame clock can also automatically stop painting when it knows the frames
* will not be visible, or scale back animation framerates.
*
* `GdkFrameClock` is designed to be compatible with an OpenGL-based implementation
* or with mozRequestAnimationFrame in Firefox, for example.
*
* A frame clock is idle until someone requests a frame with
* gdk_frame_clock_request_phase(). At some later point that makes
* sense for the synchronization being implemented, the clock will
* process a frame and emit signals for each phase that has been
* requested. (See the signals of the #GdkFrameClock class for
* documentation of the phases. %GDK_FRAME_CLOCK_PHASE_UPDATE and the
* #GdkFrameClock::update signal are most interesting for application
* writers, and are used to update the animations, using the frame time
* given by gdk_frame_clock_get_frame_time().
* [method@Gdk.FrameClock.request_phase]. At some later point that makes sense
* for the synchronization being implemented, the clock will process a frame and
* emit signals for each phase that has been requested. (See the signals of the
* `GdkFrameClock` class for documentation of the phases.
* %GDK_FRAME_CLOCK_PHASE_UPDATE and the [signal@GdkFrameClock::update] signal
* are most interesting for application writers, and are used to update the
* animations, using the frame time given by [metohd@Gdk.FrameClock.get_frame_time].
*
* The frame time is reported in microseconds and generally in the same
* timescale as g_get_monotonic_time(), however, it is not the same
* as g_get_monotonic_time(). The frame time does not advance during
* the time a frame is being painted, and outside of a frame, an attempt
* is made so that all calls to gdk_frame_clock_get_frame_time() that
* is made so that all calls to [method@Gdk.FrameClock.get_frame_time] that
* are called at a “similar” time get the same value. This means that
* if different animations are timed by looking at the difference in
* time between an initial value from gdk_frame_clock_get_frame_time()
* and the value inside the #GdkFrameClock::update signal of the clock,
* time between an initial value from [method@Gdk.FrameClock.get_frame_time]
* and the value inside the [signal@GdkFrameClock::update] signal of the clock,
* they will stay exactly synchronized.
*/
/**
* GdkFrameClock:
*
* The GdkFrameClock struct contains only private fields and
* should not be accessed directly.
*/
enum {
FLUSH_EVENTS,
BEFORE_PAINT,
@ -138,9 +129,10 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass)
* GdkFrameClock::flush-events:
* @clock: the frame clock emitting the signal
*
* This signal is used to flush pending motion events that
* are being batched up and compressed together. Applications
* should not handle this signal.
* Used to flush pending motion events that are being batched up and
* compressed together.
*
* Applications should not handle this signal.
*/
signals[FLUSH_EVENTS] =
g_signal_new (g_intern_static_string ("flush-events"),
@ -154,8 +146,9 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass)
* GdkFrameClock::before-paint:
* @clock: the frame clock emitting the signal
*
* This signal begins processing of the frame. Applications
* should generally not handle this signal.
* Begins processing of the frame.
*
* Applications should generally not handle this signal.
*/
signals[BEFORE_PAINT] =
g_signal_new (g_intern_static_string ("before-paint"),
@ -169,12 +162,12 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass)
* GdkFrameClock::update:
* @clock: the frame clock emitting the signal
*
* This signal is emitted as the first step of toolkit and
* application processing of the frame. Animations should
* be updated using gdk_frame_clock_get_frame_time().
* Applications can connect directly to this signal, or
* use gtk_widget_add_tick_callback() as a more convenient
* interface.
* Emitted as the first step of toolkit and application processing
* of the frame.
*
* Animations should be updated using [method@Gdk.FrameClock.get_frame_time].
* Applications can connect directly to this signal, or use
* [method@Gtk.Widget.add_tick_callback] as a more convenient interface.
*/
signals[UPDATE] =
g_signal_new (g_intern_static_string ("update"),
@ -188,10 +181,11 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass)
* GdkFrameClock::layout:
* @clock: the frame clock emitting the signal
*
* This signal is emitted as the second step of toolkit and
* application processing of the frame. Any work to update
* sizes and positions of application elements should be
* performed. GTK normally handles this internally.
* Emitted as the second step of toolkit and application processing
* of the frame.
*
* Any work to update sizes and positions of application elements
* should be performed. GTK normally handles this internally.
*/
signals[LAYOUT] =
g_signal_new (g_intern_static_string ("layout"),
@ -205,11 +199,12 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass)
* GdkFrameClock::paint:
* @clock: the frame clock emitting the signal
*
* This signal is emitted as the third step of toolkit and
* application processing of the frame. The frame is
* repainted. GDK normally handles this internally and
* emits #GdkSurface::render which are turned into
* #GtkWidget::snapshot signals by GTK.
* Emitted as the third step of toolkit and application processing
* of the frame.
*
* The frame is repainted. GDK normally handles this internally and
* emits [signal@Gdk.Surface::render] signals which are turned into
* [signal@Gtk.Widget::snapshot] signals by GTK.
*/
signals[PAINT] =
g_signal_new (g_intern_static_string ("paint"),
@ -223,8 +218,9 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass)
* GdkFrameClock::after-paint:
* @clock: the frame clock emitting the signal
*
* This signal ends processing of the frame. Applications
* should generally not handle this signal.
* This signal ends processing of the frame.
*
* Applications should generally not handle this signal.
*/
signals[AFTER_PAINT] =
g_signal_new (g_intern_static_string ("after-paint"),
@ -238,8 +234,9 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass)
* GdkFrameClock::resume-events:
* @clock: the frame clock emitting the signal
*
* This signal is emitted after processing of the frame is
* finished, and is handled internally by GTK to resume normal
* Emitted after processing of the frame is finished.
*
* This signal is handled internally by GTK to resume normal
* event processing. Applications should not handle this signal.
*/
signals[RESUME_EVENTS] =
@ -267,10 +264,11 @@ gdk_frame_clock_init (GdkFrameClock *clock)
/**
* gdk_frame_clock_get_frame_time:
* @frame_clock: a #GdkFrameClock
* @frame_clock: a `GdkFrameClock`
*
* Gets the time that should currently be used for animations. Inside
* the processing of a frame, it’s the time used to compute the
* Gets the time that should currently be used for animations.
*
* Inside the processing of a frame, it’s the time used to compute the
* animation position of everything in a frame. Outside of a frame, it's
* the time of the conceptual “previous frame,” which may be either
* the actual previous frame time, or if that’s too old, an updated
@ -289,18 +287,19 @@ gdk_frame_clock_get_frame_time (GdkFrameClock *frame_clock)
/**
* gdk_frame_clock_request_phase:
* @frame_clock: a #GdkFrameClock
* @frame_clock: a `GdkFrameClock`
* @phase: the phase that is requested
*
* Asks the frame clock to run a particular phase. The signal
* corresponding the requested phase will be emitted the next
* Asks the frame clock to run a particular phase.
*
* The signal corresponding the requested phase will be emitted the next
* time the frame clock processes. Multiple calls to
* gdk_frame_clock_request_phase() will be combined together
* and only one frame processed. If you are displaying animated
* content and want to continually request the
* %GDK_FRAME_CLOCK_PHASE_UPDATE phase for a period of time,
* you should use gdk_frame_clock_begin_updating() instead, since
* this allows GTK to adjust system parameters to get maximally
* you should use [method@Gdk.FrameClock.begin_updating] instead,
* since this allows GTK to adjust system parameters to get maximally
* smooth animations.
*/
void
@ -314,14 +313,15 @@ gdk_frame_clock_request_phase (GdkFrameClock *frame_clock,
/**
* gdk_frame_clock_begin_updating:
* @frame_clock: a #GdkFrameClock
* @frame_clock: a `GdkFrameClock`
*
* Starts updates for an animation. Until a matching call to
* gdk_frame_clock_end_updating() is made, the frame clock will continually
* request a new frame with the %GDK_FRAME_CLOCK_PHASE_UPDATE phase.
* This function may be called multiple times and frames will be
* requested until gdk_frame_clock_end_updating() is called the same
* number of times.
* Starts updates for an animation.
*
* Until a matching call to [method@Gdk.FrameClock.end_updating] is made,
* the frame clock will continually request a new frame with the
* %GDK_FRAME_CLOCK_PHASE_UPDATE phase. This function may be called multiple
* times and frames will be requested until gdk_frame_clock_end_updating()
* is called the same number of times.
*/
void
gdk_frame_clock_begin_updating (GdkFrameClock *frame_clock)
@ -333,10 +333,11 @@ gdk_frame_clock_begin_updating (GdkFrameClock *frame_clock)
/**
* gdk_frame_clock_end_updating:
* @frame_clock: a #GdkFrameClock
* @frame_clock: a `GdkFrameClock`
*
* Stops updates for an animation. See the documentation for
* gdk_frame_clock_begin_updating().
* Stops updates for an animation.
*
* See the documentation for [method@Gdk.FrameClock.begin_updating].
*/
void
gdk_frame_clock_end_updating (GdkFrameClock *frame_clock)
@ -354,7 +355,6 @@ _gdk_frame_clock_freeze (GdkFrameClock *clock)
GDK_FRAME_CLOCK_GET_CLASS (clock)->freeze (clock);
}
static void
_gdk_frame_clock_thaw (GdkFrameClock *clock)
{
@ -377,7 +377,6 @@ _gdk_frame_clock_inhibit_freeze (GdkFrameClock *clock)
_gdk_frame_clock_thaw (clock);
}
void
_gdk_frame_clock_uninhibit_freeze (GdkFrameClock *clock)
{
@ -394,13 +393,13 @@ _gdk_frame_clock_uninhibit_freeze (GdkFrameClock *clock)
/**
* gdk_frame_clock_get_frame_counter:
* @frame_clock: a #GdkFrameClock
* @frame_clock: a `GdkFrameClock`
*
* A #GdkFrameClock maintains a 64-bit counter that increments for
* `GdkFrameClock` maintains a 64-bit counter that increments for
* each frame drawn.
*
* Returns: inside frame processing, the value of the frame counter
* for the current frame. Outside of frame processing, the frame
* for the current frame. Outside of frame processing, the frame
* counter for the last frame.
*/
gint64
@ -417,18 +416,20 @@ gdk_frame_clock_get_frame_counter (GdkFrameClock *frame_clock)
/**
* gdk_frame_clock_get_history_start:
* @frame_clock: a #GdkFrameClock
* @frame_clock: a `GdkFrameClock`
*
* #GdkFrameClock internally keeps a history of #GdkFrameTimings
* Returns the frame counter for the oldest frame available in history.
*
* `GdkFrameClock` internally keeps a history of `GdkFrameTimings`
* objects for recent frames that can be retrieved with
* gdk_frame_clock_get_timings(). The set of stored frames
* [method@Gdk.FrameClock.get_timings]. The set of stored frames
* is the set from the counter values given by
* gdk_frame_clock_get_history_start() and
* gdk_frame_clock_get_frame_counter(), inclusive.
* [method@Gdk.FrameClock.get_history_start] and
* [method@Gdk.FrameClock.get_frame_counter], inclusive.
*
* Returns: the frame counter value for the oldest frame
* that is available in the internal frame history of the
* #GdkFrameClock.
* `GdkFrameClock`
*/
gint64
gdk_frame_clock_get_history_start (GdkFrameClock *frame_clock)
@ -472,17 +473,19 @@ _gdk_frame_clock_begin_frame (GdkFrameClock *frame_clock)
/**
* gdk_frame_clock_get_timings:
* @frame_clock: a #GdkFrameClock
* @frame_clock: a `GdkFrameClock`
* @frame_counter: the frame counter value identifying the frame to
* be received.
* be received
*
* Retrieves a #GdkFrameTimings object holding timing information
* for the current frame or a recent frame. The #GdkFrameTimings
* object may not yet be complete: see gdk_frame_timings_get_complete().
* Retrieves a `GdkFrameTimings` object holding timing information
* for the current frame or a recent frame.
*
* Returns: (nullable) (transfer none): the #GdkFrameTimings object for
* the specified frame, or %NULL if it is not available. See
* gdk_frame_clock_get_history_start().
* The `GdkFrameTimings` object may not yet be complete: see
* [method@Gdk.FrameTimings.get_complete].
*
* Returns: (nullable) (transfer none): the `GdkFrameTimings` object
* for the specified frame, or %NULL if it is not available. See
* [method@Gdk.FrameClock.get_history_start].
*/
GdkFrameTimings *
gdk_frame_clock_get_timings (GdkFrameClock *frame_clock,
@ -508,14 +511,14 @@ gdk_frame_clock_get_timings (GdkFrameClock *frame_clock,
/**
* gdk_frame_clock_get_current_timings:
* @frame_clock: a #GdkFrameClock
* @frame_clock: a `GdkFrameClock`
*
* Gets the frame timings for the current frame.
*
* Returns: (nullable) (transfer none): the #GdkFrameTimings for the
* frame currently being processed, or even no frame is being
* processed, for the previous frame. Before any frames have been
* processed, returns %NULL.
* Returns: (nullable) (transfer none): the `GdkFrameTimings` for the
* frame currently being processed, or even no frame is being
* processed, for the previous frame. Before any frames have been
* processed, returns %NULL.
*/
GdkFrameTimings *
gdk_frame_clock_get_current_timings (GdkFrameClock *frame_clock)
@ -584,14 +587,16 @@ _gdk_frame_clock_debug_print_timings (GdkFrameClock *clock,
/**
* gdk_frame_clock_get_refresh_info:
* @frame_clock: a #GdkFrameClock
* @frame_clock: a `GdkFrameClock`
* @base_time: base time for determining a presentaton time
* @refresh_interval_return: (out) (optional): a location to store the
* determined refresh interval, or %NULL. A default refresh interval of
* 1/60th of a second will be stored if no history is present.
* determined refresh interval, or %NULL. A default refresh interval of
* 1/60th of a second will be stored if no history is present.
* @presentation_time_return: (out): a location to store the next
* candidate presentation time after the given base time.
* 0 will be will be stored if no history is present.
* candidate presentation time after the given base time.
* 0 will be will be stored if no history is present.
*
* Predicts a presentation time, based on history.
*
* Using the frame history stored in the frame clock, finds the last
* known presentation time and refresh interval, and assuming that
@ -754,12 +759,12 @@ guess_refresh_interval (GdkFrameClock *frame_clock)
/**
* gdk_frame_clock_get_fps:
* @frame_clock: a #GdkFrameClock
* @frame_clock: a `GdkFrameClock`
*
* Calculates the current frames-per-second, based on the
* frame timings of @frame_clock.
*
* Returns: the current fps, as a double
* Returns: the current fps, as a `double`
*/
double
gdk_frame_clock_get_fps (GdkFrameClock *frame_clock)

8
gdk/gdkframeclock.h
View File

@ -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,

113
gdk/gdkframetimings.c
View File

@ -21,24 +21,17 @@
#include "gdkframeclockprivate.h"
/**
* SECTION:gdkframetimings
* @Short_description: Object holding timing information for a single frame
* @Title: Frame timings
*
* A #GdkFrameTimings object holds timing information for a single frame
* of the application’s displays. To retrieve #GdkFrameTimings objects,
* use gdk_frame_clock_get_timings() or gdk_frame_clock_get_current_timings().
* The information in #GdkFrameTimings is useful for precise synchronization
* of video with the event or audio streams, and for measuring
* quality metrics for the application’s display, such as latency and jitter.
*/
/**
* GdkFrameTimings:
*
* The GdkFrameTimings struct contains only private fields and
* should not be accessed directly.
* A `GdkFrameTimings` object holds timing information for a single frame
* of the application’s displays.
*
* To retrieve `GdkFrameTimings` objects, use [method@Gdk.FrameClock.get_timings]
* or [method@Gdk.FrameClock.get_current_timings]. The information in
* `GdkFrameTimings` is useful for precise synchronization of video with
* the event or audio streams, and for measuring quality metrics for the
* application’s display, such as latency and jitter.
*/
G_DEFINE_BOXED_TYPE (GdkFrameTimings, gdk_frame_timings,
@ -74,7 +67,7 @@ _gdk_frame_timings_steal (GdkFrameTimings *timings,
/**
* gdk_frame_timings_ref:
* @timings: a #GdkFrameTimings
* @timings: a `GdkFrameTimings`
*
* Increases the reference count of @timings.
*
@ -92,10 +85,11 @@ gdk_frame_timings_ref (GdkFrameTimings *timings)
/**
* gdk_frame_timings_unref:
* @timings: a #GdkFrameTimings
* @timings: a `GdkFrameTimings`
*
* Decreases the reference count of @timings. If @timings
* is no longer referenced, it will be freed.
* Decreases the reference count of @timings.
*
* If @timings is no longer referenced, it will be freed.
*/
void
gdk_frame_timings_unref (GdkFrameTimings *timings)
@ -112,9 +106,9 @@ gdk_frame_timings_unref (GdkFrameTimings *timings)
/**
* gdk_frame_timings_get_frame_counter:
* @timings: a #GdkFrameTimings
* @timings: a `GdkFrameTimings`
*
* Gets the frame counter value of the #GdkFrameClock when this
* Gets the frame counter value of the `GdkFrameClock` when
* this frame was drawn.
*
* Returns: the frame counter value for this frame
@ -127,20 +121,24 @@ gdk_frame_timings_get_frame_counter (GdkFrameTimings *timings)
/**
* gdk_frame_timings_get_complete:
* @timings: a #GdkFrameTimings
* @timings: a `GdkFrameTimings`
*
* The timing information in a #GdkFrameTimings is filled in
* Returns whether @timings are complete.
*
* The timing information in a `GdkFrameTimings` is filled in
* incrementally as the frame as drawn and passed off to the
* window system for processing and display to the user. The
* accessor functions for #GdkFrameTimings can return 0 to
* accessor functions for `GdkFrameTimings` can return 0 to
* indicate an unavailable value for two reasons: either because
* the information is not yet available, or because it isn't
* available at all. Once gdk_frame_timings_get_complete() returns
* %TRUE for a frame, you can be certain that no further values
* will become available and be stored in the #GdkFrameTimings.
* available at all.
*
* Once this function returns %TRUE for a frame, you can be
* certain that no further values will become available and be
* stored in the `GdkFrameTimings`.
*
* Returns: %TRUE if all information that will be available
* for the frame has been filled in.
* for the frame has been filled in.
*/
gboolean
gdk_frame_timings_get_complete (GdkFrameTimings *timings)
@ -152,11 +150,12 @@ gdk_frame_timings_get_complete (GdkFrameTimings *timings)
/**
* gdk_frame_timings_get_frame_time:
* @timings: A #GdkFrameTimings
* @timings: A `GdkFrameTimings`
*
* Returns the frame time for the frame. This is the time value
* that is typically used to time animations for the frame. See
* gdk_frame_clock_get_frame_time().
* Returns the frame time for the frame.
*
* This is the time value that is typically used to time
* animations for the frame. See [method@Gdk.FrameClock.get_frame_time].
*
* Returns: the frame time for the frame, in the timescale
* of g_get_monotonic_time()
@ -171,14 +170,15 @@ gdk_frame_timings_get_frame_time (GdkFrameTimings *timings)
/**
* gdk_frame_timings_get_presentation_time:
* @timings: a #GdkFrameTimings
* @timings: a `GdkFrameTimings`
*
* Reurns the presentation time. This is the time at which the frame
* became visible to the user.
* Reurns the presentation time.
*
* This is the time at which the frame became visible to the user.
*
* Returns: the time the frame was displayed to the user, in the
* timescale of g_get_monotonic_time(), or 0 if no presentation
* time is available. See gdk_frame_timings_get_complete()
* timescale of g_get_monotonic_time(), or 0 if no presentation
* time is available. See [method@Gdk.FrameTimings.get_complete]
*/
gint64
gdk_frame_timings_get_presentation_time (GdkFrameTimings *timings)
@ -190,21 +190,24 @@ gdk_frame_timings_get_presentation_time (GdkFrameTimings *timings)
/**
* gdk_frame_timings_get_predicted_presentation_time:
* @timings: a #GdkFrameTimings
* @timings: a `GdkFrameTimings`
*
* Gets the predicted time at which this frame will be displayed. Although
* no predicted time may be available, if one is available, it will
* be available while the frame is being generated, in contrast to
* gdk_frame_timings_get_presentation_time(), which is only available
* after the frame has been presented. In general, if you are simply
* animating, you should use gdk_frame_clock_get_frame_time() rather
* than this function, but this function is useful for applications
* that want exact control over latency. For example, a movie player
* may want this information for Audio/Video synchronization.
* Gets the predicted time at which this frame will be displayed.
*
* Although no predicted time may be available, if one is available,
* it will be available while the frame is being generated, in contrast
* to [method@Gdk.FrameTimings.get_presentation_time], which is only
* available after the frame has been presented.
*
* In general, if you are simply animating, you should use
* [method@Gdk.FrameClock.get_frame_time] rather than this function,
* but this function is useful for applications that want exact control
* over latency. For example, a movie player may want this information
* for Audio/Video synchronization.
*
* Returns: The predicted time at which the frame will be presented,
* in the timescale of g_get_monotonic_time(), or 0 if no predicted
* presentation time is available.
* in the timescale of g_get_monotonic_time(), or 0 if no predicted
* presentation time is available.
*/
gint64
gdk_frame_timings_get_predicted_presentation_time (GdkFrameTimings *timings)
@ -216,15 +219,17 @@ gdk_frame_timings_get_predicted_presentation_time (GdkFrameTimings *timings)
/**
* gdk_frame_timings_get_refresh_interval:
* @timings: a #GdkFrameTimings
* @timings: a `GdkFrameTimings`
*
* Gets the natural interval between presentation times for
* the display that this frame was displayed on. Frame presentation
* usually happens during the “vertical blanking interval”.
* the display that this frame was displayed on.
*
* Frame presentation usually happens during the “vertical
* blanking interval”.
*
* Returns: the refresh interval of the display, in microseconds,
* or 0 if the refresh interval is not available.
* See gdk_frame_timings_get_complete().
* or 0 if the refresh interval is not available.
* See [method@Gdk.FrameTimings.get_complete].
*/
gint64
gdk_frame_timings_get_refresh_interval (GdkFrameTimings *timings)

182
gdk/gdkglcontext.c
View File

@ -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 the value set using gdk_gl_context_set_debug_enabled().
* Retrieves whether the context is doing extra validations and runtime checking.
*
* See [method@Gdk.GLContext.set_debug_enabled].
*
* Returns: %TRUE if debugging is enabled
*/
@ -610,17 +602,17 @@ gdk_gl_context_get_debug_enabled (GdkGLContext *context)
/**
* gdk_gl_context_set_forward_compatible:
* @context: a #GdkGLContext
* @compatible: whether the context should be forward compatible
* @context: a `GdkGLContext`
* @compatible: whether the context should be forward-compatible
*
* Sets whether the #GdkGLContext should be forward compatible.
* Sets whether the `GdkGLContext` should be forward-compatible.
*
* Forward compatible contexts must not support OpenGL functionality that
* Forward-compatible contexts must not support OpenGL functionality that
* has been marked as deprecated in the requested version; non-forward
* compatible contexts, on the other hand, must support both deprecated and
* non deprecated functionality.
*
* The #GdkGLContext must not be realized or made current prior to calling
* The `GdkGLContext` must not be realized or made current prior to calling
* this function.
*/
void
@ -639,11 +631,13 @@ gdk_gl_context_set_forward_compatible (GdkGLContext *context,
/**
* gdk_gl_context_get_forward_compatible:
* @context: a #GdkGLContext
* @context: a `GdkGLContext`
*
* Retrieves the value set using gdk_gl_context_set_forward_compatible().
* Retrieves whether the context is forward-compatible.
*
* Returns: %TRUE if the context should be forward compatible
* See [method@Gdk.GLContext.set_forward_compatible].
*
* Returns: %TRUE if the context should be forward-compatible
*/
gboolean
gdk_gl_context_get_forward_compatible (GdkGLContext *context)
@ -657,7 +651,7 @@ gdk_gl_context_get_forward_compatible (GdkGLContext *context)
/**
* gdk_gl_context_set_required_version:
* @context: a #GdkGLContext
* @context: a `GdkGLContext`
* @major: the major version to request
* @minor: the minor version to request
*
@ -665,7 +659,7 @@ gdk_gl_context_get_forward_compatible (GdkGLContext *context)
*
* Setting @major and @minor to zero will use the default values.
*
* The #GdkGLContext must not be realized or made current prior to calling
* The `GdkGLContext` must not be realized or made current prior to calling
* this function.
*/
void
@ -716,12 +710,13 @@ gdk_gl_context_set_required_version (GdkGLContext *context,
/**
* gdk_gl_context_get_required_version:
* @context: a #GdkGLContext
* @context: a `GdkGLContext`
* @major: (out) (nullable): return location for the major version to request
* @minor: (out) (nullable): return location for the minor version to request
*
* Retrieves the major and minor version requested by calling
* gdk_gl_context_set_required_version().
* Retrieves required OpenGL version.
*
* See [method@Gdk.GLContext.set_required_version].
*/
void
gdk_gl_context_get_required_version (GdkGLContext *context,
@ -776,11 +771,11 @@ gdk_gl_context_get_required_version (GdkGLContext *context,
/**
* gdk_gl_context_is_legacy:
* @context: a #GdkGLContext
* @context: a `GdkGLContext`
*
* Whether the #GdkGLContext is in legacy mode or not.
* Whether the `GdkGLContext` is in legacy mode or not.
*
* The #GdkGLContext must be realized before calling this function.
* The `GdkGLContext` must be realized before calling this function.
*
* When realizing a GL context, GDK will try to use the OpenGL 3.2 core
* profile; this profile removes all the OpenGL API that was deprecated
@ -819,12 +814,13 @@ gdk_gl_context_set_is_legacy (GdkGLContext *context,
/**
* gdk_gl_context_set_use_es:
* @context: a #GdkGLContext:
* @context: a `GdkGLContext`
* @use_es: whether the context should use OpenGL ES instead of OpenGL,
* or -1 to allow auto-detection
*
* Requests that GDK create an OpenGL ES context instead of an OpenGL one,
* if the platform and windowing system allows it.
* Requests that GDK create an OpenGL ES context instead of an OpenGL one.
*
* Not all platforms support OpenGL ES.
*
* The @context must not have been realized.
*
@ -832,9 +828,9 @@ gdk_gl_context_set_is_legacy (GdkGLContext *context,
* underlying GL implementation is OpenGL or OpenGL ES once the @context
* is realized.
*
* You should check the return value of gdk_gl_context_get_use_es() after
* calling gdk_gl_context_realize() to decide whether to use the OpenGL or
* OpenGL ES API, extensions, or shaders.
* You should check the return value of [method@Gdk.GLContext.get_use_es]
* after calling [method@Gdk.GLContext.realize] to decide whether to use
* the OpenGL or OpenGL ES API, extensions, or shaders.
*/
void
gdk_gl_context_set_use_es (GdkGLContext *context,
@ -851,11 +847,11 @@ gdk_gl_context_set_use_es (GdkGLContext *context,
/**
* gdk_gl_context_get_use_es:
* @context: a #GdkGLContext
* @context: a `GdkGLContext`
*
* Checks whether the @context is using an OpenGL or OpenGL ES profile.
*
* Returns: %TRUE if the #GdkGLContext is using an OpenGL ES profile
* Returns: %TRUE if the `GdkGLContext` is using an OpenGL ES profile
*/
gboolean
gdk_gl_context_get_use_es (GdkGLContext *context)
@ -963,12 +959,12 @@ gl_debug_message_callback (GLenum source,
/**
* gdk_gl_context_realize:
* @context: a #GdkGLContext
* @error: return location for a #GError
* @context: a `GdkGLContext`
* @error: return location for a `GError`
*
* Realizes the given #GdkGLContext.
* Realizes the given `GdkGLContext`.
*
* It is safe to call this function on a realized #GdkGLContext.
* It is safe to call this function on a realized `GdkGLContext`.
*
* Returns: %TRUE if the context is realized
*/
@ -1088,7 +1084,7 @@ gdk_gl_context_check_extensions (GdkGLContext *context)
/**
* gdk_gl_context_make_current:
* @context: a #GdkGLContext
* @context: a `GdkGLContext`
*
* Makes the @context the current one.
*/
@ -1127,11 +1123,11 @@ gdk_gl_context_make_current (GdkGLContext *context)
/**
* gdk_gl_context_get_display:
* @context: a #GdkGLContext
* @context: a `GdkGLContext`
*
* Retrieves the #GdkDisplay the @context is created for
* Retrieves the display the @context is created for
*
* Returns: (nullable) (transfer none): a #GdkDisplay or %NULL
* Returns: (nullable) (transfer none): a `GdkDisplay` or %NULL
*/
GdkDisplay *
gdk_gl_context_get_display (GdkGLContext *context)
@ -1143,11 +1139,11 @@ gdk_gl_context_get_display (GdkGLContext *context)
/**
* gdk_gl_context_get_surface:
* @context: a #GdkGLContext
* @context: a `GdkGLContext`
*
* Retrieves the #GdkSurface used by the @context.
* Retrieves the surface used by the @context.
*
* Returns: (nullable) (transfer none): a #GdkSurface or %NULL
* Returns: (nullable) (transfer none): a `GdkSurface` or %NULL
*/
GdkSurface *
gdk_gl_context_get_surface (GdkGLContext *context)
@ -1159,11 +1155,11 @@ gdk_gl_context_get_surface (GdkGLContext *context)
/**
* gdk_gl_context_get_shared_context:
* @context: a #GdkGLContext
* @context: a `GdkGLContext`
*
* Retrieves the #GdkGLContext that this @context share data with.
* Retrieves the `GdkGLContext` that this @context share data with.
*
* Returns: (nullable) (transfer none): a #GdkGLContext or %NULL
* Returns: (nullable) (transfer none): a `GdkGLContext` or %NULL
*/
GdkGLContext *
gdk_gl_context_get_shared_context (GdkGLContext *context)
@ -1177,7 +1173,7 @@ gdk_gl_context_get_shared_context (GdkGLContext *context)
/**
* gdk_gl_context_get_version:
* @context: a #GdkGLContext
* @context: a `GdkGLContext`
* @major: (out): return location for the major version
* @minor: (out): return location for the minor version
*
@ -1204,10 +1200,10 @@ gdk_gl_context_get_version (GdkGLContext *context,
/**
* gdk_gl_context_clear_current:
*
* Clears the current #GdkGLContext.
* Clears the current `GdkGLContext`.
*
* Any OpenGL call after this function returns will be ignored
* until gdk_gl_context_make_current() is called.
* until [method@Gdk.GLContext.make_current] is called.
*/
void
gdk_gl_context_clear_current (void)
@ -1225,9 +1221,9 @@ gdk_gl_context_clear_current (void)
/**
* gdk_gl_context_get_current:
*
* Retrieves the current #GdkGLContext.
* Retrieves the current `GdkGLContext`.
*
* Returns: (nullable) (transfer none): the current #GdkGLContext, or %NULL
* Returns: (nullable) (transfer none): the current `GdkGLContext`, or %NULL
*/
GdkGLContext *
gdk_gl_context_get_current (void)

23
gdk/gdkgltexture.c
View File

@ -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,

5
gdk/gdkgltexture.h
View File

@ -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;

13
gdk/gdkmemorytexture.c
View File

@ -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,

24
gdk/gdkmemorytexture.h
View File

@ -45,14 +45,14 @@ G_BEGIN_DECLS
* @GDK_MEMORY_N_FORMATS: The number of formats. This value will change as
* more formats get added, so do not rely on its concrete integer.
*
* #GdkMemoryFormat describes a format that bytes can have in memory.
* `GdkMemoryFormat` describes a format that bytes can have in memory.
*
* It describes formats by listing the contents of the memory passed to it.
* So GDK_MEMORY_A8R8G8B8 will be 1 byte (8 bits) of alpha, followed by a
* byte each of red, green and blue. It is not endian-dependent, so
* CAIRO_FORMAT_ARGB32 is represented by different #GdkMemoryFormats on
* architectures with different endiannesses.
*
* CAIRO_FORMAT_ARGB32 is represented by different `GdkMemoryFormats`
* on architectures with different endiannesses.
*
* Its naming is modelled after VkFormat (see
* https://www.khronos.org/registry/vulkan/specs/1.0/html/vkspec.html#VkFormat
* for details).
@ -74,12 +74,13 @@ typedef enum {
/**
* GDK_MEMORY_DEFAULT:
*
* This is the default memory format used by GTK and is the format
* provided by gdk_texture_download(). It is equal to
* %CAIRO_FORMAT_ARGB32.
* The default memory format used by GTK.
*
* Be aware that unlike the #GdkMemoryFormat values, this format is
* different for different endianness.
* This is the format provided by [method@Gdk.Texture.download].
* It is equal to %CAIRO_FORMAT_ARGB32.
*
* Be aware that unlike the #GdkMemoryFormat values, this format
* is different for different endianness.
*/
#if G_BYTE_ORDER == G_LITTLE_ENDIAN
#define GDK_MEMORY_DEFAULT GDK_MEMORY_B8G8R8A8_PREMULTIPLIED
@ -94,11 +95,6 @@ typedef enum {
#define GDK_MEMORY_TEXTURE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GDK_TYPE_MEMORY_TEXTURE, GdkMemoryTexture))
#define GDK_IS_MEMORY_TEXTURE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GDK_TYPE_MEMORY_TEXTURE))
/**
* GdkMemoryTexture:
*
* A #GdkTexture representing image data in memory.
*/
typedef struct _GdkMemoryTexture GdkMemoryTexture;
typedef struct _GdkMemoryTextureClass GdkMemoryTextureClass;

144
gdk/gdkmonitor.c
View File

@ -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
*/

196
gdk/gdkpaintable.c
View File

@ -30,52 +30,53 @@ void gtk_snapshot_push_debug (GdkSnapshot
void gtk_snapshot_pop (GdkSnapshot *snapshot);
/**
* SECTION:gdkpaintable
* @Title: GdkPaintable
* @Short_description: An interface for a paintable region
* @See_also: #ClutterContent, #GtkImage, #GdkTexture, #GtkSnapshot
* GdkPaintable:
*
* #GdkPaintable is a simple interface used by GDK and GTK to represent
* objects that can be painted anywhere at any size without requiring any
* sort of layout. The interface is inspired by similar concepts elsewhere,
* such as [ClutterContent](https://developer.gnome.org/clutter/stable/ClutterContent.html),
* `GdkPaintable` is a simple interface used by GTK to represent content that
* can be painted.
*
* The content of a `GdkPaintable` can be painted anywhere at any size
* without requiring any sort of layout. The interface is inspired by
* similar concepts elsewhere, such as
* [ClutterContent](https://developer.gnome.org/clutter/stable/ClutterContent.html),
* [HTML/CSS Paint Sources](https://www.w3.org/TR/css-images-4/#paint-source),
* or [SVG Paint Servers](https://www.w3.org/TR/SVG2/pservers.html).
*
* A #GdkPaintable can be snapshot at any time and size using
* gdk_paintable_snapshot(). How the paintable interprets that size and if it
* scales or centers itself into the given rectangle is implementation defined,
* though if you are implementing a #GdkPaintable and don't know what to do, it
* is suggested that you scale your paintable ignoring any potential aspect ratio.
* A `GdkPaintable` can be snapshot at any time and size using
* [method@Gdk.Paintable.snapshot]. How the paintable interprets that size and
* if it scales or centers itself into the given rectangle is implementation
* defined, though if you are implementing a `GdkPaintable` and don't know what
* to do, it is suggested that you scale your paintable ignoring any potential
* aspect ratio.
*
* The contents that a #GdkPaintable produces may depend on the #GdkSnapshot passed
* to it. For example, paintables may decide to use more detailed images on higher
* resolution screens or when OpenGL is available. A #GdkPaintable will however
* always produce the same output for the same snapshot.
* The contents that a `GdkPaintable` produces may depend on the [class@GdkSnapshot]
* passed to it. For example, paintables may decide to use more detailed images
* on higher resolution screens or when OpenGL is available. A `GdkPaintable`
* will however always produce the same output for the same snapshot.
*
* A #GdkPaintable may change its contents, meaning that it will now produce a
* different output with the same snapshot. Once that happens, it will call
* gdk_paintable_invalidate_contents() which will emit the
* #GdkPaintable::invalidate-contents signal. If a paintable is known to never
* change its contents, it will set the %GDK_PAINTABLE_STATIC_CONTENTS flag.
* If a consumer cannot deal with changing contents, it may call
* gdk_paintable_get_current_image() which will return a static paintable and
* use that.
* A `GdkPaintable` may change its contents, meaning that it will now produce
* a different output with the same snapshot. Once that happens, it will call
* [method@Gdk.Paintable.invalidate_contents] which will emit the
* [signal@GdkPaintable::invalidate-contents] signal. If a paintable is known
* to never change its contents, it will set the %GDK_PAINTABLE_STATIC_CONTENTS
* flag. If a consumer cannot deal with changing contents, it may call
* [method@Gdk.Paintable.get_current_image] which will return a static
* paintable and use that.
*
* A paintable can report an intrinsic (or preferred) size or aspect ratio it
* wishes to be rendered at, though it doesn't have to. Consumers of the interface
* can use this information to layout thepaintable appropriately.
* Just like the contents, the size of a paintable can change. A paintable will
* indicate this by calling gdk_paintable_invalidate_size() which will emit the
* #GdkPaintable::invalidate-size signal.
* And just like for contents, if a paintable is known to never change its size,
* it will set the %GDK_PAINTABLE_STATIC_SIZE flag.
* can use this information to layout thepaintable appropriately. Just like the
* contents, the size of a paintable can change. A paintable will indicate this
* by calling [method@Gdk.Paintable.invalidate_size] which will emit the
* [signal@GdkPaintable::invalidate-size] signal. And just like for contents,
* if a paintable is known to never change its size, it will set the
* %GDK_PAINTABLE_STATIC_SIZE flag.
*
* Besides API for applications, there are some functions that are only
* useful for implementing subclasses and should not be used by applications:
* gdk_paintable_invalidate_contents(),
* gdk_paintable_invalidate_size(),
* gdk_paintable_new_empty().
* [method@Gdk.Paintable.invalidate_contents],
* [method@Gdk.Paintable.invalidate_size],
* [func@Gdk.Paintable.new_empty].
*/
G_DEFINE_INTERFACE (GdkPaintable, gdk_paintable, G_TYPE_OBJECT)
@ -161,7 +162,7 @@ gdk_paintable_default_init (GdkPaintableInterface *iface)
/**
* GdkPaintable::invalidate-contents
* @paintable: a #GdkPaintable
* @paintable: a `GdkPaintable`
*
* Emitted when the contents of the @paintable change.
*
@ -179,15 +180,18 @@ gdk_paintable_default_init (GdkPaintableInterface *iface)
/**
* GdkPaintable::invalidate-size
* @paintable: a #GdkPaintable
* @paintable: a `GdkPaintable`
*
* Emitted when the intrinsic size of the @paintable changes. This means the values
* reported by at least one of gdk_paintable_get_intrinsic_width(),
* gdk_paintable_get_intrinsic_height() or gdk_paintable_get_intrinsic_aspect_ratio()
* Emitted when the intrinsic size of the @paintable changes.
*
* This means the values reported by at least one of
* [method@Gdk.Paintable.get_intrinsic_width],
* [method@Gdk.Paintable.get_intrinsic_height] or
* [method@Gdk.Paintable.get_intrinsic_aspect_ratio]
* has changed.
*
* Examples for such an event would be a paintable displaying the contents of a toplevel
* surface being resized.
* Examples for such an event would be a paintable displaying
* the contents of a toplevel surface being resized.
*/
signals[INVALIDATE_SIZE] =
g_signal_new ("invalidate-size",
@ -201,14 +205,16 @@ gdk_paintable_default_init (GdkPaintableInterface *iface)
/**
* gdk_paintable_snapshot:
* @paintable: a #GdkPaintable
* @snapshot: a #GdkSnapshot to snapshot to
* @paintable: a `GdkPaintable`
* @snapshot: a `GdkSnapshot` to snapshot to
* @width: width to snapshot in
* @height: height to snapshot in
*
* Snapshots the given paintable with the given @width and @height at the
* current (0,0) offset of the @snapshot. If @width and @height are not larger
* than zero, this function will do nothing.
* Snapshots the given paintable with the given @width and @height.
*
* The paintable is drawn at the current (0,0) offset of the @snapshot.
* If @width and @height are not larger than zero, this function will
* do nothing.
*/
void
gdk_paintable_snapshot (GdkPaintable *paintable,
@ -241,12 +247,12 @@ gdk_paintable_is_immutable (GdkPaintable *paintable)
/**
* gdk_paintable_get_current_image:
* @paintable: a #GdkPaintable
* @paintable: a `GdkPaintable`
*
* Gets an immutable paintable for the current contents displayed by @paintable.
*
* This is useful when you want to retain the current state of an animation, for
* example to take a screenshot of a running animation.
* This is useful when you want to retain the current state of an animation,
* for example to take a screenshot of a running animation.
*
* If the @paintable is already immutable, it will return itself.
*
@ -269,13 +275,15 @@ gdk_paintable_get_current_image (GdkPaintable *paintable)
/**
* gdk_paintable_get_flags:
* @paintable: a #GdkPaintable
* @paintable: a `GdkPaintable`
*
* Get flags for the paintable. This is oftentimes useful for optimizations.
* Get flags for the paintable.
*
* See #GdkPaintableFlags for the flags and what they mean.
* This is oftentimes useful for optimizations.
*
* Returns: The #GdkPaintableFlags for this paintable.
* See [flags@Gdk.PaintableFlags] for the flags and what they mean.
*
* Returns: The `GdkPaintableFlags` for this paintable
*/
GdkPaintableFlags
gdk_paintable_get_flags (GdkPaintable *paintable)
@ -290,17 +298,18 @@ gdk_paintable_get_flags (GdkPaintable *paintable)
/**
* gdk_paintable_get_intrinsic_width:
* @paintable: a #GdkPaintable
* @paintable: a `GdkPaintable`
*
* Gets the preferred width the @paintable would like to be displayed at.
*
* Consumers of this interface can use this to reserve enough space to draw
* the paintable.
*
* This is a purely informational value and does not in any way limit the values
* that may be passed to gdk_paintable_snapshot().
* This is a purely informational value and does not in any way limit the
* values that may be passed to [method@Gdk.Paintable.snapshot].
*
* If the @paintable does not have a preferred width, it returns 0. Negative
* values are never returned.
* If the @paintable does not have a preferred width, it returns 0.
* Negative values are never returned.
*
* Returns: the intrinsic width of @paintable or 0 if none.
*/
@ -317,17 +326,18 @@ gdk_paintable_get_intrinsic_width (GdkPaintable *paintable)
/**
* gdk_paintable_get_intrinsic_height:
* @paintable: a #GdkPaintable
* @paintable: a `GdkPaintable`
*
* Gets the preferred height the @paintable would like to be displayed at.
*
* Consumers of this interface can use this to reserve enough space to draw
* the paintable.
*
* This is a purely informational value and does not in any way limit the values
* that may be passed to gdk_paintable_snapshot().
* This is a purely informational value and does not in any way limit the
* values that may be passed to [method@Gdk.Paintable.snapshot].
*
* If the @paintable does not have a preferred height, it returns 0. Negative
* values are never returned.
* If the @paintable does not have a preferred height, it returns 0.
* Negative values are never returned.
*
* Returns: the intrinsic height of @paintable or 0 if none.
*/
@ -344,23 +354,25 @@ gdk_paintable_get_intrinsic_height (GdkPaintable *paintable)
/**
* gdk_paintable_get_intrinsic_aspect_ratio:
* @paintable: a #GdkPaintable
* @paintable: a `GdkPaintable`
*
* Gets the preferred aspect ratio the @paintable would like to be displayed at.
* The aspect ratio is the width divided by the height, so a value of 0.5 means
* that the @paintable prefers to be displayed twice as high as it is wide.
* Consumers of this interface can use this to preserve aspect ratio when displaying
* the paintable.
*
* This is a purely informational value and does not in any way limit the values
* that may be passed to gdk_paintable_snapshot().
* The aspect ratio is the width divided by the height, so a value of 0.5
* means that the @paintable prefers to be displayed twice as high as it
* is wide. Consumers of this interface can use this to preserve aspect
* ratio when displaying the paintable.
*
* This is a purely informational value and does not in any way limit the
* values that may be passed to [method@Gdk.Paintable.snapshot].
*
* Usually when a @paintable returns nonzero values from
* gdk_paintable_get_intrinsic_width() and gdk_paintable_get_intrinsic_height()
* the aspect ratio should conform to those values, though that is not required.
* [method@Gdk.Paintable.get_intrinsic_width] and
* [method@Gdk.Paintable.get_intrinsic_height] the aspect ratio
* should conform to those values, though that is not required.
*
* If the @paintable does not have a preferred aspect ratio, it returns 0.
* Negative values are never returned.
* If the @paintable does not have a preferred aspect ratio,
* it returns 0. Negative values are never returned.
*
* Returns: the intrinsic aspect ratio of @paintable or 0 if none.
*/
@ -377,13 +389,15 @@ gdk_paintable_get_intrinsic_aspect_ratio (GdkPaintable *paintable)
/**
* gdk_paintable_invalidate_contents:
* @paintable: a #GdkPaintable
* @paintable: a `GdkPaintable`
*
* Called by implementations of `GdkPaintable` to invalidate their contents.
*
* Called by implementations of #GdkPaintable to invalidate their contents.
* Unless the contents are invalidated, implementations must guarantee that
* multiple calls of gdk_paintable_snapshot() produce the same output.
* multiple calls of [method@Gdk.Paintable.snapshot] produce the same output.
*
* This function will emit the #GdkPaintable::invalidate-contents signal.
* This function will emit the [signal@Gdk.Paintable::invalidate-contents]
* signal.
*
* If a @paintable reports the %GDK_PAINTABLE_STATIC_CONTENTS flag,
* it must not call this function.
@ -399,13 +413,15 @@ gdk_paintable_invalidate_contents (GdkPaintable *paintable)
/**
* gdk_paintable_invalidate_size:
* @paintable: a #GdkPaintable
* @paintable: a `GdkPaintable`
*
* Called by implementations of `GdkPaintable` to invalidate their size.
*
* Called by implementations of #GdkPaintable to invalidate their size.
* As long as the size is not invalidated, @paintable must return the same
* values for its intrinsic width, height and aspect ratio.
*
* This function will emit the #GdkPaintable::invalidate-size signal.
* This function will emit the [signal@Gdk.Paintable::invalidate-size]
* signal.
*
* If a @paintable reports the %GDK_PAINTABLE_STATIC_SIZE flag,
* it must not call this function.
@ -421,7 +437,7 @@ gdk_paintable_invalidate_size (GdkPaintable *paintable)
/**
* gdk_paintable_compute_concrete_size:
* @paintable: a #GdkPaintable
* @paintable: a `GdkPaintable`
* @specified_width: the width @paintable could be drawn into or
* 0.0 if unknown
* @specified_height: the height @paintable could be drawn into or
@ -435,8 +451,10 @@ gdk_paintable_invalidate_size (GdkPaintable *paintable)
* @concrete_height: (out): will be set to the concrete height
* computed.
*
* Applies the sizing algorithm outlined in
* https://drafts.csswg.org/css-images-3/#default-sizing
* Compute a concrete size for the `GdkPaintable`.
*
* Applies the sizing algorithm outlined in the
* [CSS Image spec](https://drafts.csswg.org/css-images-3/#default-sizing)
* to the given @paintable. See that link for more details.
*
* It is not necessary to call this function when both @specified_width
@ -643,11 +661,13 @@ gdk_empty_paintable_init (GdkEmptyPaintable *self)
* @intrinsic_height: The intrinsic height to report. Can be 0 for no height.
*
* Returns a paintable that has the given intrinsic size and draws nothing.
* This is often useful for implementing the #GdkPaintableInterface.get_current_image()
* virtual function when the paintable is in an incomplete state (like a
* #GtkMediaStream before receiving the first frame).
*
* Returns: (transfer full): a #GdkPaintable
* This is often useful for implementing the
* #GdkPaintableInterface.get_current_image() virtual function
* when the paintable is in an incomplete state (like a
* [class@Gtk.MediaStream] before receiving the first frame).
*
* Returns: (transfer full): a `GdkPaintable`
*/
GdkPaintable *
gdk_paintable_new_empty (int intrinsic_width,

29
gdk/gdkpaintable.h
View File

@ -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
{

63
gdk/gdkpopup.c
View File

@ -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;

5
gdk/gdkpopup.h
View File

@ -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)

96
gdk/gdkpopuplayout.c
View File

@ -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

50
gdk/gdkrectangle.c
View File

@ -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.
*

102
gdk/gdkrgba.c
View File

@ -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. That is, drawing with the value
* would not produce any change.
* Checks if an @rgba value is transparent.
*
* That is, drawing with the value would not produce any change.
*
* Returns: %TRUE if the @rgba is clear
*/
@ -103,10 +99,12 @@ gdk_rgba_is_clear (const GdkRGBA *rgba)
/**
* gdk_rgba_is_opaque:
* @rgba: a #GdkRGBA
* @rgba: a `GdkRGBA`
*
* Checks if an @rgba value is opaque. That is, drawing with the value
* will not retain any results from previous contents.
* Checks if an @rgba value is opaque.
*
* That is, drawing with the value will not retain any results
* from previous contents.
*
* Returns: %TRUE if the @rgba is opaque
*/
@ -160,26 +158,27 @@ parse_rgb_value (const char *str,
/**
* gdk_rgba_parse:
* @rgba: the #GdkRGBA to fill in
* @rgba: the `GdkRGBA` to fill in
* @spec: the string specifying the color
*
* Parses a textual representation of a color, filling in
* the @red, @green, @blue and @alpha fields of the @rgba #GdkRGBA.
* Parses a textual representation of a color.
*
* The string can be either one of:
*
* - A standard name (Taken from the X11 rgb.txt file).
* - A hexadecimal value in the form “\#rgb”, “\#rrggbb”,
* “\#rrrgggbbb” or ”\#rrrrggggbbbb”
* - A hexadecimal value in the form “\#rgba”, “\#rrggbbaa”,
* or ”\#rrrrggggbbbbaaaa”
* - A RGB color in the form “rgb(r,g,b)” (In this case the color will
* have full opacity)
* - A RGB color in the form “rgb(r,g,b)” (In this case the color
* will have full opacity)
* - A RGBA color in the form “rgba(r,g,b,a)”
*
* Where “r”, “g”, “b” and “a” are respectively the red, green, blue and
* alpha color values. In the last two cases, “r”, “g”, and “b” are either
* integers in the range 0 to 255 or percentage values in the range 0% to
* 100%, and a is a floating point value in the range 0 to 1.
* Where “r”, “g”, “b” and “a” are respectively the red, green,
* blue and alpha color values. In the last two cases, “r”, “g”,
* and “b” are either integers in the range 0 to 255 or percentage
* values in the range 0% to 100%, and a is a floating point value
* in the range 0 to 1.
*
* Returns: %TRUE if the parsing succeeded
*/
@ -306,10 +305,10 @@ gdk_rgba_parse (GdkRGBA *rgba,
/**
* gdk_rgba_hash:
* @p: (type GdkRGBA): a #GdkRGBA pointer
* @p: (type GdkRGBA): a `GdkRGBA`
*
* A hash function suitable for using for a hash
* table that stores #GdkRGBAs.
* table that stores `GdkRGBA`s.
*
* Returns: The hash value for @p
*/
@ -326,10 +325,10 @@ gdk_rgba_hash (gconstpointer p)
/**
* gdk_rgba_equal:
* @p1: (type GdkRGBA): a #GdkRGBA pointer
* @p2: (type GdkRGBA): another #GdkRGBA pointer
* @p1: (type GdkRGBA): a `GdkRGBA`
* @p2: (type GdkRGBA): another `GdkRGBA`
*
* Compares two RGBA colors.
* Compares two `GdkRGBA` colors.
*
* Returns: %TRUE if the two colors compare equal
*/
@ -353,23 +352,21 @@ gdk_rgba_equal (gconstpointer p1,
/**
* gdk_rgba_to_string:
* @rgba: a #GdkRGBA
* @rgba: a `GdkRGBA`
*
* Returns a textual specification of @rgba in the form
* `rgb(r,g,b)` or
* `rgba(r,g,b,a)`,
* where “r”, “g”, “b” and “a” represent the red, green,
* blue and alpha values respectively. “r”, “g”, and “b” are
* represented as integers in the range 0 to 255, and “a”
* is represented as a floating point value in the range 0 to 1.
* `rgb(r,g,b)` or `rgba(r,g,b,a)`, where “r”, “g”, “b” and
* “a” represent the red, green, blue and alpha values
* respectively. “r”, “g”, and “b” are represented as integers
* in the range 0 to 255, and “a” is represented as a floating
* point value in the range 0 to 1.
*
* These string forms are string forms that are supported by
* the CSS3 colors module, and can be parsed by gdk_rgba_parse().
* the CSS3 colors module, and can be parsed by [method@Gdk.RGBA.parse].
*
* Note that this string representation may lose some
* precision, since “r”, “g” and “b” are represented as 8-bit
* integers. If this is a concern, you should use a
* different representation.
* Note that this string representation may lose some precision,
* since “r”, “g” and “b” are represented as 8-bit integers. If
* this is a concern, you should use a different representation.
*
* Returns: A newly allocated text string
*/
@ -578,4 +575,3 @@ gdk_rgba_parser_parse (GtkCssParser *parser,
return FALSE;
}
}

145
gdk/gdkseat.c
View File

@ -28,21 +28,11 @@
#include "gdkintl.h"
#include "gdkinternals.h"
/**
* SECTION:gdkseat
* @Short_description: Object representing a user seat
* @Title: GdkSeat
* @See_also: #GdkDisplay, #GdkDevice
*
* The #GdkSeat object represents a collection of input devices
* that belong to a user.
*/
/**
* GdkSeat:
*
* The GdkSeat struct contains only private fields and
* should not be accessed directly.
* The `GdkSeat` object represents a collection of input devices
* that belong to a user.
*/
typedef struct _GdkSeatPrivate GdkSeatPrivate;
@ -120,10 +110,9 @@ gdk_seat_class_init (GdkSeatClass *klass)
/**
* GdkSeat::device-added:
* @seat: the object on which the signal is emitted
* @device: the newly added #GdkDevice.
* @device: the newly added `GdkDevice`.
*
* The ::device-added signal is emitted when a new input
* device is related to this seat.
* Emitted when a new input device is related to this seat.
*/
signals [DEVICE_ADDED] =
g_signal_new (g_intern_static_string ("device-added"),
@ -138,10 +127,9 @@ gdk_seat_class_init (GdkSeatClass *klass)
/**
* GdkSeat::device-removed:
* @seat: the object on which the signal is emitted
* @device: the just removed #GdkDevice.
* @device: the just removed `GdkDevice`.
*
* The ::device-removed signal is emitted when an
* input device is removed (e.g. unplugged).
* Emitted when an input device is removed (e.g. unplugged).
*/
signals [DEVICE_REMOVED] =
g_signal_new (g_intern_static_string ("device-removed"),
@ -156,12 +144,13 @@ gdk_seat_class_init (GdkSeatClass *klass)
/**
* GdkSeat::tool-added:
* @seat: the object on which the signal is emitted
* @tool: the new #GdkDeviceTool known to the seat
* @tool: the new `GdkDeviceTool` known to the seat
*
* The ::tool-added signal is emitted whenever a new tool
* is made known to the seat. The tool may later be assigned
* to a device (i.e. on proximity with a tablet). The device
* will emit the #GdkDevice::tool-changed signal accordingly.
* Emitted whenever a new tool is made known to the seat.
*
* The tool may later be assigned to a device (i.e. on
* proximity with a tablet). The device will emit the
* [signalGdkDevice::tool-changed] signal accordingly.
*
* A same tool may be used by several devices.
*/
@ -177,10 +166,9 @@ gdk_seat_class_init (GdkSeatClass *klass)
/**
* GdkSeat::tool-removed:
* @seat: the object on which the signal is emitted
* @tool: the just removed #GdkDeviceTool
* @tool: the just removed `GdkDeviceTool`
*
* This signal is emitted whenever a tool is no longer known
* to this @seat.
* Emitted whenever a tool is no longer known to this @seat.
*/
signals [TOOL_REMOVED] =
g_signal_new (g_intern_static_string ("tool-removed"),
@ -194,7 +182,7 @@ gdk_seat_class_init (GdkSeatClass *klass)
/**
* GdkSeat:display:
*
* #GdkDisplay of this seat.
* `GdkDisplay` of this seat.
*/
props[PROP_DISPLAY] =
g_param_spec_object ("display",
@ -215,12 +203,12 @@ gdk_seat_init (GdkSeat *seat)
/**
* gdk_seat_get_capabilities:
* @seat: a #GdkSeat
* @seat: a `GdkSeat`
*
* Returns the capabilities this #GdkSeat currently has.
* Returns the capabilities this `GdkSeat` currently has.
*
* Returns: the seat capabilities
**/
*/
GdkSeatCapabilities
gdk_seat_get_capabilities (GdkSeat *seat)
{
@ -234,30 +222,30 @@ gdk_seat_get_capabilities (GdkSeat *seat)
/*
* gdk_seat_grab:
* @seat: a #GdkSeat
* @surface: the #GdkSurface which will own the grab
* @seat: a `GdkSeat`
* @surface: the `GdkSurface` which will own the grab
* @capabilities: capabilities that will be grabbed
* @owner_events: if %FALSE then all device events are reported with respect to
* @surface and are only reported if selected by @event_mask. If
* %TRUE then pointer events for this application are reported
* as normal, but pointer events outside this application are
* reported with respect to @surface and only if selected by
* @event_mask. In either mode, unreported events are discarded.
* @cursor: (nullable): the cursor to display while the grab is active. If
* this is %NULL then the normal cursors are used for
* @surface and its descendants, and the cursor for @surface is used
* elsewhere.
* @surface and are only reported if selected by @event_mask. If %TRUE then
* pointer events for this application are reported as normal, but pointer
* events outside this application are reported with respect to @surface and
* only if selected by @event_mask. In either mode, unreported events are
* discarded.
* @cursor: (nullable): the cursor to display while the grab is active.
* If this is %NULL then the normal cursors are used for @surface and
* its descendants, and the cursor for @surface is used elsewhere.
* @event: (nullable): the event that is triggering the grab, or %NULL if none
* is available.
* @prepare_func: (nullable) (scope call): function to
* prepare the surface to be grabbed, it can be %NULL if @surface is
* visible before this call.
* is available.
* @prepare_func: (nullable) (scope call): function to prepare the surface
* to be grabbed, it can be %NULL if @surface is visible before this call.
* @prepare_func_data: (closure): user data to pass to @prepare_func
*
* Grabs the seat so that all events corresponding to the given @capabilities
* are passed to this application until the seat is ungrabbed with gdk_seat_ungrab(),
* or the surface becomes hidden. This overrides any previous grab on the
* seat by this client.
* are passed to this application.
*
* The grab remains in place until the seat is ungrabbed with
* [method@Gdk.Seat.ungrab], or the surface becomes hidden. This overrides
* any previous grab on the seat by this client.
*
* As a rule of thumb, if a grab is desired over %GDK_SEAT_CAPABILITY_POINTER,
* all other "pointing" capabilities (eg. %GDK_SEAT_CAPABILITY_TOUCH) should
@ -269,18 +257,18 @@ gdk_seat_get_capabilities (GdkSeat *seat)
* events corresponding to the given capabilities. For example in GTK this
* is used for Drag and Drop operations, popup menus and such.
*
* Note that if the event mask of a #GdkSurface has selected both button press
* Note that if the event mask of a `GdkSurface` has selected both button press
* and button release events, or touch begin and touch end, then a press event
* will cause an automatic grab until the button is released, equivalent to a
* grab on the surface with @owner_events set to %TRUE. This is done because most
* applications expect to receive paired press and release events.
* grab on the surface with @owner_events set to %TRUE. This is done because
* most applications expect to receive paired press and release events.
*
* If you set up anything at the time you take the grab that needs to be
* cleaned up when the grab ends, you should handle the #GdkEventGrabBroken
* cleaned up when the grab ends, you should handle the `GdkEventGrabBroken`
* events that are emitted when the grab ends unvoluntarily.
*
* Returns: %GDK_GRAB_SUCCESS if the grab was successful.
**/
*/
GdkGrabStatus
gdk_seat_grab (GdkSeat *seat,
GdkSurface *surface,
@ -308,10 +296,12 @@ gdk_seat_grab (GdkSeat *seat,
/*
* gdk_seat_ungrab:
* @seat: a #GdkSeat
* @seat: a `GdkSeat`
*
* Releases a grab added through gdk_seat_grab().
**/
* Releases a grab.
*
* See [method@Gdk.Seat.grab] for more information.
*/
void
gdk_seat_ungrab (GdkSeat *seat)
{
@ -330,10 +320,10 @@ gdk_seat_ungrab (GdkSeat *seat)
*
* Returns the devices that match the given capabilities.
*
* Returns: (transfer container) (element-type GdkDevice): A list of #GdkDevices.
* The list must be freed with g_list_free(), the elements are owned
* by GTK and must not be freed.
**/
* Returns: (transfer container) (element-type GdkDevice): A list
* of `GdkDevices`. The list must be freed with g_list_free(),
* the elements are owned by GTK and must not be freed.
*/
GList *
gdk_seat_get_devices (GdkSeat *seat,
GdkSeatCapabilities capabilities)
@ -348,13 +338,13 @@ gdk_seat_get_devices (GdkSeat *seat,
/**
* gdk_seat_get_pointer:
* @seat: a #GdkSeat
* @seat: a `GdkSeat`
*
* Returns the device that routes pointer events.
*
* Returns: (transfer none) (nullable): a #GdkDevice with pointer
* capabilities. This object is owned by GTK and must not be freed.
**/
* Returns: (transfer none) (nullable): a `GdkDevice` with pointer
* capabilities. This object is owned by GTK and must not be freed.
*/
GdkDevice *
gdk_seat_get_pointer (GdkSeat *seat)
{
@ -368,13 +358,13 @@ gdk_seat_get_pointer (GdkSeat *seat)
/**
* gdk_seat_get_keyboard:
* @seat: a #GdkSeat
* @seat: a `GdkSeat`
*
* Returns the device that routes keyboard events.
*
* Returns: (transfer none) (nullable): a #GdkDevice with keyboard
* capabilities. This object is owned by GTK and must not be freed.
**/
* Returns: (transfer none) (nullable): a `GdkDevice` with keyboard
* capabilities. This object is owned by GTK and must not be freed.
*/
GdkDevice *
gdk_seat_get_keyboard (GdkSeat *seat)
{
@ -404,13 +394,13 @@ gdk_seat_device_removed (GdkSeat *seat,
/**
* gdk_seat_get_display:
* @seat: a #GdkSeat
* @seat: a `GdkSeat`
*
* Returns the #GdkDisplay this seat belongs to.
* Returns the `GdkDisplay` this seat belongs to.
*
* Returns: (transfer none): a #GdkDisplay. This object is owned by GTK
* and must not be freed.
**/
* Returns: (transfer none): a `GdkDisplay`. This object
* is owned by GTK and must not be freed.
*/
GdkDisplay *
gdk_seat_get_display (GdkSeat *seat)
{
@ -464,14 +454,13 @@ gdk_seat_get_tool (GdkSeat *seat,
/**
* gdk_seat_get_tools:
* @seat: A #GdkSeat
* @seat: a `GdkSeat`
*
* Returns all #GdkDeviceTools that are known to the
* application.
* Returns all `GdkDeviceTools` that are known to the application.
*
* Returns: (transfer container) (element-type Gdk.DeviceTool):
* A list of tools. Free with g_list_free().
**/
* A list of tools. Free with g_list_free().
*/
GList *
gdk_seat_get_tools (GdkSeat *seat)
{

8
gdk/gdksnapshot.c
View File

@ -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

5
gdk/gdksnapshot.h
View File

@ -29,11 +29,6 @@
G_BEGIN_DECLS
/**
* GdkSnapshot:
*
* Base type for snapshot operations.
*/
typedef struct _GdkSnapshotClass GdkSnapshotClass;

551
gdk/gdksurface.c
View File

File diff suppressed because it is too large Load Diff

84
gdk/gdktexture.c
View File

@ -17,21 +17,21 @@
*/
/**
* SECTION:gdktexture
* @Title: GdkTexture
* @Short_description: Pixel data
* GdkTexture:
*
* #GdkTexture is the basic element used to refer to pixel data.
* It is primarily mean for pixel data that will not change over
* `GdkTexture` is the basic element used to refer to pixel data.
*
* It is primarily meant for pixel data that will not change over
* multiple frames, and will be used for a long time.
*
* There are various ways to create #GdkTexture objects from a
* #GdkPixbuf, or a Cairo surface, or other pixel data.
* There are various ways to create `GdkTexture` objects from a
* `GdkPixbuf`, or a Cairo surface, or other pixel data.
*
* The ownership of the pixel data is transferred to the #GdkTexture
* instance; you can only make a copy of it, via gdk_texture_download().
* The ownership of the pixel data is transferred to the `GdkTexture`
* instance; you can only make a copy of it, via
* [method@Gdk.Texture.download].
*
* #GdkTexture is an immutable object: That means you cannot change
* `GdkTexture` is an immutable object: That means you cannot change
* anything about it other than increasing the reference count via
* g_object_ref().
*/
@ -53,12 +53,6 @@ gtk_snapshot_append_texture (GdkSnapshot *snapshot,
GdkTexture *texture,
const graphene_rect_t *bounds);
/**
* GdkTexture:
*
* The `GdkTexture` structure contains only private data.
*/
enum {
PROP_0,
PROP_WIDTH,
@ -246,9 +240,10 @@ gdk_texture_init (GdkTexture *self)
* @surface: a cairo image surface
*
* Creates a new texture object representing the surface.
*
* @surface must be an image surface with format CAIRO_FORMAT_ARGB32.
*
* Returns: a new #GdkTexture
* Returns: a new `GdkTexture`
*/
GdkTexture *
gdk_texture_new_for_surface (cairo_surface_t *surface)
@ -279,11 +274,11 @@ gdk_texture_new_for_surface (cairo_surface_t *surface)
/**
* gdk_texture_new_for_pixbuf:
* @pixbuf: a #GdkPixbuf
* @pixbuf: a `GdkPixbuf`
*
* Creates a new texture object representing the #GdkPixbuf.
* Creates a new texture object representing the `GdkPixbuf`.
*
* Returns: a new #GdkTexture
* Returns: a new `GdkTexture`
*/
GdkTexture *
gdk_texture_new_for_pixbuf (GdkPixbuf *pixbuf)
@ -316,16 +311,16 @@ gdk_texture_new_for_pixbuf (GdkPixbuf *pixbuf)
* @resource_path: the path of the resource file
*
* Creates a new texture by loading an image from a resource.
* The file format is detected automatically.
* The supported formats are PNG and JPEG, though more formats might be
* available.
*
* The file format is detected automatically. The supported formats
* are PNG and JPEG, though more formats might be available.
*
* It is a fatal error if @resource_path does not specify a valid
* image resource and the program will abort if that happens.
* If you are unsure about the validity of a resource, use
* gdk_texture_new_from_file() to load it.
* [ctor@Gdk.Texture.new_from_file] to load it.
*
* Return value: A newly-created texture
* Return value: A newly-created `GdkTexture`
*/
GdkTexture *
gdk_texture_new_from_resource (const char *resource_path)
@ -348,18 +343,18 @@ gdk_texture_new_from_resource (const char *resource_path)
/**
* gdk_texture_new_from_file:
* @file: #GFile to load
* @file: `GFile` to load
* @error: Return location for an error
*
* Creates a new texture by loading an image from a file.
* The file format is detected automatically.
* The supported formats are PNG and JPEG, though more formats might be
* available.
*
* The file format is detected automatically. The supported formats
* are PNG and JPEG, though more formats might be available.
*
* If %NULL is returned, then @error will be set.
*
* Return value: A newly-created #GdkTexture or %NULL if an error occurred.
**/
* Return value: A newly-created `GdkTexture` or %NULL if an error occurred.
*/
GdkTexture *
gdk_texture_new_from_file (GFile *file,
GError **error)
@ -388,11 +383,11 @@ gdk_texture_new_from_file (GFile *file,
/**
* gdk_texture_get_width:
* @texture: a #GdkTexture
* @texture: a `GdkTexture`
*
* Returns the width of @texture, in pixels.
*
* Returns: the width of the #GdkTexture
* Returns: the width of the `GdkTexture`
*/
int
gdk_texture_get_width (GdkTexture *texture)
@ -404,11 +399,11 @@ gdk_texture_get_width (GdkTexture *texture)
/**
* gdk_texture_get_height:
* @texture: a #GdkTexture
* @texture: a `GdkTexture`
*
* Returns the height of the @texture, in pixels.
*
* Returns: the height of the #GdkTexture
* Returns: the height of the `GdkTexture`
*/
int
gdk_texture_get_height (GdkTexture *texture)
@ -456,21 +451,22 @@ gdk_texture_download_area (GdkTexture *texture,
/**
* gdk_texture_download:
* @texture: a #GdkTexture
* @texture: a `GdkTexture`
* @data: (array): pointer to enough memory to be filled with the
* downloaded data of @texture
* @stride: rowstride in bytes
*
* Downloads the @texture into local memory. This may be
* an expensive operation, as the actual texture data may
* reside on a GPU or on a remote display server.
* Downloads the @texture into local memory.
*
* This may be an expensive operation, as the actual texture data
* may reside on a GPU or on a remote display server.
*
* The data format of the downloaded data is equivalent to
* %CAIRO_FORMAT_ARGB32, so every downloaded pixel requires
* 4 bytes of memory.
*
* Downloading a texture into a Cairo image surface:
* |[<!-- 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)

224
gdk/gdktoplevel.c
View File

@ -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, asking the
* desktop environment/windowing system to let all keyboard events reach
* the surface, as long as it is focused, instead of triggering system
* actions.
* Requests that the @toplevel inhibit the system shortcuts.
*
* This is asking the desktop environment/windowing system to let all
* keyboard events reach the surface, as long as it is focused, instead
* of triggering system actions.
*
* If granted, the rerouting remains active until the default shortcuts
* processing is restored with gdk_toplevel_restore_system_shortcuts(),
* processing is restored with [method@Gdk.Toplevel.restore_system_shortcuts],
* or the request is revoked by the desktop environment, windowing system
* or the user.
*
@ -531,8 +606,7 @@ gdk_toplevel_supports_edge_constraints (GdkToplevel *toplevel)
* or deny the request or even choose to ignore the request entirely.
*
* The caller can be notified whenever the request is granted or revoked
* by listening to the GdkToplevel::shortcuts-inhibited property.
*
* by listening to the [property@Gdk.Toplevel:shortcuts-inhibited] property.
*/
void
gdk_toplevel_inhibit_system_shortcuts (GdkToplevel *toplevel,
@ -546,10 +620,12 @@ gdk_toplevel_inhibit_system_shortcuts (GdkToplevel *toplevel,
/**
* gdk_toplevel_restore_system_shortcuts:
* @toplevel: a #GdkToplevel
* @toplevel: a `GdkToplevel`
*
* Restore default system keyboard shortcuts which were previously
* requested to be inhibited by gdk_toplevel_inhibit_system_shortcuts().
* inhibited.
*
* This undoes the effect of [method@Gdk.Toplevel.inhibit_system_shortcuts].
*/
void
gdk_toplevel_restore_system_shortcuts (GdkToplevel *toplevel)
@ -561,15 +637,17 @@ gdk_toplevel_restore_system_shortcuts (GdkToplevel *toplevel)
/**
* gdk_toplevel_begin_resize:
* @toplevel: a #GdkToplevel
* @toplevel: a `GdkToplevel`
* @edge: the edge or corner from which the drag is started
* @device: (nullable): the device used for the operation
* @button: the button being used to drag, or 0 for a keyboard-initiated drag
* @x: surface X coordinate of mouse click that began the drag
* @y: surface Y coordinate of mouse click that began the drag
* @timestamp: timestamp of mouse click that began the drag (use gdk_event_get_time())
* @timestamp: timestamp of mouse click that began the drag (use
* [method@Gdk.Event.get_time])
*
* Begins an interactive resize operation.
*
* Begins an interactive resize operation (for a toplevel surface).
* You might use this function to implement a “window resize grip.”
*/
void
@ -607,9 +685,11 @@ gdk_toplevel_begin_resize (GdkToplevel *toplevel,
* @button: the button being used to drag, or 0 for a keyboard-initiated drag
* @x: surface X coordinate of mouse click that began the drag
* @y: surface Y coordinate of mouse click that began the drag
* @timestamp: timestamp of mouse click that began the drag
* @timestamp: timestamp of mouse click that began the drag (use
* [method@Gdk.Event.get_time])
*
* Begins an interactive move operation.
*
* Begins an interactive move operation (for a toplevel surface).
* You might use this function to implement draggable titlebars.
*/
void

19
gdk/gdktoplevel.h
View File

@ -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)

12
gdk/gdktoplevellayout.c
View File

@ -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
{

37
gdk/gdktoplevelsize.c
View File

@ -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.

31
gdk/gdktypes.h
View File

@ -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
{

59
gdk/gdkvulkancontext.c
View File

@ -28,27 +28,18 @@
#include "gdkinternals.h"
#include "gdkintl.h"
/**
* SECTION:gdkvulkancontext
* @Title: GdkVulkanContext
* @Short_description: Vulkan draw context
*
* #GdkVulkanContext is an object representing the platform-specific
* Vulkan draw context.
*
* #GdkVulkanContexts are created for a #GdkSurface using
* gdk_surface_create_vulkan_context(), and the context will match the
* the characteristics of the surface.
*
* Support for #GdkVulkanContext is platform-specific, context creation
* can fail, returning %NULL context.
*/
/**
* GdkVulkanContext:
*
* The GdkVulkanContext struct contains only private fields and should not
* be accessed directly.
* `GdkVulkanContext` is an object representing the platform-specific
* Vulkan draw context.
*
* `GdkVulkanContext`s are created for a surface using
* [method@Gdk.Surface.create_vulkan_context], and the context will match
* the the characteristics of the surface.
*
* Support for `GdkVulkanContext` is platform-specific and context creation
* can fail, returning %NULL context.
*/
typedef struct _GdkVulkanContextPrivate GdkVulkanContextPrivate;
@ -540,8 +531,9 @@ gdk_vulkan_context_class_init (GdkVulkanContextClass *klass)
* GdkVulkanContext::images-updated:
* @context: the object on which the signal is emitted
*
* This signal is emitted when the images managed by this context have
* changed. Usually this means that the swapchain had to be recreated,
* Emitted when the images managed by this context have changed.
*
* Usually this means that the swapchain had to be recreated,
* for example in response to a change of the surface size.
*/
signals[IMAGES_UPDATED] =
@ -650,7 +642,7 @@ gdk_vulkan_context_initable_init (GInitableIface *iface)
/**
* gdk_vulkan_context_get_instance:
* @context: a #GdkVulkanContext
* @context: a `GdkVulkanContext`
*
* Gets the Vulkan instance that is associated with @context.
*
@ -666,7 +658,7 @@ gdk_vulkan_context_get_instance (GdkVulkanContext *context)
/**
* gdk_vulkan_context_get_physical_device:
* @context: a #GdkVulkanContext
* @context: a `GdkVulkanContext`
*
* Gets the Vulkan physical device that this context is using.
*
@ -698,7 +690,7 @@ gdk_vulkan_context_get_device (GdkVulkanContext *context)
/**
* gdk_vulkan_context_get_queue:
* @context: a #GdkVulkanContext
* @context: a `GdkVulkanContext`
*
* Gets the Vulkan queue that this context is using.
*
@ -714,9 +706,10 @@ gdk_vulkan_context_get_queue (GdkVulkanContext *context)
/**
* gdk_vulkan_context_get_queue_family_index:
* @context: a #GdkVulkanContext
* @context: a `GdkVulkanContext`
*
* Gets the family index for the queue that this context is using.
*
* See vkGetPhysicalDeviceQueueFamilyProperties().
*
* Returns: the index
@ -731,7 +724,7 @@ gdk_vulkan_context_get_queue_family_index (GdkVulkanContext *context)
/**
* gdk_vulkan_context_get_image_format:
* @context: a #GdkVulkanContext
* @context: a `GdkVulkanContext`
*
* Gets the image format that this context is using.
*
@ -749,7 +742,7 @@ gdk_vulkan_context_get_image_format (GdkVulkanContext *context)
/**
* gdk_vulkan_context_get_n_images:
* @context: a #GdkVulkanContext
* @context: a `GdkVulkanContext`
*
* Gets the number of images that this context is using in its swap chain.
*
@ -767,7 +760,7 @@ gdk_vulkan_context_get_n_images (GdkVulkanContext *context)
/**
* gdk_vulkan_context_get_image:
* @context: a #GdkVulkanContext
* @context: a `GdkVulkanContext`
* @id: the index of the image to return
*
* Gets the image with index @id that this context is using.
@ -788,12 +781,12 @@ gdk_vulkan_context_get_image (GdkVulkanContext *context,
/**
* gdk_vulkan_context_get_draw_index:
* @context: a #GdkVulkanContext
* @context: a `GdkVulkanContext`
*
* Gets the index of the image that is currently being drawn.
*
* This function can only be used between gdk_draw_context_begin_frame() and
* gdk_draw_context_end_frame() calls.
* This function can only be used between [method@Gdk.DrawContext.begin_frame]
* and [method@Gdk.DrawContext.end_frame] calls.
*
* Returns: the index of the images that is being drawn
*/
@ -810,13 +803,13 @@ gdk_vulkan_context_get_draw_index (GdkVulkanContext *context)
/**
* gdk_vulkan_context_get_draw_semaphore:
* @context: a #GdkVulkanContext
* @context: a `GdkVulkanContext`
*
* Gets the Vulkan semaphore that protects access to the image that is
* currently being drawn.
*
* This function can only be used between gdk_draw_context_begin_frame() and
* gdk_draw_context_end_frame() calls.
* This function can only be used between [method@Gdk.DrawContext.begin_frame]
* and [method@Gdk.DrawContext.end_frame] calls.
*
* Returns: (transfer none): the VkSemaphore
*/