AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-12-27 14:10:30 +00:00
Code Issues Projects Releases Wiki Activity

droptargetasync: Convert docs

Browse Source
This commit is contained in:
Matthias Clasen 2021-03-01 01:33:06 -05:00 committed by Emmanuele Bassi
parent 39dac1ff22
commit b3f6e95d62
1 changed files with 69 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

138
gtk/gtkdroptargetasync.c
View File

@ -35,41 +35,38 @@
/** /**
* SECTION:gtkdroptargetasync * GtkDropTargetAsync:
* @Short_description: Event controller to receive DND drops *
* @Title: GtkDropTargetAsync * `GtkDropTargetAsync` is an event controller to receive Drag-and-Drop
* @See_also: #GtkDropTarget * operations, asynchronously.
* *
* GtkDropTargetAsync is an auxiliary object that can be used to receive
* Drag-and-Drop operations.
* It is the more complete but also more complex method of handling drop * It is the more complete but also more complex method of handling drop
* operations compared to #GtkDropTarget and you should only use it if * operations compared to [class@Gtk.DropTarget], and you should only use
* #GtkDropTarget doesn't provide all the features you need. * it if `GtkDropTarget` doesn't provide all the features you need.
* *
* To use a #GtkDropTargetAsync to receive drops on a widget, you create * To use a `GtkDropTargetAsync` to receive drops on a widget, you create
* a #GtkDropTargetAsync object, configure which data formats and actions * a `GtkDropTargetAsync` object, configure which data formats and actions
* you support, connect to its signals, and then attach * you support, connect to its signals, and then attach it to the widget
* it to the widget with gtk_widget_add_controller(). * with [method@Gtk.Widget.add_controller].
* *
* During a drag operation, the first signal that a GtkDropTargetAsync * During a drag operation, the first signal that a `GtkDropTargetAsync`
* emits is #GtkDropTargetAsync::accept, which is meant to determine * emits is [signal@Gtk.DropTargetAsync::accept], which is meant to determine
* whether the target is a possible drop site for the ongoing drop. * whether the target is a possible drop site for the ongoing drop. The
* The default handler for the ::accept signal accepts the drop * default handler for the ::accept signal accepts the drop if it finds
* if it finds a compatible data format and an action that is supported * a compatible data format and an action that is supported on both sides.
* on both sides.
* *
* If it is, and the widget becomes a target, you will receive a * If it is, and the widget becomes a target, you will receive a
* #GtkDropTargetAsync::drag-enter signal, followed by * [signal@Gtk.DropTargetAsync::drag-enter] signal, followed by
* #GtkDropTargetAsync::drag-motion signals as the pointer moves, * [signal@Gtk.DropTargetAsync::drag-motion] signals as the pointer moves,
* optionally a #GtkDropTargetAsync::drop signal when a drop happens, * optionally a [signal@Gtk.DropTargetAsync::drop] signal when a drop happens,
* and finally a #GtkDropTargetAsync::drag-leave signal when the pointer * and finally a [signal@Gtk.DropTargetAsync::drag-leave] signal when the
* moves off the widget. * pointer moves off the widget.
* *
* The ::drag-enter and ::drag-motion handler return a #GdkDragAction * The ::drag-enter and ::drag-motion handler return a `GdkDragAction`
* to update the status of the ongoing operation. The ::drop handler * to update the status of the ongoing operation. The ::drop handler
* should decide if it ultimately accepts the drop and if it does, it * should decide if it ultimately accepts the drop and if it does, it
* should initiate the data transfer and finish the operation by calling * should initiate the data transfer and finish the operation by calling
* gdk_drop_finish(). * [method@Gdk.Drop.finish].
* *
* Between the ::drag-enter and ::drag-leave signals the widget is a * Between the ::drag-enter and ::drag-leave signals the widget is a
* current drop target, and will receive the %GTK_STATE_FLAG_DROP_ACTIVE * current drop target, and will receive the %GTK_STATE_FLAG_DROP_ACTIVE
@ -383,19 +380,19 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
class->drop = gtk_drop_target_async_drop; class->drop = gtk_drop_target_async_drop;
/** /**
* GtkDropTargetAsync:actions: * GtkDropTargetAsync:actions: (attributes org.gtk.Property.get=gtk_drop_target_async_get_actions org.gtk.Property.set=gtk_drop_target_async_set_actions)
* *
* The #GdkDragActions that this drop target supports * The `GdkDragActions` that this drop target supports.
*/ */
properties[PROP_ACTIONS] = properties[PROP_ACTIONS] =
g_param_spec_flags ("actions", P_("Actions"), P_("Actions"), g_param_spec_flags ("actions", P_("Actions"), P_("Actions"),
GDK_TYPE_DRAG_ACTION, 0, GDK_TYPE_DRAG_ACTION, 0,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY); G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY);
/** /**
* GtkDropTargetAsync:formats: * GtkDropTargetAsync:formats: (attributes org.gtk.Property.get=gtk_drop_target_async_get_formats org.gtk.Property.set=gtk_drop_target_async_set_formats)
* *
* The #GdkContentFormats that determines the supported data formats * The `GdkContentFormats` that determines the supported data formats.
*/ */
properties[PROP_FORMATS] = properties[PROP_FORMATS] =
g_param_spec_boxed ("formats", P_("Formats"), P_("Formats"), g_param_spec_boxed ("formats", P_("Formats"), P_("Formats"),
@ -406,16 +403,16 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
/** /**
* GtkDropTargetAsync::accept: * GtkDropTargetAsync::accept:
* @self: the #GtkDropTargetAsync * @self: the `GtkDropTargetAsync`
* @drop: the #GdkDrop * @drop: the #GdkDrop
* *
* The ::accept signal is emitted on the drop site when a drop operation * Emitted on the drop site when a drop operation is about to begin.
* is about to begin.
* *
* If the drop is not accepted, %FALSE will be returned and the drop target * If the drop is not accepted, %FALSE will be returned and the drop target
* will ignore the drop. If %TRUE is returned, the drop is accepted for now * will ignore the drop. If %TRUE is returned, the drop is accepted for now
* but may be rejected later via a call to gtk_drop_target_async_reject() or * but may be rejected later via a call to [method@Gtk.DropTargetAsync.reject_drop]
* ultimately by returning %FALSE from #GtkDropTargetAsync::drop. * or ultimately by returning %FALSE from a [signal@Gtk.DropTargetAsync::drop]
* handler.
* *
* The default handler for this signal decides whether to accept the drop * The default handler for this signal decides whether to accept the drop
* based on the formats provided by the @drop. * based on the formats provided by the @drop.
@ -423,7 +420,7 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
* If the decision whether the drop will be accepted or rejected needs * If the decision whether the drop will be accepted or rejected needs
* further processing, such as inspecting the data, this function should * further processing, such as inspecting the data, this function should
* return %TRUE and proceed as is @drop was accepted and if it decides to * return %TRUE and proceed as is @drop was accepted and if it decides to
* reject the drop later, it should call gtk_drop_target_async_reject_drop(). * reject the drop later, it should call [method@Gtk.DropTargetAsync.reject_drop].
* *
* Returns: %TRUE if @drop is accepted * Returns: %TRUE if @drop is accepted
*/ */
@ -439,15 +436,16 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
/** /**
* GtkDropTargetAsync::drag-enter: * GtkDropTargetAsync::drag-enter:
* @self: the #GtkDropTargetAsync * @self: the `GtkDropTargetAsync`
* @drop: the #GdkDrop * @drop: the #GdkDrop
* @x: the x coordinate of the current pointer position * @x: the x coordinate of the current pointer position
* @y: the y coordinate of the current pointer position * @y: the y coordinate of the current pointer position
* *
* The ::drag-enter signal is emitted on the drop site when the pointer * Emitted on the drop site when the pointer enters the widget.
* enters the widget. It can be used to set up custom highlighting.
* *
* Returns: Preferred action for this drag operation. * It can be used to set up custom highlighting.
*
* Returns: Preferred action for this drag operation.
*/ */
signals[DRAG_ENTER] = signals[DRAG_ENTER] =
g_signal_new (I_("drag-enter"), g_signal_new (I_("drag-enter"),
@ -461,15 +459,14 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
/** /**
* GtkDropTargetAsync::drag-motion: * GtkDropTargetAsync::drag-motion:
* @self: the #GtkDropTargetAsync * @self: the `GtkDropTargetAsync`
* @drop: the #GdkDrop * @drop: the #GdkDrop
* @x: the x coordinate of the current pointer position * @x: the x coordinate of the current pointer position
* @y: the y coordinate of the current pointer position * @y: the y coordinate of the current pointer position
* *
* The ::drag-motion signal is emitted while the pointer is moving * Emitted while the pointer is moving over the drop target.
* over the drop target.
* *
* Returns: Preferred action for this drag operation. * Returns: Preferred action for this drag operation.
*/ */
signals[DRAG_MOTION] = signals[DRAG_MOTION] =
g_signal_new (I_("drag-motion"), g_signal_new (I_("drag-motion"),
@ -483,12 +480,13 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
/** /**
* GtkDropTargetAsync::drag-leave: * GtkDropTargetAsync::drag-leave:
* @self: the #GtkDropTargetAsync * @self: the `GtkDropTargetAsync`
* @drop: the #GdkDrop * @drop: the #GdkDrop
* *
* The ::drag-leave signal is emitted on the drop site when the pointer * Emitted on the drop site when the pointer leaves the widget.
* leaves the widget. Its main purpose it to undo things done in *
* #GtkDropTargetAsync::drag-enter. * Its main purpose it to undo things done in
* `GtkDropTargetAsync`::drag-enter.
*/ */
signals[DRAG_LEAVE] = signals[DRAG_LEAVE] =
g_signal_new (I_("drag-leave"), g_signal_new (I_("drag-leave"),
@ -502,23 +500,25 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
/** /**
* GtkDropTargetAsync::drop: * GtkDropTargetAsync::drop:
* @self: the #GtkDropTargetAsync * @self: the `GtkDropTargetAsync`
* @drop: the #GdkDrop * @drop: the #GdkDrop
* @x: the x coordinate of the current pointer position * @x: the x coordinate of the current pointer position
* @y: the y coordinate of the current pointer position * @y: the y coordinate of the current pointer position
* *
* The ::drop signal is emitted on the drop site when the user drops * Emitted on the drop site when the user drops the data onto the widget.
* the data onto the widget. The signal handler must determine whether *
* the pointer position is in a drop zone or not. If it is not in a drop * The signal handler must determine whether the pointer position is in a
* zone, it returns %FALSE and no further processing is necessary. * drop zone or not. If it is not in a drop zone, it returns %FALSE and no
* further processing is necessary.
* *
* Otherwise, the handler returns %TRUE. In this case, this handler will * Otherwise, the handler returns %TRUE. In this case, this handler will
* accept the drop. The handler must ensure that gdk_drop_finish() is * accept the drop. The handler must ensure that [method@Gdk.Drop.finish]
* called to let the source know that the drop is done. The call to * is called to let the source know that the drop is done. The call to
* gdk_drop_finish() must only be done when all data has been received. * [method@Gdk.Drop.finish] must only be done when all data has been received.
* *
* To receive the data, use one of the read functions provides by #GdkDrop * To receive the data, use one of the read functions provided by
* such as gdk_drop_read_async() or gdk_drop_read_value_async(). * [class@Gdk.Drop] such as [method@Gdk.Drop.read_async] or
* [method@Gdk.Drop.read_value_async].
* *
* Returns: whether the drop is accepted at the given pointer position * Returns: whether the drop is accepted at the given pointer position
*/ */
@ -543,9 +543,9 @@ gtk_drop_target_async_init (GtkDropTargetAsync *self)
* @formats: (nullable) (transfer full): the supported data formats * @formats: (nullable) (transfer full): the supported data formats
* @actions: the supported actions * @actions: the supported actions
* *
* Creates a new #GtkDropTargetAsync object. * Creates a new `GtkDropTargetAsync` object.
* *
* Returns: the new #GtkDropTargetAsync * Returns: the new `GtkDropTargetAsync`
*/ */
GtkDropTargetAsync * GtkDropTargetAsync *
gtk_drop_target_async_new (GdkContentFormats *formats, gtk_drop_target_async_new (GdkContentFormats *formats,
@ -564,8 +564,8 @@ gtk_drop_target_async_new (GdkContentFormats *formats,
} }
/** /**
* gtk_drop_target_async_set_formats: * gtk_drop_target_async_set_formats: (attributes org.gtk.Method.set_property=formats)
* @self: a #GtkDropTargetAsync * @self: a `GtkDropTargetAsync`
* @formats: (nullable): the supported data formats or %NULL for * @formats: (nullable): the supported data formats or %NULL for
* any format. * any format.
* *
@ -592,8 +592,8 @@ gtk_drop_target_async_set_formats (GtkDropTargetAsync *self,
} }
/** /**
* gtk_drop_target_async_get_formats: * gtk_drop_target_async_get_formats: (attributes org.gtk.Method.get_property=formats)
* @self: a #GtkDropTargetAsync * @self: a `GtkDropTargetAsync`
* *
* Gets the data formats that this drop target accepts. * Gets the data formats that this drop target accepts.
* *
@ -610,8 +610,8 @@ gtk_drop_target_async_get_formats (GtkDropTargetAsync *self)
} }
/** /**
* gtk_drop_target_async_set_actions: * gtk_drop_target_async_set_actions: (attributes org.gtk.Method.set_property=actions)
* @self: a #GtkDropTargetAsync * @self: a `GtkDropTargetAsync`
* @actions: the supported actions * @actions: the supported actions
* *
* Sets the actions that this drop target supports. * Sets the actions that this drop target supports.
@ -631,8 +631,8 @@ gtk_drop_target_async_set_actions (GtkDropTargetAsync *self,
} }
/** /**
* gtk_drop_target_async_get_actions: * gtk_drop_target_async_get_actions: (attributes org.gtk.Method.get_property=actions)
* @self: a #GtkDropTargetAsync * @self: a `GtkDropTargetAsync`
* *
* Gets the actions that this drop target supports. * Gets the actions that this drop target supports.
* *
@ -648,7 +648,7 @@ gtk_drop_target_async_get_actions (GtkDropTargetAsync *self)
/** /**
* gtk_drop_target_async_reject_drop: * gtk_drop_target_async_reject_drop:
* @self: a #GtkDropTargetAsync * @self: a `GtkDropTargetAsync`
* @drop: the #GdkDrop of an ongoing drag operation * @drop: the #GdkDrop of an ongoing drag operation
* *
* Sets the @drop as not accepted on this drag site. * Sets the @drop as not accepted on this drag site.