[gtk+/gtk-2-22] Clarify what the @event is used for when calling gtk_drag_begin()

[Federico Mena Quintero <federico src gnome org>]

commit 05e2004eb637296acd6cbea0ee9c07a74dff558e
Author: Federico Mena Quintero <federico novell com>
Date:   Fri Jul 23 11:51:23 2010 -0500

    Clarify what the @event is used for when calling gtk_drag_begin()
    
    Signed-off-by: Federico Mena Quintero <federico novell com>

 gtk/gtkdnd.c |   23 +++++++++++++++++++++++
 1 files changed, 23 insertions(+), 0 deletions(-)
---
diff --git a/gtk/gtkdnd.c b/gtk/gtkdnd.c
index 0859c45..d14c66b 100644
--- a/gtk/gtkdnd.c
+++ b/gtk/gtkdnd.c
@@ -2510,6 +2510,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.
  **/