AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-09-20 05:50:11 +00:00
Code Issues Projects Releases Wiki Activity

Mention impact of GtkDestDefaults on "drag-motion" handlers. Clearify

Browse Source 
* 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:
Mathias Hasselmann 2007-12-11 18:56:56 +00:00
parent c1387f9cea
commit dce782750f
3 changed files with 55 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
ChangeLog
View File

@ -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
View File

@ -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;

36
gtk/gtkwidget.c
View File

@ -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)