diff --git a/ChangeLog b/ChangeLog index dab64dff69..185b94e544 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2007-12-11 Mathias Hasselmann + + * gtk/gtkdnd.c, gtk/gtkwidget.c: Mention impact of GtkDestDefaults + on "drag-motion" handlers. Clearify documentation for + gtk_drag_dest_set. + 2007-12-11 15:44:01 Tim Janik * buildertest.c: made unnecessarily exported symbols static. diff --git a/gtk/gtkdnd.c b/gtk/gtkdnd.c index 4294412f6f..c7ca16d683 100644 --- a/gtk/gtkdnd.c +++ b/gtk/gtkdnd.c @@ -1071,26 +1071,37 @@ gtk_drag_dest_set_internal (GtkWidget *widget, g_object_set_data_full (G_OBJECT (widget), I_("gtk-drag-dest"), site, gtk_drag_dest_site_destroy); } - -/************************************************************* +/** * gtk_drag_dest_set: - * Register a drop site, and possibly add default behaviors. - * arguments: - * widget: - * flags: Which types of default drag behavior to use - * targets: Table of targets that can be accepted - * n_targets: Number of of entries in targets - * actions: - * results: - *************************************************************/ - -void -gtk_drag_dest_set (GtkWidget *widget, - GtkDestDefaults flags, - const GtkTargetEntry *targets, - gint n_targets, - GdkDragAction actions) + * @widget: a #GtkWidget + * @flags: which types of default drag behavior to use + * @targets: a pointer to an array of #GtkTargetEntrys indicating + * the drop types that this @widget will accept. + * @n_targets: the number of entries in @targets. + * @actions: a bitmask of possible actions for a drop onto this @widget. + * + * Sets a widget as a potential drop destination, and adds default behaviors. + * + * The default behaviors listed in @flags have an effect similar + * to installing default handlers for the widget's drag-and-drop signals + * (#GtkWidget:drag-motion, #GtkWidget:drag-drop, ...). They are exist for + * convenience, but have to be selected carefully as some of those default + * behaviors make assumptions, that can conflict with your own signal handlers. + * For instance the default behaviors implied by #GTK_DEST_DEFAULT_DROP, + * #GTK_DEST_DEFAULT_MOTION and #GTK_DEST_DEFAULT_ALL, use #gdk_drag_status + * and gtk_drag_finish() in a way that conflicts with #GtkWidget:drag-motion + * handlers calling gtk_drag_get_data() to inspect the dragged data. + * + * The list of @targets can be retrieved with gtk_drag_dest_get_target_list(), + * or gtk_drag_dest_find_target(). + */ +void +gtk_drag_dest_set (GtkWidget *widget, + GtkDestDefaults flags, + const GtkTargetEntry *targets, + gint n_targets, + GdkDragAction actions) { GtkDragDestSite *site; diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c index ca8d968f7d..b457e51ed5 100644 --- a/gtk/gtkwidget.c +++ b/gtk/gtkwidget.c @@ -1658,27 +1658,31 @@ gtk_widget_class_init (GtkWidgetClass *klass) * @time: the timestamp of the motion event * @returns: whether the cursor position is in a drop zone * - * The ::drag-motion signal is emitted on the drop site when the user - * moves the cursor over the widget during a drag. The signal handler - * must determine whether the cursor position is in a 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, the - * handler is responsible for providing the necessary information for - * displaying feedback to the user, by calling gdk_drag_status(). 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 gtk_drag_get_data() and defer the - * gdk_drag_status() call to the #GtkWidget::drag-data-received handler. + * The drag-motion signal is emitted on the drop site when the user + * moves the cursor over the widget during a drag. The signal handler + * must determine whether the cursor position is in a 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, the + * handler is responsible for providing the necessary information for + * displaying feedback to the user, by calling gdk_drag_status(). * - * Note that there is no drag-enter signal. The drag receiver has to keep - * track of whether he has received any drag-motion signals since the last - * #GtkWidget::drag-leave and if not, treat the drag-motion signal as an - * "enter" signal. Upon an "enter", the handler will typically highlight + * 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 gtk_drag_get_data() and + * defer the gdk_drag_status() call to the #GtkWidget::drag-data-received + * handler. Note that you cannot not pass #GTK_DEST_DEFAULT_DROP, + * #GTK_DEST_DEFAULT_MOTION or #GTK_DEST_DEFAULT_ALL to gtk_drag_dest_set() + * when using the drag-motion signal that way. + * + * Also note that there is no drag-enter signal. The drag receiver has to + * keep track of whether he has received any drag-motion signals since the + * last #GtkWidget::drag-leave and if not, treat the drag-motion signal as + * an "enter" signal. Upon an "enter", the handler will typically highlight * the drop site with gtk_drag_highlight(). * |[ * static void * drag_motion (GtkWidget *widget, - * GdkDragContext *context, + * GdkDragContext *context, * gint x, * gint y, * guint time)