From b76940bab5b82914617424a1063c6942e4ad143d Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 11 Jan 2020 00:31:40 -0500 Subject: [PATCH] dragdest: More documentation --- gtk/gtkdragdest.c | 44 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 35 insertions(+), 9 deletions(-) diff --git a/gtk/gtkdragdest.c b/gtk/gtkdragdest.c index 7cf83e5697..a7f32bc1c0 100644 --- a/gtk/gtkdragdest.c +++ b/gtk/gtkdragdest.c @@ -44,8 +44,32 @@ * Drag-and-Drop operations. * * To use a GtkDropTarget to receive drops on a widget, you create - * a GtkDropTarget object, connect to its signals, and then attach + * a GtkDropTarget object, configure which data formats and actions + * you support, connect to its signals, and then attach * it to the widget with gtk_widget_add_controller(). + * + * During a drag operation, the first signal that a GtkDropTarget + * emits is #GtkDropTarget::accept, which is meant to determine + * whether the target is a possible drop site for the ongoing drag. + * The default handler for the ::accept signal accepts the drag + * if it finds a compatible data format an an action that is supported + * on both sides. + * + * If it is, and the widget becomes the current target, you will + * receive a #GtkDropTarget::drag-enter signal, followed by + * #GtkDropTarget::drag-motion signals as the pointer moves, and + * finally either a #GtkDropTarget::drag-leave signal when the pointer + * move off the widget, or a #GtkDropTarget::drag-drop signal when + * a drop happens. + * + * The ::drag-enter and ::drag-motion handler can call gdk_drop_status() + * to update the status of the ongoing operation. The ::drag-drop handler + * should initiate the data transfer and finish the operation by calling + * gdk_drop_finish(). + * + * Between the ::drag-enter and ::drag-leave signals the widget is the + * current drop target, and will receive the %GTK_STATE_FLAG_DROP_ACTIVE + * state, which can be used to style the widget as a drop targett. */ struct _GtkDropTarget @@ -239,7 +263,7 @@ gtk_drop_target_class_init (GtkDropTargetClass *class) * @drop: the #GdkDrop * * The ::drag-enter signal is emitted on the drop site when the cursor - * enters the widget. + * enters the widget. It can be used to set up custom highlighting. */ signals[DRAG_ENTER] = g_signal_new (I_("drag-enter"), @@ -257,7 +281,8 @@ gtk_drop_target_class_init (GtkDropTargetClass *class) * @drop: the #GdkDrop * * The ::drag-leave signal is emitted on the drop site when the cursor - * leaves the widget. + * leaves the widget. Its main purpose it to undo things done in + * #GtkDropTarget::drag-enter. */ signals[DRAG_LEAVE] = g_signal_new (I_("drag-leave"), @@ -306,11 +331,11 @@ gtk_drop_target_class_init (GtkDropTargetClass *class) * based on the type of the data. * * If the decision whether the drop will be accepted or rejected can't be - * made based solely on the cursor position and the type of the data, the - * handler may inspect the dragged data by calling one of the #GdkDrop - * read functions and return %TRUE to tentatively accept the drop. When - * the data arrives and will nto be accepted, a call to - * gtk_drop_target_deny_drop() should be made to reject the drop. + * made based solely the data format, handler may inspect the dragged data + * by calling one of the #GdkDrop read functions and return %TRUE to + * tentatively accept the drop. When the data arrives and is found to not be + * acceptable, a call to gtk_drop_target_deny_drop() should be made to reject + * the drop. * * Returns: whether the cursor position is in a drop zone */ @@ -521,7 +546,8 @@ gtk_drop_target_match (GtkDropTarget *dest, * @dest: a #GtkDropTarget * * Returns a mimetype that is supported both by @dest and the ongoing - * drag. + * drag. For more detailed control, you can use gdk_drop_get_formats() + * to obtain the content formats that are supported by the source. * * Returns: (nullable): a matching mimetype for the ongoing drag, or %NULL */