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 </para>
  90 <variablelist>
  91  <varlistentry><term> %GTK_TARGET_SAME_APP </term>
  92  <listitem>
  93    <para>
  94    If this is set, the target will only be selected
  95    for drags within a single application.
  96    </para>
  97  </listitem>
  98  </varlistentry>
  99  <varlistentry><term> %GTK_TARGET_SAME_WIDGET </term>
 100  <listitem>
 101    <para>
 102    If this is set, the target will only be selected
 103    for drags within a single widget.
 104    </para>
 105  </listitem>
 106  </varlistentry>
 107 </variablelist>
 108
 109 @GTK_TARGET_SAME_APP:
 110 @GTK_TARGET_SAME_WIDGET:
 111
 112 <!-- ##### FUNCTION gtk_drag_dest_set ##### -->
 113 <para>
 114 Set a widget as a potential drop destination.
 115 </para>
 116
 117 @widget: a widget
 118 @flags: the flags that specify what actions GTK+ should take
 119  on behalf of a widget for drops onto that widget. The @targets
 120  and @actions fields only are used if %GTK_DEST_DEFAULT_MOTION
 121  or %GTK_DEST_DEFAULT_DROP are given.
 122 @targets: a pointer to an array of #GtkTargetEntry indicating
 123  the drop types that this widget will accept.
 124 @n_targets: the number of entries in @targets.
 125 @actions: a bitmask of possible actions for a drop onto this
 126  widget.
 127
 128
 129 <!-- ##### FUNCTION gtk_drag_dest_set_proxy ##### -->
 130 <para>
 131 Set this widget as a proxy for drops to another window.
 132 </para>
 133
 134 @widget: a #GtkWidget
 135 @proxy_window: the window to which to forward drag events
 136 @protocol: the drag protocol which the @proxy_window accepts
 137            (You can use gdk_drag_get_protocol() to determine this)
 138 @use_coordinates: If true, send the same coordinates to the
 139                   destination, because it is a embedded
 140                   subwindow.
 141
 142
 143 <!-- ##### FUNCTION gtk_drag_dest_unset ##### -->
 144 <para>
 145 Clear information about a drop destination set with
 146 gtk_drag_dest_set(). The widget will no longer receive
 147 notification of drags.
 148 </para>
 149
 150 @widget: a #GtkWidget
 151
 152
 153 <!-- ##### FUNCTION gtk_drag_dest_find_target ##### -->
 154 <para>
 155
 156 </para>
 157
 158 @widget:
 159 @context:
 160 @target_list:
 161 @Returns:
 162
 163
 164 <!-- ##### FUNCTION gtk_drag_dest_get_target_list ##### -->
 165 <para>
 166
 167 </para>
 168
 169 @widget:
 170 @Returns:
 171
 172
 173 <!-- ##### FUNCTION gtk_drag_dest_set_target_list ##### -->
 174 <para>
 175
 176 </para>
 177
 178 @widget:
 179 @target_list:
 180
 181
 182 <!-- ##### FUNCTION gtk_drag_finish ##### -->
 183 <para>
 184 Inform the drag source that the drop is finished, and
 185 that the data of the drag will no longer be required.
 186 </para>
 187
 188 @context: the drag context.
 189 @success: a flag indicating whether the drop was succesful
 190 @del: a flag indicating whether the source should delete the
 191       original data. (This should be %TRUE for a move)
 192 @time: the timestamp from the "drag_data_drop" signal.
 193
 194
 195 <!-- ##### FUNCTION gtk_drag_get_data ##### -->
 196 <para>
 197 Get the data associated with a drag. When the data
 198 is received or the retrieval fails, GTK+ will emit a
 199 "drag_data_received" signal. Failure of the retrieval
 200 is indicated by the length field of the @selection_data
 201 signal parameter being negative. However, when gtk_drag_get_data()
 202 is called implicitely because the %GTK_DRAG_DEFAULT_DROP was set,
 203 then the widget will not receive notification of failed
 204 drops.
 205 </para>
 206
 207 @widget: the widget that will receive the "drag_data_received"
 208  signal.
 209 @context: the drag context
 210 @target: the target (form of the data) to retrieve.
 211 @time: a timestamp for retrieving the data. This will
 212        generally be the time received in a "drag_data_motion"
 213        or "drag_data_drop" signal.
 214
 215
 216 <!-- ##### FUNCTION gtk_drag_get_source_widget ##### -->
 217 <para>
 218 Determine the source widget for a drag.
 219 </para>
 220
 221 @context: a (destination side) drag context.
 222 @Returns: if the drag is occurring within a single application,
 223           a pointer to the source widget. Otherwise, NULL.
 224
 225
 226 <!-- ##### FUNCTION gtk_drag_highlight ##### -->
 227 <para>
 228 Draw a highlight around a widget. This will attach
 229 handlers to  "expose_event" and "draw", so the highlight
 230 will continue to be displayed until gtk_drag_unhighlight
 231 is called.
 232 </para>
 233
 234 @widget: a widget to highlight
 235
 236
 237 <!-- ##### FUNCTION gtk_drag_unhighlight ##### -->
 238 <para>
 239 Remove a highlight set by gtk_drag_highlight() from
 240 a widget.
 241 is called.
 242 </para>
 243
 244 @widget: a widget to remove the highlight from.
 245
 246
 247 <!-- ##### FUNCTION gtk_drag_begin ##### -->
 248 <para>
 249 Initiate a drag on the source side. The function
 250 only needs to be used when the application is
 251 starting drags itself, and is not needed when
 252 gtk_drag_source_set() is used.
 253 </para>
 254
 255 @widget: the source widget.
 256 @targets: The targets (data formats) in which the
 257  source can provide the data.
 258 @actions: A bitmask of the allowed drag actions for this
 259           drag.
 260 @button: The button the user clicked to start the drag.
 261 @event: The event that triggered the start of the
 262         drag. Usually
 263 @Returns: The context for this drag.
 264
 265
 266 <!-- ##### FUNCTION gtk_drag_set_icon_widget ##### -->
 267 <para>
 268 </para>
 269
 270 @context:
 271 @widget:
 272 @hot_x:
 273 @hot_y:
 274
 275
 276 <!-- ##### FUNCTION gtk_drag_set_icon_pixmap ##### -->
 277 <para>
 278 </para>
 279
 280 @context:
 281 @colormap:
 282 @pixmap:
 283 @mask:
 284 @hot_x:
 285 @hot_y:
 286
 287
 288 <!-- ##### FUNCTION gtk_drag_set_icon_pixbuf ##### -->
 289 <para>
 290
 291 </para>
 292
 293 @context:
 294 @pixbuf:
 295 @hot_x:
 296 @hot_y:
 297
 298
 299 <!-- ##### FUNCTION gtk_drag_set_icon_stock ##### -->
 300 <para>
 301
 302 </para>
 303
 304 @context:
 305 @stock_id:
 306 @hot_x:
 307 @hot_y:
 308
 309
 310 <!-- ##### FUNCTION gtk_drag_set_icon_default ##### -->
 311 <para>
 312 </para>
 313
 314 @context:
 315
 316
 317 <!-- ##### FUNCTION gtk_drag_set_default_icon ##### -->
 318 <para>
 319
 320 </para>
 321
 322 @colormap:
 323 @pixmap:
 324 @mask:
 325 @hot_x:
 326 @hot_y:
 327
 328
 329 <!-- ##### FUNCTION gtk_drag_check_threshold ##### -->
 330 <para>
 331
 332 </para>
 333
 334 @widget:
 335 @start_x:
 336 @start_y:
 337 @current_x:
 338 @current_y:
 339 @Returns:
 340
 341
 342 <!-- ##### FUNCTION gtk_drag_source_set ##### -->
 343 <para>
 344 Sets up a widget so that GTK+ will start a drag
 345 operation when the user clicks and drags on the
 346 widget. The widget must have a window.
 347 </para>
 348
 349 @widget: a #GtkWidget
 350 @start_button_mask: the bitmask of buttons that can start the drag
 351 @targets: the table of targets that the drag will support
 352 @n_targets: the number of items in @targets
 353 @actions: the bitmask of possible actions for a drag from this
 354  widget.
 355
 356
 357 <!-- ##### FUNCTION gtk_drag_source_set_icon ##### -->
 358 <para>
 359 </para>
 360
 361 @widget:
 362 @colormap:
 363 @pixmap:
 364 @mask:
 365
 366
 367 <!-- ##### FUNCTION gtk_drag_source_set_icon_pixbuf ##### -->
 368 <para>
 369
 370 </para>
 371
 372 @widget:
 373 @pixbuf:
 374
 375
 376 <!-- ##### FUNCTION gtk_drag_source_set_icon_stock ##### -->
 377 <para>
 378
 379 </para>
 380
 381 @widget:
 382 @stock_id:
 383
 384
 385 <!-- ##### FUNCTION gtk_drag_source_unset ##### -->
 386 <para>
 387 Undo the effects of gtk_drag_source_set().
 388 </para>
 389
 390 @widget: a #GtkWidget
 391
 392