From 917f5c12722225f12c4f81c5aeacec7d20ae83b3 Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Fri, 23 Jul 2010 11:51:23 -0500 Subject: [PATCH] Clarify what the @event is used for when calling gtk_drag_begin() Signed-off-by: Federico Mena Quintero --- gtk/gtkdnd.c | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/gtk/gtkdnd.c b/gtk/gtkdnd.c index 52d8edaa64..dc9a938309 100644 --- a/gtk/gtkdnd.c +++ b/gtk/gtkdnd.c @@ -2559,6 +2559,29 @@ gtk_drag_begin_internal (GtkWidget *widget, * only needs to be used when the application is * starting drags itself, and is not needed when * gtk_drag_source_set() is used. + * + * The @event is used to retrieve the timestamp that will be used internally to + * grab the pointer. If @event is #NULL, then GDK_CURRENT_TIME will be used. + * However, you should try to pass a real event in all cases, since that can be + * used by GTK+ to get information about the start position of the drag, for + * example if the @event is a GDK_MOTION_NOTIFY. + * + * Generally there are three cases when you want to start a drag by hand by calling + * this function: + * + * 1. During a button-press-event handler, if you want to start a drag immediately + * when the user presses the mouse button. Pass the @event that you have in your + * button-press-event handler. + * + * 2. During a motion-notify-event handler, if you want to start a drag when the mouse + * moves past a certain threshold distance after a button-press. Pass the @event that you + * have in your motion-notify-event handler. + * + * 3. During a timeout handler, if you want to start a drag after the mouse + * button is held down for some time. Try to save the last event that you got + * from the mouse, using gdk_event_copy(), and pass it to this function + * (remember to free the event with gdk_event_free() when you are done). If you + * can really not pass a real event, pass #NULL instead. * * Return value: the context for this drag. **/