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 <!-- ##### TYPEDEF GdkSelection ##### -->
  51 <para>
  52 The #GdkSelection enumeration contains predefined
  53 atom values for several common selections.
  54 </para>
  55
  56
  57 <!-- ##### TYPEDEF GdkSelectionType ##### -->
  58 <para>
  59 The #GdkSelectionType enumeration contains predefined
  60 atom values used to represent the types of data transferred
  61 in response to a request for a target. See the
  62 ICCCM for details about what data should be transferred
  63 for each of these types. Other atoms can be used,
  64 and the recommended practice for GTK+ is to to use mime
  65 types for this purpose. However, supporting these types
  66 may be useful for compatibility with older programs.
  67 </para>
  68
  69
  70 <!-- ##### TYPEDEF GdkTarget ##### -->
  71 <para>
  72 The #GdkTarget enumeration contains predefined atom values which are
  73 used to describe possible targets for a selection. Other atoms can be
  74 used, and the recommended practice for GTK+ is to to use mime types
  75 for this purpose. However, supporting these types may be useful for
  76 compatibility with older programs.
  77 </para>
  78
  79
  80 <!-- ##### MACRO GDK_SELECTION_PRIMARY ##### -->
  81 <para>
  82 A #GdkAtom representing the <literal>PRIMARY</literal> selection.
  83 </para>
  84
  85
  86
  87 <!-- ##### MACRO GDK_SELECTION_SECONDARY ##### -->
  88 <para>
  89 A #GdkAtom representing the <literal>SECONDARY</literal> selection.
  90 </para>
  91
  92
  93
  94 <!-- ##### MACRO GDK_SELECTION_CLIPBOARD ##### -->
  95 <para>
  96 A #GdkAtom representing the <literal>CLIPBOARD</literal> selection.
  97 </para>
  98
  99
 100
 101 <!-- ##### MACRO GDK_TARGET_BITMAP ##### -->
 102 <para>
 103 A #GdkAtom representing the <literal>BITMAP</literal> selection target.
 104 </para>
 105
 106
 107
 108 <!-- ##### MACRO GDK_TARGET_COLORMAP ##### -->
 109 <para>
 110 A #GdkAtom representing the <literal>COLORMAP</literal> selection target.
 111 </para>
 112
 113
 114
 115 <!-- ##### MACRO GDK_TARGET_DRAWABLE ##### -->
 116 <para>
 117 A #GdkAtom representing the <literal>DRAWABLE</literal> selection target.
 118 </para>
 119
 120
 121
 122 <!-- ##### MACRO GDK_TARGET_PIXMAP ##### -->
 123 <para>
 124 A #GdkAtom representing the <literal>PIXMAP</literal> selection target.
 125 </para>
 126
 127
 128
 129 <!-- ##### MACRO GDK_TARGET_STRING ##### -->
 130 <para>
 131 A #GdkAtom representing the <literal>STRING</literal> selection target.
 132 </para>
 133
 134
 135
 136 <!-- ##### MACRO GDK_SELECTION_TYPE_ATOM ##### -->
 137 <para>
 138 A #GdkAtom representing the <literal>ATOM</literal> selection type.
 139 </para>
 140
 141
 142
 143 <!-- ##### MACRO GDK_SELECTION_TYPE_BITMAP ##### -->
 144 <para>
 145 A #GdkAtom representing the <literal>BITMAP</literal> selection type.
 146 </para>
 147
 148
 149
 150 <!-- ##### MACRO GDK_SELECTION_TYPE_COLORMAP ##### -->
 151 <para>
 152 A #GdkAtom representing the <literal>COLORMAP</literal> selection type.
 153 </para>
 154
 155
 156
 157 <!-- ##### MACRO GDK_SELECTION_TYPE_DRAWABLE ##### -->
 158 <para>
 159 A #GdkAtom representing the <literal>DRAWABLE</literal> selection type.
 160 </para>
 161
 162
 163
 164 <!-- ##### MACRO GDK_SELECTION_TYPE_INTEGER ##### -->
 165 <para>
 166 A #GdkAtom representing the <literal>INTEGER</literal> selection type.
 167 </para>
 168
 169
 170
 171 <!-- ##### MACRO GDK_SELECTION_TYPE_PIXMAP ##### -->
 172 <para>
 173 A #GdkAtom representing the <literal>PIXMAP</literal> selection type.
 174 </para>
 175
 176
 177
 178 <!-- ##### MACRO GDK_SELECTION_TYPE_WINDOW ##### -->
 179 <para>
 180 A #GdkAtom representing the <literal>WINDOW</literal> selection type.
 181 </para>
 182
 183
 184
 185 <!-- ##### MACRO GDK_SELECTION_TYPE_STRING ##### -->
 186 <para>
 187 A #GdkAtom representing the <literal>STRING</literal> selection type.
 188 </para>
 189
 190
 191
 192 <!-- ##### FUNCTION gdk_selection_owner_set ##### -->
 193 <para>
 194 Sets the owner of the given selection.
 195 </para>
 196
 197 @owner: a #GdkWindow or %NULL to indicate that the
 198         the owner for the given should be unset.
 199 @selection: an atom identifying a selection.
 200 @time: timestamp to use when setting the selection.
 201        If this is older than the timestamp given last
 202        time the owner was set for the given selection, the
 203        request will be ignored.
 204 @send_event: if %TRUE, and the new owner is different
 205              from the current owner, the current owner
 206              will be sent a SelectionClear event.
 207 @Returns: %TRUE if the selection owner was successfully
 208           changed to @owner, otherwise %FALSE.
 209
 210
 211 <!-- ##### FUNCTION gdk_selection_owner_get ##### -->
 212 <para>
 213 Determines the owner of the given selection.
 214 </para>
 215
 216 @selection: an atom indentifying a selection.
 217 @Returns: if there is a selection owner for this window,
 218           and it is a window known to the current process,
 219           the #GdkWindow that owns the selection, otherwise
 220           %NULL. Note that the return value may be owned
 221           by a different process if a foreign window
 222           was previously created for that window, but
 223           a new foreign window will never be created by
 224           this call.
 225
 226
 227 <!-- ##### FUNCTION gdk_selection_convert ##### -->
 228 <para>
 229 Retrieves the contents of a selection in a given
 230 form.
 231 </para>
 232
 233 @requestor: a #GdkWindow.
 234 @selection: an atom identifying the selection to get the
 235             contents of.
 236 @target: the form in which to retrieve the selection.
 237 @time: the timestamp to use when retrieving the
 238        selection. The selection owner may refuse the
 239        request if it did not own the selection at
 240        the time indicated by the timestamp.
 241
 242
 243 <!-- ##### FUNCTION gdk_selection_property_get ##### -->
 244 <para>
 245 Retrieves selection data that was stored by the selection
 246 data in response to a call to gdk_selection_convert().
 247 </para>
 248
 249 @requestor: the window on which the data is stored
 250 @data: location to store a pointer to the retrieved data.
 251        If the retrieval failed, %NULL we be stored here, otherwise, it
 252        will be non-%NULL and the returned data should be freed with g_free()
 253        when you are finished using it. The length of the
 254        allocated memory is one more than the the length
 255        of the returned data, and the final byte will always
 256        be zero, to ensure nul-termination of strings.
 257 @prop_type: location to store the type of the property.
 258 @prop_format: location to store the format of the property.
 259 @Returns: the length of the retrieved data.
 260
 261
 262 <!-- ##### FUNCTION gdk_selection_send_notify ##### -->
 263 <para>
 264 Sends a response to SelectionRequest event.
 265 </para>
 266
 267 @requestor: window to which to deliver response.
 268 @selection: selection that was requested.
 269 @target: target that was selected.
 270 @property: property in which the selection owner stored the
 271            data, or %GDK_NONE to indicate that the request
 272            was rejected.
 273 @time: timestamp.
 274
 275