forked from AuroraMiddleware/gtk
Mention impact of GtkDestDefaults on "drag-motion" handlers. Clearify
* gtk/gtkdnd.c, gtk/gtkwidget.c: Mention impact of GtkDestDefaults on "drag-motion" handlers. Clearify documentation for gtk_drag_dest_set. svn path=/trunk/; revision=19159
This commit is contained in:
parent
c1387f9cea
commit
dce782750f
@ -1,3 +1,9 @@
|
||||
2007-12-11 Mathias Hasselmann <mathias@openismus.com>
|
||||
|
||||
* 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 <timj@imendio.com>
|
||||
|
||||
* buildertest.c: made unnecessarily exported symbols static.
|
||||
|
47
gtk/gtkdnd.c
47
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 #GtkTargetEntry<!-- -->s 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;
|
||||
|
||||
|
@ -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)
|
||||
|
Loading…
Reference in New Issue
Block a user