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 metaphor. 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 widget drag format and action are acceptable.</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 successful,
  63    GTK+ will call gtk_drag_finish(). If the action
  64    was a move, then if the drag was successful, 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 specify
  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 Sets a widget as a potential drop destination.
 115 </para>
 116
 117 @widget: a #GtkWidget
 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 Sets 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 an embedded
 140                   subwindow.
 141
 142
 143 <!-- ##### FUNCTION gtk_drag_dest_unset ##### -->
 144 <para>
 145 Clears 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 Informs 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 successful
 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 Determines 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 Draws 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 Removes a highlight set by gtk_drag_highlight() from
 240 a widget.
 241 </para>
 242
 243 @widget: a widget to remove the highlight from.
 244
 245
 246 <!-- ##### FUNCTION gtk_drag_begin ##### -->
 247 <para>
 248 Initiates a drag on the source side. The function
 249 only needs to be used when the application is
 250 starting drags itself, and is not needed when
 251 gtk_drag_source_set() is used.
 252 </para>
 253
 254 @widget: the source widget.
 255 @targets: The targets (data formats) in which the
 256  source can provide the data.
 257 @actions: A bitmask of the allowed drag actions for this
 258           drag.
 259 @button: The button the user clicked to start the drag.
 260 @event: The event that triggered the start of the
 261         drag.
 262 @Returns: The context for this drag.
 263
 264
 265 <!-- ##### FUNCTION gtk_drag_set_icon_widget ##### -->
 266 <para>
 267 </para>
 268
 269 @context:
 270 @widget:
 271 @hot_x:
 272 @hot_y:
 273
 274
 275 <!-- ##### FUNCTION gtk_drag_set_icon_pixmap ##### -->
 276 <para>
 277 </para>
 278
 279 @context:
 280 @colormap:
 281 @pixmap:
 282 @mask:
 283 @hot_x:
 284 @hot_y:
 285
 286
 287 <!-- ##### FUNCTION gtk_drag_set_icon_pixbuf ##### -->
 288 <para>
 289
 290 </para>
 291
 292 @context:
 293 @pixbuf:
 294 @hot_x:
 295 @hot_y:
 296
 297
 298 <!-- ##### FUNCTION gtk_drag_set_icon_stock ##### -->
 299 <para>
 300
 301 </para>
 302
 303 @context:
 304 @stock_id:
 305 @hot_x:
 306 @hot_y:
 307
 308
 309 <!-- ##### FUNCTION gtk_drag_set_icon_default ##### -->
 310 <para>
 311 </para>
 312
 313 @context:
 314
 315
 316 <!-- ##### FUNCTION gtk_drag_set_default_icon ##### -->
 317 <para>
 318
 319 </para>
 320
 321 @colormap:
 322 @pixmap:
 323 @mask:
 324 @hot_x:
 325 @hot_y:
 326
 327
 328 <!-- ##### FUNCTION gtk_drag_check_threshold ##### -->
 329 <para>
 330
 331 </para>
 332
 333 @widget:
 334 @start_x:
 335 @start_y:
 336 @current_x:
 337 @current_y:
 338 @Returns:
 339
 340
 341 <!-- ##### FUNCTION gtk_drag_source_set ##### -->
 342 <para>
 343 Sets up a widget so that GTK+ will start a drag
 344 operation when the user clicks and drags on the
 345 widget. The widget must have a window.
 346 </para>
 347
 348 @widget: a #GtkWidget
 349 @start_button_mask: the bitmask of buttons that can start the drag
 350 @targets: the table of targets that the drag will support
 351 @n_targets: the number of items in @targets
 352 @actions: the bitmask of possible actions for a drag from this
 353  widget.
 354
 355
 356 <!-- ##### FUNCTION gtk_drag_source_set_icon ##### -->
 357 <para>
 358 </para>
 359
 360 @widget:
 361 @colormap:
 362 @pixmap:
 363 @mask:
 364
 365
 366 <!-- ##### FUNCTION gtk_drag_source_set_icon_pixbuf ##### -->
 367 <para>
 368
 369 </para>
 370
 371 @widget:
 372 @pixbuf:
 373
 374
 375 <!-- ##### FUNCTION gtk_drag_source_set_icon_stock ##### -->
 376 <para>
 377
 378 </para>
 379
 380 @widget:
 381 @stock_id:
 382
 383
 384 <!-- ##### FUNCTION gtk_drag_source_unset ##### -->
 385 <para>
 386 Undoes the effects of gtk_drag_source_set().
 387 </para>
 388
 389 @widget: a #GtkWidget
 390
 391