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