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 <!-- ##### STRUCT GdkAtom ##### -->
  46 <para>
  47 An opaque type representing a string as an index into a table
  48 of strings on the X server.
  49 </para>
  50
  51
  52 <!-- ##### MACRO GDK_ATOM_TO_POINTER ##### -->
  53 <para>
  54 Converts a #GdkAtom into a pointer type.
  55 </para>
  56
  57 @atom: a #GdkAtom.
  58
  59
  60 <!-- ##### MACRO GDK_POINTER_TO_ATOM ##### -->
  61 <para>
  62 Extracts a #GdkAtom from a pointer. The #GdkAtom must have been
  63 stored in the pointer with GDK_ATOM_TO_POINTER().
  64 </para>
  65
  66 @ptr: a pointer containing a #GdkAtom.
  67
  68
  69 <!-- ##### MACRO GDK_NONE ##### -->
  70 <para>
  71 A null value for #GdkAtom, used in a similar way as <literal>None</literal>
  72 in the Xlib API.
  73 </para>
  74
  75
  76
  77 <!-- ##### FUNCTION gdk_text_property_to_text_list ##### -->
  78 <para>
  79 Converts a text string from the encoding as it is stored in
  80 a property into an array of strings in the encoding of
  81 the current local. (The elements of the array represent
  82 the nul-separated elements of the original text string.)
  83 </para>
  84
  85 @encoding: an atom representing the encoding. The most common
  86            values for this are <literal>STRING</literal>,
  87            or <literal>COMPOUND_TEXT</literal>. This is
  88            value used as the type for the property.
  89 @format: the format of the property.
  90 @text: the text data.
  91 @length: the length of the property, in items.
  92 @list: location to store a terminated array of strings
  93        in the encoding of the current locale. This
  94        array should be freed using gdk_free_text_list().
  95 @Returns: the number of strings stored in @list, or 0,
  96           if the conversion failed.
  97
  98
  99 <!-- ##### FUNCTION gdk_text_property_to_text_list_for_display ##### -->
 100 <para>
 101
 102 </para>
 103
 104 @display:
 105 @encoding:
 106 @format:
 107 @text:
 108 @length:
 109 @list:
 110 @Returns:
 111
 112
 113 <!-- ##### FUNCTION gdk_free_text_list ##### -->
 114 <para>
 115 Frees the array of strings created by
 116 gdk_text_property_to_text_list().
 117 </para>
 118
 119 @list: the value stored in the @list parameter by
 120        a call to gdk_text_property_to_text_list().
 121
 122
 123 <!-- ##### FUNCTION gdk_text_property_to_utf8_list ##### -->
 124 <para>
 125
 126 </para>
 127
 128 @encoding:
 129 @format:
 130 @text:
 131 @length:
 132 @list:
 133 @Returns:
 134
 135
 136 <!-- ##### FUNCTION gdk_text_property_to_utf8_list_for_display ##### -->
 137 <para>
 138
 139 </para>
 140
 141 @display:
 142 @encoding:
 143 @format:
 144 @text:
 145 @length:
 146 @list:
 147 @Returns:
 148
 149
 150 <!-- ##### FUNCTION gdk_string_to_compound_text ##### -->
 151 <para>
 152 Converts a string from the encoding of the current locale
 153 into a form suitable for storing in a window property.
 154 </para>
 155
 156 @str: a nul-terminated string.
 157 @encoding: location to store the encoding atom (to be used as the type for the property).
 158 @format: location to store the format for the property.
 159 @ctext: location to store newly allocated data for the property.
 160 @length: location to store the length of @ctext in items.
 161 @Returns: 0 upon sucess, non-zero upon failure.
 162
 163
 164 <!-- ##### FUNCTION gdk_string_to_compound_text_for_display ##### -->
 165 <para>
 166
 167 </para>
 168
 169 @display:
 170 @str:
 171 @encoding:
 172 @format:
 173 @ctext:
 174 @length:
 175 @Returns:
 176
 177
 178 <!-- ##### FUNCTION gdk_free_compound_text ##### -->
 179 <para>
 180 Frees the data returned from gdk_string_to_compound_text().
 181 </para>
 182
 183 @ctext: The pointer stored in @ctext from a call to gdk_string_to_compound_text().
 184
 185
 186 <!-- ##### FUNCTION gdk_utf8_to_string_target ##### -->
 187 <para>
 188
 189 </para>
 190
 191 @str:
 192 @Returns:
 193
 194
 195 <!-- ##### FUNCTION gdk_utf8_to_compound_text ##### -->
 196 <para>
 197
 198 </para>
 199
 200 @str:
 201 @encoding:
 202 @format:
 203 @ctext:
 204 @length:
 205 @Returns:
 206
 207
 208 <!-- ##### FUNCTION gdk_utf8_to_compound_text_for_display ##### -->
 209 <para>
 210
 211 </para>
 212
 213 @display:
 214 @str:
 215 @encoding:
 216 @format:
 217 @ctext:
 218 @length:
 219 @Returns:
 220
 221
 222 <!-- ##### FUNCTION gdk_atom_intern ##### -->
 223 <para>
 224 Finds or creates an atom corresponding to a given string.
 225 </para>
 226
 227 @atom_name: a string.
 228 @only_if_exists: if %TRUE, GDK is allowed to not create a new atom, but
 229                  just return %GDK_NONE if the requested atom doesn't already
 230                  exists. Currently, the flag is ignored, since checking the
 231                  existance of an atom is as expensive as creating it.
 232 @Returns: the atom corresponding to @atom_name.
 233
 234
 235 <!-- ##### FUNCTION gdk_atom_name ##### -->
 236 <para>
 237 Determines the string corresponding to an atom.
 238 </para>
 239
 240 @atom: a #GdkAtom.
 241 @Returns: a newly-allocated string containing the string
 242           corresponding to @atom. When you are done
 243           with the return value, you should free it
 244           using g_free().
 245
 246
 247 <!-- ##### FUNCTION gdk_property_get ##### -->
 248 <para>
 249 Retrieves a portion of the contents of a property. If the
 250 property does not exist, then the function returns %FALSE,
 251 and %GDK_NONE will be stored in @actual_property_type.
 252 </para>
 253 <note>
 254 <para>
 255 The <function>XGetWindowProperty()</function>
 256 function that gdk_property_get()
 257 uses has a very confusing and complicated set of semantics.
 258 Unfortunately, gdk_property_get() makes the situation
 259 worse instead of better (the semantics should be considered
 260 undefined), and also prints warnings to stderr in cases where it
 261 should return a useful error to the program. You are advised to use
 262 <function>XGetWindowProperty()</function>
 263 directly until a replacement function for gdk_property_get()
 264 is provided.
 265 </para>
 266 </note>
 267
 268 @window: a #GdkWindow.
 269 @property: the property to retrieve.
 270 @type: the desired property type, or %GDK_NONE, if any type of data
 271        is acceptable. If this does not match the actual
 272        type, then @actual_format and @actual_length will
 273        be filled in, a warning will be printed to stderr
 274        and no data will be returned.
 275 @offset: the offset into the property at which to begin
 276          retrieving data. (in 4 byte units!)
 277 @length: the length of the data to delete. (in bytes, but
 278          the actual retrieved length will be the next
 279          integer multiple multiple of four greater than
 280          this!)
 281 @pdelete: if %TRUE, delete the property after retrieving the
 282           data.
 283 @actual_property_type: location to store the actual type of
 284                        the property.
 285 @actual_format: location to store the actual format of the data.
 286 @actual_length: location to store the length of the retrieved
 287                 data, in bytes.
 288 @data: location to store a pointer to the data. The retrieved
 289        data should be freed with g_free() when you are finished
 290        using it.
 291 @Returns: %TRUE if data was sucessfully received and stored
 292           in @data, otherwise %FALSE.
 293
 294
 295 <!-- ##### FUNCTION gdk_property_change ##### -->
 296 <para>
 297 Changes the contents of a property on a window.
 298 </para>
 299
 300 @window: a #GdkWindow.
 301 @property: the property to change.
 302 @type: the new type for the property. If @mode is
 303        %GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this
 304        must match the existing type or an error will occur.
 305 @format: the new format for the property. If @mode is
 306          %GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this
 307          must match the existing format or an error will occur.
 308 @mode: a value describing how the new data is to be combined
 309        with the current data.
 310 @data: the data
 311        (a <literal>guchar *</literal>
 312         <literal>gushort *</literal>, or
 313         <literal>gulong *</literal>, depending on @format), cast to a
 314         <literal>guchar *</literal>.
 315 @nelements: the number of elements of size determined by the format,
 316             contained in @data.
 317
 318
 319 <!-- ##### ENUM GdkPropMode ##### -->
 320 <para>
 321 Describes how existing data is combined with new data when
 322 using gdk_property_change().
 323 </para>
 324
 325 @GDK_PROP_MODE_REPLACE: the new data replaces the existing data.
 326 @GDK_PROP_MODE_PREPEND: the new data is prepended to the existing data.
 327 @GDK_PROP_MODE_APPEND: the new data is appended to the existing data.
 328
 329 <!-- ##### FUNCTION gdk_property_delete ##### -->
 330 <para>
 331 Deletes a property from a window.
 332 </para>
 333
 334 @window: a #GdkWindow.
 335 @property: the property to delete.
 336
 337