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

   1 <!-- ##### SECTION Title ##### -->
   2 Selections
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Functions for transfering data via the X selection mechanism
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The X selection mechanism provides a way to transfer
  10 arbitrary chunks of data between programs.
  11 A <firstterm>selection</firstterm> is a essentially
  12 a named clipboard, identified by a string interned
  13 as a #GdkAtom. By claiming ownership of a selection,
  14 an application indicates that it will be responsible
  15 for supplying its contents. The most common
  16 selections are <literal>PRIMARY</literal> and
  17 <literal>CLIPBOARD</literal>.
  18 </para>
  19 <para>
  20 The contents of a selection can be represented in
  21 a number of formats, called <firstterm>targets</firstterm>.
  22 Each target is identified by an atom. A list of
  23 all possible targets supported by the selection owner
  24 can be retrieved by requesting the special target
  25 <literal>TARGETS</literal>. When a selection is
  26 retrieved, the data is accompanied by a type
  27 (an atom), and a format (an integer, representing
  28 the number of bits per item).
  29 See <link linkend="gdk-Properties-and-Atoms">Properties and Atoms</link>
  30 for more information.
  31 </para>
  32 <para>
  33 The functions in this section only contain the lowlevel
  34 parts of the selection protocol. A considerably more
  35 complicated implementation is needed on top of this.
  36 GTK+ contains such an implementation in the functions
  37 in <literal>gtkselection.h</literal> and programmers
  38 should use those functions instead of the ones presented
  39 here. If you plan to implement selection handling
  40 directly on top of the functions here, you should refer
  41 to the X Inter-client Communication Conventions Manual
  42 (ICCCM).
  43 </para>
  44
  45 <!-- ##### SECTION See_Also ##### -->
  46 <para>
  47
  48 </para>
  49
  50 <!-- ##### SECTION Stability_Level ##### -->
  51
  52
  53 <!-- ##### SECTION Image ##### -->
  54
  55
  56 <!-- ##### MACRO GDK_SELECTION_PRIMARY ##### -->
  57 <para>
  58 A #GdkAtom representing the <literal>PRIMARY</literal> selection.
  59 </para>
  60
  61
  62
  63 <!-- ##### MACRO GDK_SELECTION_SECONDARY ##### -->
  64 <para>
  65 A #GdkAtom representing the <literal>SECONDARY</literal> selection.
  66 </para>
  67
  68
  69
  70 <!-- ##### MACRO GDK_SELECTION_CLIPBOARD ##### -->
  71 <para>
  72 A #GdkAtom representing the <literal>CLIPBOARD</literal> selection.
  73 </para>
  74
  75
  76
  77 <!-- ##### MACRO GDK_TARGET_BITMAP ##### -->
  78 <para>
  79 A #GdkAtom representing the <literal>BITMAP</literal> selection target.
  80 </para>
  81
  82
  83
  84 <!-- ##### MACRO GDK_TARGET_COLORMAP ##### -->
  85 <para>
  86 A #GdkAtom representing the <literal>COLORMAP</literal> selection target.
  87 </para>
  88
  89
  90
  91 <!-- ##### MACRO GDK_TARGET_DRAWABLE ##### -->
  92 <para>
  93 A #GdkAtom representing the <literal>DRAWABLE</literal> selection target.
  94 </para>
  95
  96
  97
  98 <!-- ##### MACRO GDK_TARGET_PIXMAP ##### -->
  99 <para>
 100 A #GdkAtom representing the <literal>PIXMAP</literal> selection target.
 101 </para>
 102
 103
 104
 105 <!-- ##### MACRO GDK_TARGET_STRING ##### -->
 106 <para>
 107 A #GdkAtom representing the <literal>STRING</literal> selection target.
 108 </para>
 109
 110
 111
 112 <!-- ##### MACRO GDK_SELECTION_TYPE_ATOM ##### -->
 113 <para>
 114 A #GdkAtom representing the <literal>ATOM</literal> selection type.
 115 </para>
 116
 117
 118
 119 <!-- ##### MACRO GDK_SELECTION_TYPE_BITMAP ##### -->
 120 <para>
 121 A #GdkAtom representing the <literal>BITMAP</literal> selection type.
 122 </para>
 123
 124
 125
 126 <!-- ##### MACRO GDK_SELECTION_TYPE_COLORMAP ##### -->
 127 <para>
 128 A #GdkAtom representing the <literal>COLORMAP</literal> selection type.
 129 </para>
 130
 131
 132
 133 <!-- ##### MACRO GDK_SELECTION_TYPE_DRAWABLE ##### -->
 134 <para>
 135 A #GdkAtom representing the <literal>DRAWABLE</literal> selection type.
 136 </para>
 137
 138
 139
 140 <!-- ##### MACRO GDK_SELECTION_TYPE_INTEGER ##### -->
 141 <para>
 142 A #GdkAtom representing the <literal>INTEGER</literal> selection type.
 143 </para>
 144
 145
 146
 147 <!-- ##### MACRO GDK_SELECTION_TYPE_PIXMAP ##### -->
 148 <para>
 149 A #GdkAtom representing the <literal>PIXMAP</literal> selection type.
 150 </para>
 151
 152
 153
 154 <!-- ##### MACRO GDK_SELECTION_TYPE_WINDOW ##### -->
 155 <para>
 156 A #GdkAtom representing the <literal>WINDOW</literal> selection type.
 157 </para>
 158
 159
 160
 161 <!-- ##### MACRO GDK_SELECTION_TYPE_STRING ##### -->
 162 <para>
 163 A #GdkAtom representing the <literal>STRING</literal> selection type.
 164 </para>
 165
 166
 167
 168 <!-- ##### FUNCTION gdk_selection_owner_set ##### -->
 169 <para>
 170 Sets the owner of the given selection.
 171 </para>
 172
 173 @owner: a #GdkWindow or %NULL to indicate that the
 174         the owner for the given should be unset.
 175 @selection: an atom identifying a selection.
 176 @time_: timestamp to use when setting the selection.
 177        If this is older than the timestamp given last
 178        time the owner was set for the given selection, the
 179        request will be ignored.
 180 @send_event: if %TRUE, and the new owner is different
 181              from the current owner, the current owner
 182              will be sent a SelectionClear event.
 183 @Returns: %TRUE if the selection owner was successfully
 184           changed to @owner, otherwise %FALSE.
 185
 186
 187 <!-- ##### FUNCTION gdk_selection_owner_set_for_display ##### -->
 188 <para>
 189
 190 </para>
 191
 192 @display:
 193 @owner:
 194 @selection:
 195 @time_:
 196 @send_event:
 197 @Returns:
 198
 199
 200 <!-- ##### FUNCTION gdk_selection_owner_get ##### -->
 201 <para>
 202 Determines the owner of the given selection.
 203 </para>
 204
 205 @selection: an atom indentifying a selection.
 206 @Returns: if there is a selection owner for this window,
 207           and it is a window known to the current process,
 208           the #GdkWindow that owns the selection, otherwise
 209           %NULL. Note that the return value may be owned
 210           by a different process if a foreign window
 211           was previously created for that window, but
 212           a new foreign window will never be created by
 213           this call.
 214
 215
 216 <!-- ##### FUNCTION gdk_selection_owner_get_for_display ##### -->
 217 <para>
 218
 219 </para>
 220
 221 @display:
 222 @selection:
 223 @Returns:
 224
 225
 226 <!-- ##### FUNCTION gdk_selection_convert ##### -->
 227 <para>
 228 Retrieves the contents of a selection in a given
 229 form.
 230 </para>
 231
 232 @requestor: a #GdkWindow.
 233 @selection: an atom identifying the selection to get the
 234             contents of.
 235 @target: the form in which to retrieve the selection.
 236 @time_: the timestamp to use when retrieving the
 237        selection. The selection owner may refuse the
 238        request if it did not own the selection at
 239        the time indicated by the timestamp.
 240
 241
 242 <!-- ##### FUNCTION gdk_selection_property_get ##### -->
 243 <para>
 244 </para>
 245
 246 @requestor:
 247 @data:
 248 @prop_type:
 249 @prop_format:
 250 @Returns:
 251
 252
 253 <!-- ##### FUNCTION gdk_selection_send_notify ##### -->
 254 <para>
 255 Sends a response to SelectionRequest event.
 256 </para>
 257
 258 @requestor: window to which to deliver response.
 259 @selection: selection that was requested.
 260 @target: target that was selected.
 261 @property: property in which the selection owner stored the
 262            data, or %GDK_NONE to indicate that the request
 263            was rejected.
 264 @time_: timestamp.
 265
 266
 267 <!-- ##### FUNCTION gdk_selection_send_notify_for_display ##### -->
 268 <para>
 269
 270 </para>
 271
 272 @display:
 273 @requestor:
 274 @selection:
 275 @target:
 276 @property:
 277 @time_:
 278
 279