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

   1 <!-- ##### SECTION Title ##### -->
   2 Selections
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Functions for handling inter-process communication via selections.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8
   9 <para>
  10 The selection mechanism provides the basis for different types
  11 of IPC between processes. In particular, drag and drop and
  12 #GtkClipboard work via selections. You will very seldom or
  13 never need to use most of the functions in this section directly;
  14 #GtkClipboard provides a nicer interface to the same functionality.
  15 </para>
  16 <para>
  17 Some of the datatypes defined this section are used in
  18 the #GtkClipboard and drag-and-drop API's as well. The
  19 #GtkTargetEntry structure and #GtkTargetList objects represent
  20 lists of data types that are supported when sending or
  21 receiving data. The #GtkSelectionData object is used to
  22 store a chunk of data along with the data type and other
  23 associated information.
  24 </para>
  25
  26 <!-- ##### SECTION See_Also ##### -->
  27 <para>
  28 <variablelist>
  29
  30 <varlistentry>
  31 <term>#GtkWidget</term>
  32 <listitem><para>Much of the operation of selections happens via
  33              signals for #GtkWidget. In particular, if you are
  34              using the functions in this section, you may need
  35              to pay attention to ::selection_get,
  36              ::selection_received,  and :selection_clear_event
  37              signals.</para></listitem>
  38 </varlistentry>
  39
  40 </variablelist>
  41
  42 </para>
  43
  44 <!-- ##### STRUCT GtkTargetEntry ##### -->
  45 <para>
  46 A #GtkTargetEntry structure represents a single type of
  47 data than can be supplied for by a widget for a selection
  48 or for supplied or received during drag-and-drop. It
  49 contains a string representing the drag type, a flags
  50 field (used only for drag and drop - see #GtkTargetFlags),
  51 and an application assigned integer ID. The integer
  52 ID will later be passed as a signal parameter for signals
  53 like "selection_get". It allows the application to identify
  54 the target type without extensive string compares.
  55 </para>
  56
  57 @target:
  58 @flags:
  59 @info:
  60
  61 <!-- ##### STRUCT GtkTargetList ##### -->
  62 <para>
  63 A #GtkTargetList structure is a reference counted list
  64 of #GtkTargetPair. It is used to represent the same
  65 information as a table of #GtkTargetEntry, but in
  66 an efficient form. This structure should be treated as
  67 opaque.
  68 </para>
  69
  70 @list:
  71 @ref_count:
  72
  73 <!-- ##### STRUCT GtkTargetPair ##### -->
  74 <para>
  75 Internally used structure in the drag-and-drop and
  76 selection handling code.
  77 </para>
  78
  79 @target:
  80 @flags:
  81 @info:
  82
  83 <!-- ##### FUNCTION gtk_target_list_new ##### -->
  84 <para>
  85 Create a new #GtkTargetList from an array of #GtkTargetEntry.
  86 </para>
  87
  88 @targets: Pointer to an array of #GtkTargetEntry
  89 @ntargets: number of entries in @targets.
  90 @Returns: the new #GtkTargetList.
  91
  92
  93 <!-- ##### FUNCTION gtk_target_list_ref ##### -->
  94 <para>
  95 Increase the reference count of a #GtkTargetList by one.
  96 </para>
  97
  98 @list: a #GtkTargetList
  99
 100
 101 <!-- ##### FUNCTION gtk_target_list_unref ##### -->
 102 <para>
 103 Decrease the reference count of a #GtkTargetList by one.
 104 If the resulting reference count is zero, free the list.
 105 </para>
 106
 107 @list: a #GtkTargetList
 108
 109
 110 <!-- ##### FUNCTION gtk_target_list_add ##### -->
 111 <para>
 112 Add another target to a #GtkTargetList
 113 </para>
 114
 115 @list: a #GtkTargetList
 116 @target: the interned atom representing the target
 117 @flags: the flags for this target
 118 @info: an ID that will be passed back to the application
 119
 120
 121 <!-- ##### FUNCTION gtk_target_list_add_table ##### -->
 122 <para>
 123 Add a table of #GtkTargetEntry into a target list
 124 </para>
 125
 126 @list: a #GtkTargetList
 127 @targets: the table of #GtkTargetEntry
 128 @ntargets: number of targets in the table
 129
 130
 131 <!-- ##### FUNCTION gtk_target_list_remove ##### -->
 132 <para>
 133 Remove a target from a target list
 134 </para>
 135
 136 @list: a #GtkTargetList
 137 @target: the interned atom representing the target
 138
 139
 140 <!-- ##### FUNCTION gtk_target_list_find ##### -->
 141 <para>
 142 Look up a given target in a #GtkTargetList
 143 </para>
 144
 145 @list: a #GtkTargetList
 146 @target: an interned atom representing the target to search for
 147 @info: a pointer to the location to store application info for target
 148 @Returns: %TRUE if the target was found, otherwise %FALSE
 149
 150
 151 <!-- ##### FUNCTION gtk_selection_owner_set ##### -->
 152 <para>
 153 Claim ownership of a given selection for a particular widget,
 154 or, if @widget is %NULL, release ownership of the selection.
 155 </para>
 156
 157 @widget: a #GtkWidget, or %NULL.
 158 @selection: an interned atom representing the selection to claim
 159 @time: the time stamp for claiming the selection
 160 @Returns: %TRUE if the operation succeeded
 161
 162
 163 <!-- ##### FUNCTION gtk_selection_add_target ##### -->
 164 <para>
 165 Add specified target to the list of supported targets for a
 166 given widget and selection.
 167 </para>
 168
 169 @widget: a #GtkTarget
 170 @selection: the selection
 171 @target: target to add.
 172 @info: A unsigned integer which will be passed back to the application.
 173
 174
 175 <!-- ##### FUNCTION gtk_selection_add_targets ##### -->
 176 <para>
 177 Add a table of targets to the list of supported targets
 178 for a given widget and selection.
 179 </para>
 180
 181 @widget: a #GtkWidget
 182 @selection: the selection
 183 @targets: a table of targets to add
 184 @ntargets: number of entries in @targets
 185
 186
 187 <!-- ##### FUNCTION gtk_selection_clear_targets ##### -->
 188 <para>
 189
 190 </para>
 191
 192 @widget:
 193 @selection:
 194
 195
 196 <!-- ##### FUNCTION gtk_selection_convert ##### -->
 197 <para>
 198 Request the contents of a selection. When received,
 199 a "selection_received" signal will be generated.
 200 </para>
 201
 202 @widget: The widget which acts as requestor
 203 @selection: Which selection to get
 204 @target: Form of information desired (e.g., STRING)
 205 @time: Time of request (usually of triggering event)
 206        In emergency, you could use GDK_CURRENT_TIME
 207 @Returns: TRUE if requested succeeded. FALSE if we could not process
 208           request. (e.g., there was already a request in process for
 209           this widget).
 210
 211
 212 <!-- ##### FUNCTION gtk_selection_data_set ##### -->
 213 <para>
 214 Store new data into a GtkSelectionData object. Should
 215 _only_ by called from a selection handler callback.
 216 Null terminates the stored data.
 217 </para>
 218
 219 @selection_data:
 220 @type: the type of selection data
 221 @format: format (number of bits in a unit)
 222 @data: pointer to the data (will be copied)
 223 @length: length of the data
 224
 225
 226 <!-- ##### FUNCTION gtk_selection_data_set_text ##### -->
 227 <para>
 228
 229 </para>
 230
 231 @selection_data:
 232 @str:
 233 @Returns:
 234
 235
 236 <!-- ##### FUNCTION gtk_selection_data_get_text ##### -->
 237 <para>
 238
 239 </para>
 240
 241 @selection_data:
 242 @Returns:
 243
 244
 245 <!-- ##### FUNCTION gtk_selection_remove_all ##### -->
 246 <para>
 247 Removes all handlers and unsets ownership of all
 248 selections for a widget. Called when widget is being
 249 destroyed. This function will not generally be
 250 called by applications.
 251 </para>
 252
 253 @widget: a #GtkWidget
 254
 255
 256 <!-- ##### FUNCTION gtk_selection_data_copy ##### -->
 257 <para>
 258 Make a copy of a #GtkSelection data structure and its
 259 data.
 260 </para>
 261
 262 @data: a pointer to a #GtkSelectionData structure.
 263 @Returns: a pointer to a copy of @data.
 264
 265
 266 <!-- ##### FUNCTION gtk_selection_data_free ##### -->
 267 <para>
 268 Free a #GtkSelectionData structure returned from
 269 gtk_selection_data_copy().
 270 </para>
 271
 272 @data: a pointer to a #GtkSelectionData structure.
 273
 274
 275 <!-- ##### FUNCTION gtk_selection_clear ##### -->
 276 <para>
 277 Internal function.
 278 </para>
 279
 280 @widget:
 281 @event:
 282 @Returns:
 283
 284
 285 <!-- ##### FUNCTION gtk_selection_incr_event ##### -->
 286 <para>
 287 Internal function.
 288 </para>
 289
 290 @window:
 291 @event:
 292 @Returns:
 293
 294
 295 <!-- ##### FUNCTION gtk_selection_notify ##### -->
 296 <para>
 297 Internal function.
 298 </para>
 299
 300 @widget:
 301 @event:
 302 @Returns:
 303
 304
 305 <!-- ##### FUNCTION gtk_selection_property_notify ##### -->
 306 <para>
 307 Internal function.
 308 </para>
 309
 310 @widget:
 311 @event:
 312 @Returns:
 313
 314
 315 <!-- ##### FUNCTION gtk_selection_request ##### -->
 316 <para>
 317 Internal function.
 318 </para>
 319
 320 @widget:
 321 @event:
 322 @Returns:
 323
 324