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

   1 <!-- ##### SECTION Title ##### -->
   2 Properties and Atoms
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Functions to manipulate properties on windows
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 Each window under X can have any number of associated
  10 <firstterm>properties</firstterm> attached to it.
  11 Properties are arbitrary chunks of data identified by
  12 <firstterm>atom</firstterm>s. (An <firstterm>atom</firstterm>
  13 is a numeric index into a string table on the X server. They are used
  14 to transfer strings efficiently between clients without
  15 having to transfer the entire string.) A property
  16 has an associated type, which is also identified
  17 using an atom.
  18 </para>
  19 <para>
  20 A property has an associated <firstterm>format</firstterm>,
  21 an integer describing how many bits are in each unit
  22 of data inside the property. It must be 8, 16, or 32.
  23 When data is transferred between the server and client,
  24 if they are of different endianesses it will be byteswapped
  25 as necessary according to the format of the property.
  26 Note that on the client side, properties of format 32
  27 will be stored with one unit per <emphasis>long</emphasis>,
  28 even if a long integer has more than 32 bits on the platform.
  29 (This decision was apparently made for Xlib to maintain
  30 compatibility with programs that assumed longs were 32
  31 bits, at the expense of programs that knew better.)
  32 </para>
  33 <para>
  34 The functions in this section are used to add, remove
  35 and change properties on windows, to convert atoms
  36 to and from strings and to manipulate some types of
  37 data commonly stored in X window properties.
  38 </para>
  39
  40 <!-- ##### SECTION See_Also ##### -->
  41 <para>
  42
  43 </para>
  44
  45 <!-- ##### SECTION Stability_Level ##### -->
  46
  47
  48 <!-- ##### SECTION Image ##### -->
  49
  50
  51 <!-- ##### STRUCT GdkAtom ##### -->
  52 <para>
  53 An opaque type representing a string as an index into a table
  54 of strings on the X server.
  55 </para>
  56
  57
  58 <!-- ##### MACRO GDK_ATOM_TO_POINTER ##### -->
  59 <para>
  60 Converts a #GdkAtom into a pointer type.
  61 </para>
  62
  63 @atom: a #GdkAtom.
  64
  65
  66 <!-- ##### MACRO GDK_POINTER_TO_ATOM ##### -->
  67 <para>
  68 Extracts a #GdkAtom from a pointer. The #GdkAtom must have been
  69 stored in the pointer with GDK_ATOM_TO_POINTER().
  70 </para>
  71
  72 @ptr: a pointer containing a #GdkAtom.
  73
  74
  75 <!-- ##### MACRO GDK_NONE ##### -->
  76 <para>
  77 A null value for #GdkAtom, used in a similar way as <literal>None</literal>
  78 in the Xlib API.
  79 </para>
  80
  81
  82
  83 <!-- ##### FUNCTION gdk_text_property_to_text_list ##### -->
  84 <para>
  85 Converts a text string from the encoding as it is stored in
  86 a property into an array of strings in the encoding of
  87 the current local. (The elements of the array represent
  88 the nul-separated elements of the original text string.)
  89 </para>
  90
  91 @encoding: an atom representing the encoding. The most common
  92            values for this are <literal>STRING</literal>,
  93            or <literal>COMPOUND_TEXT</literal>. This is
  94            value used as the type for the property.
  95 @format: the format of the property.
  96 @text: the text data.
  97 @length: the length of the property, in items.
  98 @list: location to store a terminated array of strings
  99        in the encoding of the current locale. This
 100        array should be freed using gdk_free_text_list().
 101 @Returns: the number of strings stored in @list, or 0,
 102           if the conversion failed.
 103
 104
 105 <!-- ##### FUNCTION gdk_text_property_to_text_list_for_display ##### -->
 106 <para>
 107
 108 </para>
 109
 110 @display:
 111 @encoding:
 112 @format:
 113 @text:
 114 @length:
 115 @list:
 116 @Returns:
 117
 118
 119 <!-- ##### FUNCTION gdk_free_text_list ##### -->
 120 <para>
 121 Frees the array of strings created by
 122 gdk_text_property_to_text_list().
 123 </para>
 124
 125 @list: the value stored in the @list parameter by
 126        a call to gdk_text_property_to_text_list().
 127
 128
 129 <!-- ##### FUNCTION gdk_text_property_to_utf8_list ##### -->
 130 <para>
 131
 132 </para>
 133
 134 @encoding:
 135 @format:
 136 @text:
 137 @length:
 138 @list:
 139 @Returns:
 140
 141
 142 <!-- ##### FUNCTION gdk_text_property_to_utf8_list_for_display ##### -->
 143 <para>
 144
 145 </para>
 146
 147 @display:
 148 @encoding:
 149 @format:
 150 @text:
 151 @length:
 152 @list:
 153 @Returns:
 154
 155
 156 <!-- ##### FUNCTION gdk_string_to_compound_text ##### -->
 157 <para>
 158 Converts a string from the encoding of the current locale
 159 into a form suitable for storing in a window property.
 160 </para>
 161
 162 @str: a nul-terminated string.
 163 @encoding: location to store the encoding atom (to be used as the type for the property).
 164 @format: location to store the format for the property.
 165 @ctext: location to store newly allocated data for the property.
 166 @length: location to store the length of @ctext in items.
 167 @Returns: 0 upon sucess, non-zero upon failure.
 168
 169
 170 <!-- ##### FUNCTION gdk_string_to_compound_text_for_display ##### -->
 171 <para>
 172
 173 </para>
 174
 175 @display:
 176 @str:
 177 @encoding:
 178 @format:
 179 @ctext:
 180 @length:
 181 @Returns:
 182
 183
 184 <!-- ##### FUNCTION gdk_free_compound_text ##### -->
 185 <para>
 186 Frees the data returned from gdk_string_to_compound_text().
 187 </para>
 188
 189 @ctext: The pointer stored in @ctext from a call to gdk_string_to_compound_text().
 190
 191
 192 <!-- ##### FUNCTION gdk_utf8_to_string_target ##### -->
 193 <para>
 194
 195 </para>
 196
 197 @str:
 198 @Returns:
 199
 200
 201 <!-- ##### FUNCTION gdk_utf8_to_compound_text ##### -->
 202 <para>
 203
 204 </para>
 205
 206 @str:
 207 @encoding:
 208 @format:
 209 @ctext:
 210 @length:
 211 @Returns:
 212
 213
 214 <!-- ##### FUNCTION gdk_utf8_to_compound_text_for_display ##### -->
 215 <para>
 216
 217 </para>
 218
 219 @display:
 220 @str:
 221 @encoding:
 222 @format:
 223 @ctext:
 224 @length:
 225 @Returns:
 226
 227
 228 <!-- ##### FUNCTION gdk_atom_intern ##### -->
 229 <para>
 230 Finds or creates an atom corresponding to a given string.
 231 </para>
 232
 233 @atom_name: a string.
 234 @only_if_exists: if %TRUE, GDK is allowed to not create a new atom, but
 235                  just return %GDK_NONE if the requested atom doesn't already
 236                  exists. Currently, the flag is ignored, since checking the
 237                  existance of an atom is as expensive as creating it.
 238 @Returns: the atom corresponding to @atom_name.
 239
 240
 241 <!-- ##### FUNCTION gdk_atom_intern_static_string ##### -->
 242 <para>
 243
 244 </para>
 245
 246 @atom_name:
 247 @Returns:
 248
 249
 250 <!-- ##### FUNCTION gdk_atom_name ##### -->
 251 <para>
 252 Determines the string corresponding to an atom.
 253 </para>
 254
 255 @atom: a #GdkAtom.
 256 @Returns: a newly-allocated string containing the string
 257           corresponding to @atom. When you are done
 258           with the return value, you should free it
 259           using g_free().
 260
 261
 262 <!-- ##### FUNCTION gdk_property_get ##### -->
 263 <para>
 264 Retrieves a portion of the contents of a property. If the
 265 property does not exist, then the function returns %FALSE,
 266 and %GDK_NONE will be stored in @actual_property_type.
 267 </para>
 268 <note>
 269 <para>
 270 The XGetWindowProperty() function that gdk_property_get()
 271 uses has a very confusing and complicated set of semantics.
 272 Unfortunately, gdk_property_get() makes the situation
 273 worse instead of better (the semantics should be considered
 274 undefined), and also prints warnings to stderr in cases where it
 275 should return a useful error to the program. You are advised to use
 276 XGetWindowProperty() directly until a replacement function for
 277 gdk_property_get()
 278 is provided.
 279 </para>
 280 </note>
 281
 282 @window: a #GdkWindow.
 283 @property: the property to retrieve.
 284 @type: the desired property type, or %GDK_NONE, if any type of data
 285        is acceptable. If this does not match the actual
 286        type, then @actual_format and @actual_length will
 287        be filled in, a warning will be printed to stderr
 288        and no data will be returned.
 289 @offset: the offset into the property at which to begin
 290          retrieving data, in 4 byte units.
 291 @length: the length of the data to retrieve in bytes.  Data is
 292          considered to be retrieved in 4 byte chunks, so @length
 293          will be rounded up to the next highest 4 byte boundary
 294          (so be careful not to pass a value that might overflow
 295           when rounded up).
 296 @pdelete: if %TRUE, delete the property after retrieving the
 297           data.
 298 @actual_property_type: location to store the actual type of
 299                        the property.
 300 @actual_format: location to store the actual return format of the
 301                 data; either 8, 16 or 32 bits.
 302 @actual_length: location to store the length of the retrieved data, in
 303                 bytes.  Data returned in the 32 bit format is stored
 304                 in a long variable, so the actual number of 32 bit
 305                 elements should be be calculated via
 306                 @actual_length/sizeof(glong) to ensure portability to
 307                 64 bit systems.
 308 @data: location to store a pointer to the data. The retrieved
 309        data should be freed with g_free() when you are finished
 310        using it.
 311 @Returns: %TRUE if data was successfully received and stored
 312           in @data, otherwise %FALSE.
 313
 314
 315 <!-- ##### FUNCTION gdk_property_change ##### -->
 316 <para>
 317 Changes the contents of a property on a window.
 318 </para>
 319
 320 @window: a #GdkWindow.
 321 @property: the property to change.
 322 @type: the new type for the property. If @mode is
 323        %GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this
 324        must match the existing type or an error will occur.
 325 @format: the new format for the property. If @mode is
 326          %GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this
 327          must match the existing format or an error will occur.
 328 @mode: a value describing how the new data is to be combined
 329        with the current data.
 330 @data: the data
 331        (a <literal>guchar *</literal>
 332         <literal>gushort *</literal>, or
 333         <literal>gulong *</literal>, depending on @format), cast to a
 334         <literal>guchar *</literal>.
 335 @nelements: the number of elements of size determined by the format,
 336             contained in @data.
 337
 338
 339 <!-- ##### ENUM GdkPropMode ##### -->
 340 <para>
 341 Describes how existing data is combined with new data when
 342 using gdk_property_change().
 343 </para>
 344
 345 @GDK_PROP_MODE_REPLACE: the new data replaces the existing data.
 346 @GDK_PROP_MODE_PREPEND: the new data is prepended to the existing data.
 347 @GDK_PROP_MODE_APPEND: the new data is appended to the existing data.
 348
 349 <!-- ##### FUNCTION gdk_property_delete ##### -->
 350 <para>
 351 Deletes a property from a window.
 352 </para>
 353
 354 @window: a #GdkWindow.
 355 @property: the property to delete.
 356
 357