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 #GtkDestDefaults 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
  34 @GTK_DEST_DEFAULT_MOTION:
  35    If set for a widget, GTK+, during a drag over this
  36    widget will check if the drag matches this widget's
  37    list of possible targets and actions.
  38    GTK+ will then call gdk_drag_status() as appropriate.
  39 @GTK_DEST_DEFAULT_HIGHLIGHT:
  40    If set for a widget, GTK+ will draw a highlight on
  41    this widget as long as a drag is over this widget
  42    and the widget drag format and action are acceptable.
  43 @GTK_DEST_DEFAULT_DROP:
  44    If set for a widget, when a drop occurs, GTK+ will
  45    will check if the drag matches this widget's
  46    list of possible targets and actions. If so,
  47    GTK+ will call gtk_drag_get_data() on behalf
  48    of the widget. Whether or not the drop is successful,
  49    GTK+ will call gtk_drag_finish(). If the action
  50    was a move, then if the drag was successful, then
  51    %TRUE will be passed for the @delete parameter
  52    to gtk_drag_finish().
  53 @GTK_DEST_DEFAULT_ALL:
  54    If set, specifies that all default actions should
  55    be taken.
  56
  57 <!-- ##### ENUM GtkTargetFlags ##### -->
  58 <para>
  59 The #GtkTargetFlags enumeration is used to specify
  60 constraints on an entry in a #GtkTargetTable.
  61 </para>
  62
  63 @GTK_TARGET_SAME_APP:
  64    If this is set, the target will only be selected
  65    for drags within a single application.
  66 @GTK_TARGET_SAME_WIDGET:
  67    If this is set, the target will only be selected
  68    for drags within a single widget.
  69
  70 <!-- ##### FUNCTION gtk_drag_dest_set ##### -->
  71 <para>
  72 Sets a widget as a potential drop destination.
  73 </para>
  74
  75 @widget: a #GtkWidget
  76 @flags: the flags that specify what actions GTK+ should take
  77  on behalf of a widget for drops onto that widget. The @targets
  78  and @actions fields only are used if %GTK_DEST_DEFAULT_MOTION
  79  or %GTK_DEST_DEFAULT_DROP are given.
  80 @targets: a pointer to an array of #GtkTargetEntry<!-- -->s indicating
  81  the drop types that this widget will accept.
  82 @n_targets: the number of entries in @targets.
  83 @actions: a bitmask of possible actions for a drop onto this
  84  widget.
  85
  86
  87 <!-- ##### FUNCTION gtk_drag_dest_set_proxy ##### -->
  88 <para>
  89 Sets this widget as a proxy for drops to another window.
  90 </para>
  91
  92 @widget: a #GtkWidget
  93 @proxy_window: the window to which to forward drag events
  94 @protocol: the drag protocol which the @proxy_window accepts
  95            (You can use gdk_drag_get_protocol() to determine this)
  96 @use_coordinates: If %TRUE, send the same coordinates to the
  97                   destination, because it is an embedded
  98                   subwindow.
  99
 100
 101 <!-- ##### FUNCTION gtk_drag_dest_unset ##### -->
 102 <para>
 103 Clears information about a drop destination set with
 104 gtk_drag_dest_set(). The widget will no longer receive
 105 notification of drags.
 106 </para>
 107
 108 @widget: a #GtkWidget
 109
 110
 111 <!-- ##### FUNCTION gtk_drag_dest_find_target ##### -->
 112 <para>
 113
 114 </para>
 115
 116 @widget:
 117 @context:
 118 @target_list:
 119 @Returns:
 120
 121
 122 <!-- ##### FUNCTION gtk_drag_dest_get_target_list ##### -->
 123 <para>
 124
 125 </para>
 126
 127 @widget:
 128 @Returns:
 129
 130
 131 <!-- ##### FUNCTION gtk_drag_dest_set_target_list ##### -->
 132 <para>
 133
 134 </para>
 135
 136 @widget:
 137 @target_list:
 138
 139
 140 <!-- ##### FUNCTION gtk_drag_dest_add_text_targets ##### -->
 141 <para>
 142
 143 </para>
 144
 145 @widget:
 146
 147
 148 <!-- ##### FUNCTION gtk_drag_finish ##### -->
 149 <para>
 150 Informs the drag source that the drop is finished, and
 151 that the data of the drag will no longer be required.
 152 </para>
 153
 154 @context: the drag context.
 155 @success: a flag indicating whether the drop was successful
 156 @del: a flag indicating whether the source should delete the
 157       original data. (This should be %TRUE for a move)
 158 @time_: the timestamp from the "drag_data_drop" signal.
 159
 160
 161 <!-- ##### FUNCTION gtk_drag_get_data ##### -->
 162 <para>
 163 Gets the data associated with a drag. When the data
 164 is received or the retrieval fails, GTK+ will emit a
 165 "drag_data_received" signal. Failure of the retrieval
 166 is indicated by the length field of the @selection_data
 167 signal parameter being negative. However, when gtk_drag_get_data()
 168 is called implicitely because the %GTK_DEST_DEFAULT_DROP was set,
 169 then the widget will not receive notification of failed
 170 drops.
 171 </para>
 172
 173 @widget: the widget that will receive the "drag_data_received"
 174  signal.
 175 @context: the drag context
 176 @target: the target (form of the data) to retrieve.
 177 @time_: a timestamp for retrieving the data. This will
 178        generally be the time received in a "drag_data_motion"
 179        or "drag_data_drop" signal.
 180
 181
 182 <!-- ##### FUNCTION gtk_drag_get_source_widget ##### -->
 183 <para>
 184 Determines the source widget for a drag.
 185 </para>
 186
 187 @context: a (destination side) drag context.
 188 @Returns: if the drag is occurring within a single application,
 189           a pointer to the source widget. Otherwise, %NULL.
 190
 191
 192 <!-- ##### FUNCTION gtk_drag_highlight ##### -->
 193 <para>
 194 Draws a highlight around a widget. This will attach
 195 handlers to  "expose_event" and "draw", so the highlight
 196 will continue to be displayed until gtk_drag_unhighlight()
 197 is called.
 198 </para>
 199
 200 @widget: a widget to highlight
 201
 202
 203 <!-- ##### FUNCTION gtk_drag_unhighlight ##### -->
 204 <para>
 205 Removes a highlight set by gtk_drag_highlight() from
 206 a widget.
 207 </para>
 208
 209 @widget: a widget to remove the highlight from.
 210
 211
 212 <!-- ##### FUNCTION gtk_drag_begin ##### -->
 213 <para>
 214
 215 </para>
 216
 217 @widget:
 218 @targets:
 219 @actions:
 220 @button:
 221 @event:
 222 @Returns:
 223
 224
 225 <!-- ##### FUNCTION gtk_drag_set_icon_widget ##### -->
 226 <para>
 227 </para>
 228
 229 @context:
 230 @widget:
 231 @hot_x:
 232 @hot_y:
 233
 234
 235 <!-- ##### FUNCTION gtk_drag_set_icon_pixmap ##### -->
 236 <para>
 237 </para>
 238
 239 @context:
 240 @colormap:
 241 @pixmap:
 242 @mask:
 243 @hot_x:
 244 @hot_y:
 245
 246
 247 <!-- ##### FUNCTION gtk_drag_set_icon_pixbuf ##### -->
 248 <para>
 249
 250 </para>
 251
 252 @context:
 253 @pixbuf:
 254 @hot_x:
 255 @hot_y:
 256
 257
 258 <!-- ##### FUNCTION gtk_drag_set_icon_stock ##### -->
 259 <para>
 260
 261 </para>
 262
 263 @context:
 264 @stock_id:
 265 @hot_x:
 266 @hot_y:
 267
 268
 269 <!-- ##### FUNCTION gtk_drag_set_icon_default ##### -->
 270 <para>
 271 </para>
 272
 273 @context:
 274
 275
 276 <!-- ##### FUNCTION gtk_drag_set_default_icon ##### -->
 277 <para>
 278
 279 </para>
 280
 281 @colormap:
 282 @pixmap:
 283 @mask:
 284 @hot_x:
 285 @hot_y:
 286
 287
 288 <!-- ##### FUNCTION gtk_drag_check_threshold ##### -->
 289 <para>
 290
 291 </para>
 292
 293 @widget:
 294 @start_x:
 295 @start_y:
 296 @current_x:
 297 @current_y:
 298 @Returns:
 299
 300
 301 <!-- ##### FUNCTION gtk_drag_source_set ##### -->
 302 <para>
 303 Sets up a widget so that GTK+ will start a drag
 304 operation when the user clicks and drags on the
 305 widget. The widget must have a window.
 306 </para>
 307
 308 @widget: a #GtkWidget
 309 @start_button_mask: the bitmask of buttons that can start the drag
 310 @targets: the table of targets that the drag will support
 311 @n_targets: the number of items in @targets
 312 @actions: the bitmask of possible actions for a drag from this
 313  widget.
 314
 315
 316 <!-- ##### FUNCTION gtk_drag_source_set_icon ##### -->
 317 <para>
 318 </para>
 319
 320 @widget:
 321 @colormap:
 322 @pixmap:
 323 @mask:
 324
 325
 326 <!-- ##### FUNCTION gtk_drag_source_set_icon_pixbuf ##### -->
 327 <para>
 328
 329 </para>
 330
 331 @widget:
 332 @pixbuf:
 333
 334
 335 <!-- ##### FUNCTION gtk_drag_source_set_icon_stock ##### -->
 336 <para>
 337
 338 </para>
 339
 340 @widget:
 341 @stock_id:
 342
 343
 344 <!-- ##### FUNCTION gtk_drag_source_unset ##### -->
 345 <para>
 346 Undoes the effects of gtk_drag_source_set().
 347 </para>
 348
 349 @widget: a #GtkWidget
 350
 351
 352 <!-- ##### FUNCTION gtk_drag_source_set_target_list ##### -->
 353 <para>
 354
 355 </para>
 356
 357 @widget:
 358 @target_list:
 359
 360
 361 <!-- ##### FUNCTION gtk_drag_source_get_target_list ##### -->
 362 <para>
 363
 364 </para>
 365
 366 @widget:
 367 @Returns:
 368
 369
 370 <!-- ##### FUNCTION gtk_drag_source_add_text_targets ##### -->
 371 <para>
 372
 373 </para>
 374
 375 @widget:
 376
 377