Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkdnd.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Drag and Drop
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Functions for controlling drag and drop handling.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 GTK+ has a rich set of functions for doing inter-process
  10 communication via the drag-and-drop metaphore. GTK+
  11 can do drag and drop (DND) via multiple protocols.
  12 The currently supported protocols are the Xdnd and
  13 Motif protocols.
  14
  15 As well as the functions listed here, applications
  16 may need to use some facilities provided for
  17 <link linkend="gtk-Selections">Selections</link>.
  18 Also, the Drag and Drop API makes use of signals
  19 in the #GtkWidget class.
  20 </para>
  21
  22 <!-- ##### SECTION See_Also ##### -->
  23 <para>
  24
  25 </para>
  26
  27 <!-- ##### ENUM GtkDestDefaults ##### -->
  28 <para>
  29 The #GtkDestfaults enumeration specifies the various
  30 types of action that will be taken on behalf
  31 of the user for a drag destination site.
  32 </para>
  33 <informaltable pgwide=1 frame="none" role="enum">
  34 <tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
  35 <tbody>
  36
  37 <row>
  38 <entry><symbol>GTK_DEST_DEFAULT_MOTION</symbol></entry>
  39 <entry>
  40    If set for a widget, GTK+, during a drag over this
  41    widget will check if the drag matches this widget's
  42    list of possible targets and actions.
  43    GTK+ will then call gtk_drag_status() as appropriate.
  44 </entry>
  45 </row>
  46
  47 <row>
  48 <entry><symbol>GTK_DEST_DEFAULT_HIGHLIGHT</symbol></entry>
  49 <entry>
  50    If set for a widget, GTK+ will draw a highlight on
  51    this widget as long as a drag is over this widget
  52    and the wiget drag format and action is accetable.</entry>
  53 </row>
  54
  55 <row>
  56 <entry><symbol>GTK_DEST_DEFAULT_DROP</symbol></entry>
  57 <entry>
  58    If set for a widget, when a drop occurs, GTK+ will
  59    will check if the drag matches this widget's
  60    list of possible targets and actions. If so,
  61    GTK+ will call gtk_drag_data_get() on behalf
  62    of the widget. Whether or not the drop is succesful,
  63    GTK+ will call gtk_drag_finish(). If the action
  64    was a move, then if the drag was succesful, then
  65    %TRUE will be passed for the @delete parameter
  66    to gtk_drag_finish().
  67 </entry>
  68 </row>
  69
  70 <row>
  71 <entry><symbol>GTK_DEST_DEFAULT_ALL</symbol></entry>
  72 <entry>
  73    If set, specifies that all default actions should
  74    be taken.
  75 </entry>
  76 </row>
  77
  78 </tbody></tgroup></informaltable>
  79
  80 @GTK_DEST_DEFAULT_MOTION:
  81 @GTK_DEST_DEFAULT_HIGHLIGHT:
  82 @GTK_DEST_DEFAULT_DROP:
  83 @GTK_DEST_DEFAULT_ALL:
  84
  85 <!-- ##### ENUM GtkTargetFlags ##### -->
  86 <para>
  87 The #GtkTargetFlags enumeration is used to specifies
  88 constraints on an entry in a GtkTargetTable.
  89 <variablelist>
  90  <varlistentry><term> %GTK_TARGET_SAME_APP </term>
  91  <listitem>
  92    <para>
  93    If this is set, the target will only be selected
  94    for drags within a single application.
  95    </para>
  96  </listitem>
  97  </varlistentry>
  98  <varlistentry><term> %GTK_TARGET_SAME_WIDGET </term>
  99  <listitem>
 100    <para>
 101    If this is set, the target will only be selected
 102    for drags within a single widget.
 103    </para>
 104  </listitem>
 105  </varlistentry>
 106 </variablelist>
 107
 108 @GTK_TARGET_SAME_APP:
 109 @GTK_TARGET_SAME_WIDGET:
 110
 111 <!-- ##### FUNCTION gtk_drag_dest_set ##### -->
 112 <para>
 113 Set a widget as a potential drop destination.
 114 </para>
 115
 116 @widget: a widget
 117 @flags: the flags that specify what actions GTK+ should take
 118  on behalf of a widget for drops onto that widget. The @targets
 119  and @actions fields only are used if %GTK_DEST_DEFAULT_MOTION
 120  or %GTK_DEST_DEFAULT_DROP are given.
 121 @targets: a pointer to an array of #GtkTargetEntry indicating
 122  the drop types that this widget will accept.
 123 @n_targets: the number of entries in @targets.
 124 @actions: a bitmask of possible actions for a drop onto this
 125  widget.
 126
 127
 128 <!-- ##### FUNCTION gtk_drag_dest_set_proxy ##### -->
 129 <para>
 130 Set this widget as a proxy for drops to another window.
 131 </para>
 132
 133 @widget: a #GtkWidget
 134 @proxy_window: the window to which to forward drag events
 135 @protocol: the drag protocol which the @proxy_window accepts
 136            (You can use gdk_drag_get_protocol() to determine this)
 137 @use_coordinates: If true, send the same coordinates to the
 138                   destination, because it is a embedded
 139                   subwindow.
 140
 141
 142 <!-- ##### FUNCTION gtk_drag_dest_unset ##### -->
 143 <para>
 144 Clear information about a drop destination set with
 145 gtk_drag_dest_set(). The widget will no longer receive
 146 notification of drags.
 147 </para>
 148
 149 @widget: a #GtkWidget
 150
 151
 152 <!-- ##### FUNCTION gtk_drag_finish ##### -->
 153 <para>
 154 Inform the drag source that the drop is finished, and
 155 that the data of the drag will no longer be required.
 156 </para>
 157
 158 @context: the drag context.
 159 @success: a flag indicating whether the drop was succesful
 160 @del: a flag indicating whether the source should delete the
 161       original data. (This should be %TRUE for a move)
 162 @time: the timestamp from the "drag_data_drop" signal.
 163
 164
 165 <!-- ##### FUNCTION gtk_drag_get_data ##### -->
 166 <para>
 167 Get the data associated with a drag. When the data
 168 is received or the retrieval fails, GTK+ will emit a
 169 "drag_data_received" signal. Failure of the retrieval
 170 is indicated by the length field of the @selection_data
 171 signal parameter being negative. However, when gtk_drag_get_data()
 172 is called implicitely because the %GTK_DRAG_DEFAULT_DROP was set,
 173 then the widget will not receive notification of failed
 174 drops.
 175 </para>
 176
 177 @widget: the widget that will receive the "drag_data_received"
 178  signal.
 179 @context: the drag context
 180 @target: the target (form of the data) to retrieve.
 181 @time: a timestamp for retrieving the data. This will
 182        generally be the time received in a "drag_data_motion"
 183        or "drag_data_drop" signal.
 184
 185
 186 <!-- ##### FUNCTION gtk_drag_get_source_widget ##### -->
 187 <para>
 188 Determine the source widget for a drag.
 189 </para>
 190
 191 @context: a (destination side) drag context.
 192 @Returns: if the drag is occurring within a single application,
 193           a pointer to the source widget. Otherwise, NULL.
 194
 195
 196 <!-- ##### FUNCTION gtk_drag_highlight ##### -->
 197 <para>
 198 Draw a highlight around a widget. This will attach
 199 handlers to  "expose_event" and "draw", so the highlight
 200 will continue to be displayed until gtk_drag_unhighlight
 201 is called.
 202 </para>
 203
 204 @widget: a widget to highlight
 205
 206
 207 <!-- ##### FUNCTION gtk_drag_unhighlight ##### -->
 208 <para>
 209 Remove a highlight set by gtk_drag_highlight() from
 210 a widget.
 211 is called.
 212 </para>
 213
 214 @widget: a widget to remove the highlight from.
 215
 216
 217 <!-- ##### FUNCTION gtk_drag_begin ##### -->
 218 <para>
 219 Initiate a drag on the source side. The function
 220 only needs to be used when the application is
 221 starting drags itself, and is not needed when
 222 gtk_drag_source_set() is used.
 223 </para>
 224
 225 @widget: the source widget.
 226 @targets: The targets (data formats) in which the
 227  source can provide the data.
 228 @actions: A bitmask of the allowed drag actions for this
 229           drag.
 230 @button: The button the user clicked to start the drag.
 231 @event: The event that triggered the start of the
 232         drag. Usually
 233 @Returns: The context for this drag.
 234
 235
 236 <!-- ##### FUNCTION gtk_drag_set_icon_widget ##### -->
 237 <para>
 238 Change the icon for a widget to a given widget. GTK+
 239 will not destroy the icon, so if you don't want
 240 it to persist, you should connect to the "drag_end"
 241 signal and destroy it yourself.
 242 </para>
 243
 244 @context: the context for a drag. (This must be called
 245           with a  context for the source side of a drag)
 246 @widget: A toplevel window to use as an icon.
 247 @hot_x: The X offset within @widget of the hotspot.
 248 @hot_y: The Y offset within @widget of the hotspot.
 249
 250
 251 <!-- ##### FUNCTION gtk_drag_set_icon_pixmap ##### -->
 252 <para>
 253 Sets a given pixmap as the icon for a given drag.
 254 GTK+ retains a reference count for the arguments, and
 255 will release them when they are no longer needed.
 256 </para>
 257
 258 @context: the context for a drag. (This must be called
 259           with a  context for the source side of a drag)
 260 @colormap: the colormap of the icon
 261 @pixmap: the image data for the icon
 262 @mask: the transparency mask for an image.
 263 @hot_x: The X offset within @widget of the hotspot.
 264 @hot_y: The Y offset within @widget of the hotspot.
 265
 266
 267 <!-- ##### FUNCTION gtk_drag_set_icon_default ##### -->
 268 <para>
 269 Set the icon for a particular drag to the default
 270 icon.
 271 </para>
 272
 273 @context: the context for a drag. (This must be called
 274           with a  context for the source side of a drag)
 275
 276
 277 <!-- ##### FUNCTION gtk_drag_set_default_icon ##### -->
 278 <para>
 279 Change the default drag icon. GTK+ retains a reference count for the
 280 arguments, and will release them when they are no longer needed.
 281 </para>
 282
 283 @colormap: the colormap of the icon
 284 @pixmap: the image data for the icon
 285 @mask: the transparency mask for an image.
 286 @hot_x: The X offset within @widget of the hotspot.
 287 @hot_y: The Y offset within @widget of the hotspot.
 288
 289
 290 <!-- ##### FUNCTION gtk_drag_source_set ##### -->
 291 <para>
 292 Sets up a widget so that GTK+ will start a drag
 293 operation when the user clicks and drags on the
 294 widget. The widget must have a window.
 295 </para>
 296
 297 @widget: a #GtkWidget
 298 @start_button_mask: the bitmask of buttons that can start the drag
 299 @targets: the table of targets that the drag will support
 300 @n_targets: the number of items in @targets
 301 @actions: the bitmask of possible actions for a drag from this
 302  widget.
 303
 304
 305 <!-- ##### FUNCTION gtk_drag_source_set_icon ##### -->
 306 <para>
 307 Sets the icon that will be used for drags from a
 308 particular widget. GTK+ retains a reference count
 309 for the arguments, and will release them when
 310 they are no longer needed.
 311 </para>
 312
 313 @widget: a #GtkWidget
 314 @colormap: the colormap of the icon
 315 @pixmap: the image data for the icon
 316 @mask: the transparency mask for an image.
 317
 318
 319 <!-- ##### FUNCTION gtk_drag_source_unset ##### -->
 320 <para>
 321 Undo the effects of gtk_drag_source_set().
 322 </para>
 323
 324 @widget: a #GtkWidget
 325
 326
 327 <!-- ##### FUNCTION gtk_drag_source_handle_event ##### -->
 328 <para>
 329 Internal function.
 330 </para>
 331
 332 @widget:
 333 @event:
 334
 335
 336 <!-- ##### FUNCTION gtk_drag_dest_handle_event ##### -->
 337 <para>
 338 Internal function.
 339 </para>
 340
 341 @toplevel:
 342 @event:
 343
 344