forked from AuroraMiddleware/gtk
dc754528a0
Mon Oct 22 14:08:26 2001 Jonathan Blandford <jrb@redhat.com> * demos/gtk-demo/appwindow.c: Remove handle_box from App demo. * gtk/gtktreeview.c (size_allocate): Move to a different drawing system. Instead of having a window the size of the tree, we have a window the size of widget->allocation, and simply draw with the offset. (coords_are_over_arrow): ditto. Move to window coordinates. (do_prelight): ditto (do_unprelight): ditto * gtk/gtktreemodelsort.c (gtk_tree_model_sort_rows_reordered): Minor fix from Kristian Rietveld to fix unsorted case.
392 lines
8.7 KiB
Plaintext
392 lines
8.7 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
Drag and Drop
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
Functions for controlling drag and drop handling.
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
GTK+ has a rich set of functions for doing inter-process
|
|
communication via the drag-and-drop metaphor. GTK+
|
|
can do drag-and-drop (DND) via multiple protocols.
|
|
The currently supported protocols are the Xdnd and
|
|
Motif protocols.
|
|
|
|
As well as the functions listed here, applications
|
|
may need to use some facilities provided for
|
|
<link linkend="gtk-Selections">Selections</link>.
|
|
Also, the Drag and Drop API makes use of signals
|
|
in the #GtkWidget class.
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ENUM GtkDestDefaults ##### -->
|
|
<para>
|
|
The #GtkDestfaults enumeration specifies the various
|
|
types of action that will be taken on behalf
|
|
of the user for a drag destination site.
|
|
</para>
|
|
<informaltable pgwide=1 frame="none" role="enum">
|
|
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
|
|
<tbody>
|
|
|
|
<row>
|
|
<entry><symbol>GTK_DEST_DEFAULT_MOTION</symbol></entry>
|
|
<entry>
|
|
If set for a widget, GTK+, during a drag over this
|
|
widget will check if the drag matches this widget's
|
|
list of possible targets and actions.
|
|
GTK+ will then call gtk_drag_status() as appropriate.
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><symbol>GTK_DEST_DEFAULT_HIGHLIGHT</symbol></entry>
|
|
<entry>
|
|
If set for a widget, GTK+ will draw a highlight on
|
|
this widget as long as a drag is over this widget
|
|
and the widget drag format and action are acceptable.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><symbol>GTK_DEST_DEFAULT_DROP</symbol></entry>
|
|
<entry>
|
|
If set for a widget, when a drop occurs, GTK+ will
|
|
will check if the drag matches this widget's
|
|
list of possible targets and actions. If so,
|
|
GTK+ will call gtk_drag_data_get() on behalf
|
|
of the widget. Whether or not the drop is successful,
|
|
GTK+ will call gtk_drag_finish(). If the action
|
|
was a move, then if the drag was successful, then
|
|
%TRUE will be passed for the @delete parameter
|
|
to gtk_drag_finish().
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><symbol>GTK_DEST_DEFAULT_ALL</symbol></entry>
|
|
<entry>
|
|
If set, specifies that all default actions should
|
|
be taken.
|
|
</entry>
|
|
</row>
|
|
|
|
</tbody></tgroup></informaltable>
|
|
|
|
@GTK_DEST_DEFAULT_MOTION:
|
|
@GTK_DEST_DEFAULT_HIGHLIGHT:
|
|
@GTK_DEST_DEFAULT_DROP:
|
|
@GTK_DEST_DEFAULT_ALL:
|
|
|
|
<!-- ##### ENUM GtkTargetFlags ##### -->
|
|
<para>
|
|
The #GtkTargetFlags enumeration is used to specify
|
|
constraints on an entry in a #GtkTargetTable.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry><term> %GTK_TARGET_SAME_APP </term>
|
|
<listitem>
|
|
<para>
|
|
If this is set, the target will only be selected
|
|
for drags within a single application.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term> %GTK_TARGET_SAME_WIDGET </term>
|
|
<listitem>
|
|
<para>
|
|
If this is set, the target will only be selected
|
|
for drags within a single widget.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
@GTK_TARGET_SAME_APP:
|
|
@GTK_TARGET_SAME_WIDGET:
|
|
|
|
<!-- ##### FUNCTION gtk_drag_dest_set ##### -->
|
|
<para>
|
|
Sets a widget as a potential drop destination.
|
|
</para>
|
|
|
|
@widget: a #GtkWidget
|
|
@flags: the flags that specify what actions GTK+ should take
|
|
on behalf of a widget for drops onto that widget. The @targets
|
|
and @actions fields only are used if %GTK_DEST_DEFAULT_MOTION
|
|
or %GTK_DEST_DEFAULT_DROP are given.
|
|
@targets: a pointer to an array of #GtkTargetEntry 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.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_dest_set_proxy ##### -->
|
|
<para>
|
|
Sets this widget as a proxy for drops to another window.
|
|
</para>
|
|
|
|
@widget: a #GtkWidget
|
|
@proxy_window: the window to which to forward drag events
|
|
@protocol: the drag protocol which the @proxy_window accepts
|
|
(You can use gdk_drag_get_protocol() to determine this)
|
|
@use_coordinates: If true, send the same coordinates to the
|
|
destination, because it is an embedded
|
|
subwindow.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_dest_unset ##### -->
|
|
<para>
|
|
Clears information about a drop destination set with
|
|
gtk_drag_dest_set(). The widget will no longer receive
|
|
notification of drags.
|
|
</para>
|
|
|
|
@widget: a #GtkWidget
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_dest_find_target ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@widget:
|
|
@context:
|
|
@target_list:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_dest_get_target_list ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@widget:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_dest_set_target_list ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@widget:
|
|
@target_list:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_finish ##### -->
|
|
<para>
|
|
Informs the drag source that the drop is finished, and
|
|
that the data of the drag will no longer be required.
|
|
</para>
|
|
|
|
@context: the drag context.
|
|
@success: a flag indicating whether the drop was successful
|
|
@del: a flag indicating whether the source should delete the
|
|
original data. (This should be %TRUE for a move)
|
|
@time: the timestamp from the "drag_data_drop" signal.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_get_data ##### -->
|
|
<para>
|
|
Get the data associated with a drag. When the data
|
|
is received or the retrieval fails, GTK+ will emit a
|
|
"drag_data_received" signal. Failure of the retrieval
|
|
is indicated by the length field of the @selection_data
|
|
signal parameter being negative. However, when gtk_drag_get_data()
|
|
is called implicitely because the %GTK_DRAG_DEFAULT_DROP was set,
|
|
then the widget will not receive notification of failed
|
|
drops.
|
|
</para>
|
|
|
|
@widget: the widget that will receive the "drag_data_received"
|
|
signal.
|
|
@context: the drag context
|
|
@target: the target (form of the data) to retrieve.
|
|
@time: a timestamp for retrieving the data. This will
|
|
generally be the time received in a "drag_data_motion"
|
|
or "drag_data_drop" signal.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_get_source_widget ##### -->
|
|
<para>
|
|
Determines the source widget for a drag.
|
|
</para>
|
|
|
|
@context: a (destination side) drag context.
|
|
@Returns: if the drag is occurring within a single application,
|
|
a pointer to the source widget. Otherwise, %NULL.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_highlight ##### -->
|
|
<para>
|
|
Draws a highlight around a widget. This will attach
|
|
handlers to "expose_event" and "draw", so the highlight
|
|
will continue to be displayed until gtk_drag_unhighlight()
|
|
is called.
|
|
</para>
|
|
|
|
@widget: a widget to highlight
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_unhighlight ##### -->
|
|
<para>
|
|
Removes a highlight set by gtk_drag_highlight() from
|
|
a widget.
|
|
</para>
|
|
|
|
@widget: a widget to remove the highlight from.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_begin ##### -->
|
|
<para>
|
|
Initiates a drag on the source side. The function
|
|
only needs to be used when the application is
|
|
starting drags itself, and is not needed when
|
|
gtk_drag_source_set() is used.
|
|
</para>
|
|
|
|
@widget: the source widget.
|
|
@targets: The targets (data formats) in which the
|
|
source can provide the data.
|
|
@actions: A bitmask of the allowed drag actions for this
|
|
drag.
|
|
@button: The button the user clicked to start the drag.
|
|
@event: The event that triggered the start of the
|
|
drag.
|
|
@Returns: The context for this drag.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_set_icon_widget ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@context:
|
|
@widget:
|
|
@hot_x:
|
|
@hot_y:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_set_icon_pixmap ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@context:
|
|
@colormap:
|
|
@pixmap:
|
|
@mask:
|
|
@hot_x:
|
|
@hot_y:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_set_icon_pixbuf ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@context:
|
|
@pixbuf:
|
|
@hot_x:
|
|
@hot_y:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_set_icon_stock ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@context:
|
|
@stock_id:
|
|
@hot_x:
|
|
@hot_y:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_set_icon_default ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@context:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_set_default_icon ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@colormap:
|
|
@pixmap:
|
|
@mask:
|
|
@hot_x:
|
|
@hot_y:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_check_threshold ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@widget:
|
|
@start_x:
|
|
@start_y:
|
|
@current_x:
|
|
@current_y:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_source_set ##### -->
|
|
<para>
|
|
Sets up a widget so that GTK+ will start a drag
|
|
operation when the user clicks and drags on the
|
|
widget. The widget must have a window.
|
|
</para>
|
|
|
|
@widget: a #GtkWidget
|
|
@start_button_mask: the bitmask of buttons that can start the drag
|
|
@targets: the table of targets that the drag will support
|
|
@n_targets: the number of items in @targets
|
|
@actions: the bitmask of possible actions for a drag from this
|
|
widget.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_source_set_icon ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@widget:
|
|
@colormap:
|
|
@pixmap:
|
|
@mask:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_source_set_icon_pixbuf ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@widget:
|
|
@pixbuf:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_source_set_icon_stock ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@widget:
|
|
@stock_id:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drag_source_unset ##### -->
|
|
<para>
|
|
Undoes the effects of gtk_drag_source_set().
|
|
</para>
|
|
|
|
@widget: a #GtkWidget
|
|
|
|
|