AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2025-01-16 23:24:16 +00:00
Code Issues Projects Releases Wiki Activity

dragsource: Convert docs

Browse Source
This commit is contained in:
Matthias Clasen 2021-02-28 13:02:19 -05:00 committed by Emmanuele Bassi
parent eb77ff9696
commit f4b498031a
1 changed files with 87 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

166
gtk/gtkdragsource.c
View File

@ -42,22 +42,19 @@
#include "gtkgesturesingle.h" #include "gtkgesturesingle.h"
/** /**
* SECTION:gtkdragsource * GtkDragSource:
* @Short_description: Event controller to initiate DND operations
* @Title: GtkDragSource
* *
* GtkDragSource is an event controller that is used to initiate * `GtkDragSource` is an event controller to initiate Drag-And-Drop operations.
* Drag-And-Drop operations.
* *
* GtkDragSource can be set up with the necessary * `GtkDragSource` can be set up with the necessary
* ingredients for a DND operation ahead of time. This includes * ingredients for a DND operation ahead of time. This includes
* the source for the data that is being transferred, in the form * the source for the data that is being transferred, in the form
* of a #GdkContentProvider, the desired action, and the icon to * of a `GdkContentProvider`, the desired action, and the icon to
* use during the drag operation. After setting it up, the drag * use during the drag operation. After setting it up, the drag
* source must be added to a widget as an event controller, using * source must be added to a widget as an event controller, using
* gtk_widget_add_controller(). * [method@Gtk.Widget.add_controller].
* *
* |[<!-- language="C" --> * ```c
* static void * static void
* my_widget_init (MyWidget *self) * my_widget_init (MyWidget *self)
* { * {
@ -68,18 +65,19 @@
* *
* gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (drag_source)); * gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (drag_source));
* } * }
* ]| * ```
* *
* Setting up the content provider and icon ahead of time only * Setting up the content provider and icon ahead of time only makes
* makes sense when the data does not change. More commonly, you * sense when the data does not change. More commonly, you will want
* will want to set them up just in time. To do so, #GtkDragSource * to set them up just in time. To do so, `GtkDragSource` has
* has #GtkDragSource::prepare and #GtkDragSource::drag-begin signals. * [signal@Gtk.DragSource::prepare] and [signal@Gtk.DragSource::drag-begin]
* signals.
* *
* The ::prepare signal is emitted before a drag is started, and * The ::prepare signal is emitted before a drag is started, and
* can be used to set the content provider and actions that the * can be used to set the content provider and actions that the
* drag should be started with. * drag should be started with.
* *
* |[<!-- language="C" --> * ```c
* static GdkContentProvider * * static GdkContentProvider *
* on_drag_prepare (GtkDragSource *source, * on_drag_prepare (GtkDragSource *source,
* double x, * double x,
@ -97,12 +95,12 @@
* gdk_content_provider_new_typed (GDK_TYPE_PIXBUF, pixbuf), * gdk_content_provider_new_typed (GDK_TYPE_PIXBUF, pixbuf),
* }, 2); * }, 2);
* } * }
* ]| * ```
* *
* The ::drag-begin signal is emitted after the #GdkDrag object has * The ::drag-begin signal is emitted after the `GdkDrag` object has
* been created, and can be used to set up the drag icon. * been created, and can be used to set up the drag icon.
* *
* |[<!-- language="C" --> * ```c
* static void * static void
* on_drag_begin (GtkDragSource *source, * on_drag_begin (GtkDragSource *source,
* GtkDrag *drag, * GtkDrag *drag,
@ -113,14 +111,14 @@
* gtk_drag_source_set_icon (source, paintable, 0, 0); * gtk_drag_source_set_icon (source, paintable, 0, 0);
* g_object_unref (paintable); * g_object_unref (paintable);
* } * }
* ]| * ```
* *
* During the DND operation, GtkDragSource emits signals that * During the DND operation, `GtkDragSource` emits signals that
* can be used to obtain updates about the status of the operation, * can be used to obtain updates about the status of the operation,
* but it is not normally necessary to connect to any signals, * but it is not normally necessary to connect to any signals,
* except for one case: when the supported actions include * except for one case: when the supported actions include
* %GDK_ACTION_MOVE, you need to listen for the * %GDK_ACTION_MOVE, you need to listen for the
* #GtkDragSource::drag-end signal and delete the * [signal@Gtk.DragSource::drag-end] signal and delete the
* data after it has been transferred. * data after it has been transferred.
*/ */
@ -320,10 +318,9 @@ gtk_drag_source_class_init (GtkDragSourceClass *class)
class->prepare = gtk_drag_source_prepare; class->prepare = gtk_drag_source_prepare;
/** /**
* GtkDragSource:content: * GtkDragSource:content: (attributes org.gtk.Property.get=gtk_drag_source_get_content org.gtk.Propery.set=gtk_drag_source_set_content)
* *
* The data that is offered by drag operations from this source, * The data that is offered by drag operations from this source.
* in the form of a #GdkContentProvider.
*/ */
properties[PROP_CONTENT] = properties[PROP_CONTENT] =
g_param_spec_object ("content", g_param_spec_object ("content",
@ -333,11 +330,11 @@ gtk_drag_source_class_init (GtkDragSourceClass *class)
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY); G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY);
/** /**
* GtkDragSource:actions: * GtkDragSource:actions: (attributes org.gtk.Property.get=gtk_drag_source_get_actions org.gtk.Property.set=gtk_drag_source_set_actions)
* *
* The actions that are supported by drag operations from the source. * The actions that are supported by drag operations from the source.
* *
* Note that you must handle the #GtkDragSource::drag-end signal * Note that you must handle the [signal@Gtk.DragSource::drag-end] signal
* if the actions include %GDK_ACTION_MOVE. * if the actions include %GDK_ACTION_MOVE.
*/ */
properties[PROP_ACTIONS] = properties[PROP_ACTIONS] =
@ -351,17 +348,18 @@ gtk_drag_source_class_init (GtkDragSourceClass *class)
/** /**
* GtkDragSource::prepare: * GtkDragSource::prepare:
* @source: the #GtkDragSource * @source: the `GtkDragSource`
* @x: the X coordinate of the drag starting point * @x: the X coordinate of the drag starting point
* @y: the Y coordinate fo the drag starting point * @y: the Y coordinate fo the drag starting point
* *
* The ::prepare signal is emitted when a drag is about to be initiated. * Emitted when a drag is about to be initiated.
* It returns the * #GdkContentProvider to use for the drag that is about
* to start. The default handler for this signal returns the value of
* the #GtkDragSource:content property, so if you set up that property
* ahead of time, you don't need to connect to this signal.
* *
* Returns: (transfer full) (nullable): a #GdkContentProvider, or %NULL * It returns the `GdkContentProvider` to use for the drag that is about
* to start. The default handler for this signal returns the value of
* the [property@Gtk.DragSource:content] property, so if you set up that
* property ahead of time, you don't need to connect to this signal.
*
* Returns: (transfer full) (nullable): a `GdkContentProvider`, or %NULL
*/ */
signals[PREPARE] = signals[PREPARE] =
g_signal_new (I_("prepare"), g_signal_new (I_("prepare"),
@ -375,12 +373,13 @@ gtk_drag_source_class_init (GtkDragSourceClass *class)
/** /**
* GtkDragSource::drag-begin: * GtkDragSource::drag-begin:
* @source: the #GtkDragSource * @source: the `GtkDragSource`
* @drag: the #GdkDrag object * @drag: the `GdkDrag` object
* *
* The ::drag-begin signal is emitted on the drag source when a drag * Emitted on the drag source when a drag is started.
* is started. It can be used to e.g. set a custom drag icon with *
* gtk_drag_source_set_icon(). * It can be used to e.g. set a custom drag icon with
* [method@Gtk.DragSource.set_icon].
*/ */
signals[DRAG_BEGIN] = signals[DRAG_BEGIN] =
g_signal_new (I_("drag-begin"), g_signal_new (I_("drag-begin"),
@ -394,14 +393,16 @@ gtk_drag_source_class_init (GtkDragSourceClass *class)
/** /**
* GtkDragSource::drag-end: * GtkDragSource::drag-end:
* @source: the #GtkDragSource * @source: the `GtkDragSource`
* @drag: the #GdkDrag object * @drag: the `GdkDrag` object
* @delete_data: %TRUE if the drag was performing %GDK_ACTION_MOVE, * @delete_data: %TRUE if the drag was performing %GDK_ACTION_MOVE,
* and the data should be deleted * and the data should be deleted
* *
* The ::drag-end signal is emitted on the drag source when a drag is * Emitted on the drag source when a drag is finished.
* finished. A typical reason to connect to this signal is to undo *
* things done in #GtkDragSource::prepare or #GtkDragSource::drag-begin. * A typical reason to connect to this signal is to undo
* things done in [signal@Gtk.DragSource::prepare] or
* [signal@Gtk.DragSource::drag-begin] handlers.
*/ */
signals[DRAG_END] = signals[DRAG_END] =
g_signal_new (I_("drag-end"), g_signal_new (I_("drag-end"),
@ -416,12 +417,13 @@ gtk_drag_source_class_init (GtkDragSourceClass *class)
/** /**
* GtkDragSource::drag-cancel: * GtkDragSource::drag-cancel:
* @source: the #GtkDragSource * @source: the `GtkDragSource`
* @drag: the #GdkDrag object * @drag: the `GdkDrag` object
* @reason: information on why the drag failed * @reason: information on why the drag failed
* *
* The ::drag-cancel signal is emitted on the drag source when a drag has * Emitted on the drag source when a drag has failed.
* failed. The signal handler may handle a failed drag operation based on *
* The signal handler may handle a failed drag operation based on
* the type of error. It should return %TRUE if the failure has been handled * the type of error. It should return %TRUE if the failure has been handled
* and the default "drag operation failed" animation should not be shown. * and the default "drag operation failed" animation should not be shown.
* *
@ -600,9 +602,9 @@ gtk_drag_source_drag_begin (GtkDragSource *source)
/** /**
* gtk_drag_source_new: * gtk_drag_source_new:
* *
* Creates a new #GtkDragSource object. * Creates a new `GtkDragSource` object.
* *
* Returns: the new #GtkDragSource * Returns: the new `GtkDragSource`
*/ */
GtkDragSource * GtkDragSource *
gtk_drag_source_new (void) gtk_drag_source_new (void)
@ -611,12 +613,12 @@ gtk_drag_source_new (void)
} }
/** /**
* gtk_drag_source_get_content: * gtk_drag_source_get_content: (attributes org.gtk.Method.get_property=content)
* @source: a #GtkDragSource * @source: a `GtkDragSource`
* *
* Gets the current content provider of a #GtkDragSource. * Gets the current content provider of a `GtkDragSource`.
* *
* Returns: (nullable) (transfer none): the #GdkContentProvider of @source * Returns: (nullable) (transfer none): the `GdkContentProvider` of @source
*/ */
GdkContentProvider * GdkContentProvider *
gtk_drag_source_get_content (GtkDragSource *source) gtk_drag_source_get_content (GtkDragSource *source)
@ -627,21 +629,20 @@ gtk_drag_source_get_content (GtkDragSource *source)
} }
/** /**
* gtk_drag_source_set_content: * gtk_drag_source_set_content: (attributes org.gtk.Method.set_property=content)
* @source: a #GtkDragSource * @source: a `GtkDragSource`
* @content: (nullable): a #GdkContentProvider, or %NULL * @content: (nullable): a `GdkContentProvider`, or %NULL
* *
* Sets a content provider on a #GtkDragSource. * Sets a content provider on a `GtkDragSource`.
* *
* When the data is requested in the cause of a * When the data is requested in the cause of a DND operation,
* DND operation, it will be obtained from the * it will be obtained from the content provider.
* content provider.
* *
* This function can be called before a drag is started, * This function can be called before a drag is started,
* or in a handler for the #GtkDragSource::prepare signal. * or in a handler for the [signal@Gtk.DragSource::prepare] signal.
* *
* You may consider setting the content provider back to * You may consider setting the content provider back to
* %NULL in a #GtkDragSource::drag-end signal handler. * %NULL in a [signal@Gtk.DragSource::drag-end] signal handler.
*/ */
void void
gtk_drag_source_set_content (GtkDragSource *source, gtk_drag_source_set_content (GtkDragSource *source,
@ -656,10 +657,10 @@ gtk_drag_source_set_content (GtkDragSource *source,
} }
/** /**
* gtk_drag_source_get_actions: * gtk_drag_source_get_actions: (attributes org.gtk.Method.get_property=actions)
* @source: a #GtkDragSource * @source: a `GtkDragSource`
* *
* Gets the actions that are currently set on the #GtkDragSource. * Gets the actions that are currently set on the `GtkDragSource`.
* *
* Returns: the actions set on @source * Returns: the actions set on @source
*/ */
@ -672,20 +673,19 @@ gtk_drag_source_get_actions (GtkDragSource *source)
} }
/** /**
* gtk_drag_source_set_actions: * gtk_drag_source_set_actions: (attributes org.gtk.Method.set_property=actions)
* @source: a #GtkDragSource * @source: a `GtkDragSource`
* @actions: the actions to offer * @actions: the actions to offer
* *
* Sets the actions on the #GtkDragSource. * Sets the actions on the `GtkDragSource`.
* *
* During a DND operation, the actions are offered * During a DND operation, the actions are offered to potential
* to potential drop targets. If @actions include * drop targets. If @actions include %GDK_ACTION_MOVE, you need
* %GDK_ACTION_MOVE, you need to listen to the * to listen to the [signal@Gtk.DragSource::drag-end] signal and
* #GtkDragSource::drag-end signal and handle * handle @delete_data being %TRUE.
* @delete_data being %TRUE.
* *
* This function can be called before a drag is started, * This function can be called before a drag is started,
* or in a handler for the #GtkDragSource::prepare signal. * or in a handler for the [signal@Gtk.DragSource::prepare] signal.
*/ */
void void
gtk_drag_source_set_actions (GtkDragSource *source, gtk_drag_source_set_actions (GtkDragSource *source,
@ -703,7 +703,7 @@ gtk_drag_source_set_actions (GtkDragSource *source,
/** /**
* gtk_drag_source_set_icon: * gtk_drag_source_set_icon:
* @source: a #GtkDragSource * @source: a `GtkDragSource`
* @paintable: (nullable): the #GdkPaintable to use as icon, or %NULL * @paintable: (nullable): the #GdkPaintable to use as icon, or %NULL
* @hot_x: the hotspot X coordinate on the icon * @hot_x: the hotspot X coordinate on the icon
* @hot_y: the hotspot Y coordinate on the icon * @hot_y: the hotspot Y coordinate on the icon
@ -716,7 +716,8 @@ gtk_drag_source_set_actions (GtkDragSource *source,
* If @paintable is %NULL, a default icon is used. * If @paintable is %NULL, a default icon is used.
* *
* This function can be called before a drag is started, or in * This function can be called before a drag is started, or in
* a #GtkDragSource::prepare or #GtkDragSource::drag-begin signal handler. * a [signal@Gtk.DragSource::prepare] or
* [signal@Gtk.DragSource::drag-begin] signal handler.
*/ */
void void
gtk_drag_source_set_icon (GtkDragSource *source, gtk_drag_source_set_icon (GtkDragSource *source,
@ -734,11 +735,12 @@ gtk_drag_source_set_icon (GtkDragSource *source,
/** /**
* gtk_drag_source_get_drag: * gtk_drag_source_get_drag:
* @source: a #GtkDragSource * @source: a `GtkDragSource`
* *
* Returns the underlying #GdkDrag object for an ongoing drag. * Returns the underlying `GdkDrag` object for an ongoing drag.
* *
* Returns: (nullable) (transfer none): the #GdkDrag of the current drag operation, or %NULL * Returns: (nullable) (transfer none): the `GdkDrag` of the current
* drag operation, or %NULL
*/ */
GdkDrag * GdkDrag *
gtk_drag_source_get_drag (GtkDragSource *source) gtk_drag_source_get_drag (GtkDragSource *source)
@ -750,7 +752,7 @@ gtk_drag_source_get_drag (GtkDragSource *source)
/** /**
* gtk_drag_source_drag_cancel: * gtk_drag_source_drag_cancel:
* @source: a #GtkDragSource * @source: a `GtkDragSource`
* *
* Cancels a currently ongoing drag operation. * Cancels a currently ongoing drag operation.
*/ */
@ -776,9 +778,7 @@ gtk_drag_source_drag_cancel (GtkDragSource *source)
* @current_x: current X coordinate * @current_x: current X coordinate
* @current_y: current Y coordinate * @current_y: current Y coordinate
* *
* Checks to see if a mouse drag starting at (@start_x, @start_y) and ending * Checks to see if a drag movement has passed the GTK drag threshold.
* at (@current_x, @current_y) has passed the GTK drag threshold, and thus
* should trigger the beginning of a drag-and-drop operation.
* *
* Returns: %TRUE if the drag threshold has been passed. * Returns: %TRUE if the drag threshold has been passed.
*/ */