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;
* @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.
- *
- * 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 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. 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)
projects / ~andy / gtk / commitdiff