properties.sgml 9.71 KB
Newer Older
Owen Taylor's avatar
Owen Taylor committed
1 2 3 4
<!-- ##### SECTION Title ##### -->
Properties and Atoms

<!-- ##### SECTION Short_Description ##### -->
5
Functions to manipulate properties on windows
Owen Taylor's avatar
Owen Taylor committed
6 7 8

<!-- ##### SECTION Long_Description ##### -->
<para>
Owen Taylor's avatar
Owen Taylor committed
9 10 11 12 13 14 15 16 17
Each window under X can have any number of associated
<firstterm>properties</firstterm> attached to it.
Properties are arbitrary chunks of data identified by
<firstterm>atom</firstterm>s. (An <firstterm>atom</firstterm>
is a numeric index into a string table on the X server. They are used
to transfer strings efficiently between clients without
having to transfer the entire string.) A property
has an associated type, which is also identified
using an atom.
Owen Taylor's avatar
Owen Taylor committed
18 19
</para>
<para>
Owen Taylor's avatar
Owen Taylor committed
20 21 22
A property has an associated <firstterm>format</firstterm>,
an integer describing how many bits are in each unit
of data inside the property. It must be 8, 16, or 32.
Matthias Clasen's avatar
Matthias Clasen committed
23
When data is transferred between the server and client,
Owen Taylor's avatar
Owen Taylor committed
24 25 26 27 28 29 30 31
if they are of different endianesses it will be byteswapped
as necessary according to the format of the property.
Note that on the client side, properties of format 32
will be stored with one unit per <emphasis>long</emphasis>,
even if a long integer has more than 32 bits on the platform.
(This decision was apparently made for Xlib to maintain
compatibility with programs that assumed longs were 32
bits, at the expense of programs that knew better.)
Owen Taylor's avatar
Owen Taylor committed
32 33
</para>
<para>
Owen Taylor's avatar
Owen Taylor committed
34 35 36 37
The functions in this section are used to add, remove
and change properties on windows, to convert atoms
to and from strings and to manipulate some types of
data commonly stored in X window properties.
Owen Taylor's avatar
Owen Taylor committed
38 39
</para>

Owen Taylor's avatar
Owen Taylor committed
40
<!-- ##### SECTION See_Also ##### -->
Owen Taylor's avatar
Owen Taylor committed
41 42 43 44
<para>

</para>

45 46 47
<!-- ##### SECTION Stability_Level ##### -->


48 49 50
<!-- ##### SECTION Image ##### -->


51
<!-- ##### TYPEDEF GdkAtom ##### -->
Owen Taylor's avatar
Updates  
Owen Taylor committed
52
<para>
Matthias Clasen's avatar
Matthias Clasen committed
53
An opaque type representing a string as an index into a table
Owen Taylor's avatar
Updates  
Owen Taylor committed
54 55 56 57
of strings on the X server.
</para>


Owen Taylor's avatar
Owen Taylor committed
58 59
<!-- ##### MACRO GDK_ATOM_TO_POINTER ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
60
Converts a #GdkAtom into a pointer type. 
Owen Taylor's avatar
Owen Taylor committed
61 62
</para>

Matthias Clasen's avatar
Matthias Clasen committed
63
@atom: a #GdkAtom.
Owen Taylor's avatar
Owen Taylor committed
64 65 66 67


<!-- ##### MACRO GDK_POINTER_TO_ATOM ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
68 69
Extracts a #GdkAtom from a pointer. The #GdkAtom must have been
stored in the pointer with GDK_ATOM_TO_POINTER().
Owen Taylor's avatar
Owen Taylor committed
70 71
</para>

Matthias Clasen's avatar
Matthias Clasen committed
72
@ptr: a pointer containing a #GdkAtom.
Owen Taylor's avatar
Owen Taylor committed
73 74


Damon Chaplin's avatar
Damon Chaplin committed
75 76
<!-- ##### MACRO GDK_NONE ##### -->
<para>
Matthias Clasen's avatar
Update.  
Matthias Clasen committed
77 78
A null value for #GdkAtom, used in a similar way as <literal>None</literal>
in the Xlib API.
Damon Chaplin's avatar
Damon Chaplin committed
79 80 81 82
</para>



Owen Taylor's avatar
Owen Taylor committed
83 84
<!-- ##### FUNCTION gdk_text_property_to_text_list ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
85
Converts a text string from the encoding as it is stored in
Owen Taylor's avatar
Owen Taylor committed
86 87
a property into an array of strings in the encoding of
the current local. (The elements of the array represent
Matthias Clasen's avatar
Matthias Clasen committed
88
the nul-separated elements of the original text string.)
Owen Taylor's avatar
Owen Taylor committed
89 90
</para>

Owen Taylor's avatar
Owen Taylor committed
91 92 93 94 95 96
@encoding: an atom representing the encoding. The most common
           values for this are <literal>STRING</literal>,
           or <literal>COMPOUND_TEXT</literal>. This is
           value used as the type for the property.
@format: the format of the property.
@text: the text data.
Matthias Clasen's avatar
Matthias Clasen committed
97
@length: the length of the property, in items.
Owen Taylor's avatar
Owen Taylor committed
98 99 100 101 102
@list: location to store a terminated array of strings
       in the encoding of the current locale. This
       array should be freed using gdk_free_text_list().
@Returns: the number of strings stored in @list, or 0,
          if the conversion failed.
Owen Taylor's avatar
Owen Taylor committed
103 104


Owen Taylor's avatar
Owen Taylor committed
105 106 107 108 109 110 111 112 113 114 115 116 117 118
<!-- ##### FUNCTION gdk_text_property_to_text_list_for_display ##### -->
<para>

</para>

@display: 
@encoding: 
@format: 
@text: 
@length: 
@list: 
@Returns: 


Owen Taylor's avatar
Owen Taylor committed
119 120
<!-- ##### FUNCTION gdk_free_text_list ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
121
Frees the array of strings created by
Owen Taylor's avatar
Owen Taylor committed
122
gdk_text_property_to_text_list().
Owen Taylor's avatar
Owen Taylor committed
123 124
</para>

Owen Taylor's avatar
Owen Taylor committed
125 126
@list: the value stored in the @list parameter by
       a call to gdk_text_property_to_text_list().
Owen Taylor's avatar
Owen Taylor committed
127 128


Owen Taylor's avatar
Owen Taylor committed
129 130 131 132 133 134 135 136 137 138 139 140 141
<!-- ##### FUNCTION gdk_text_property_to_utf8_list ##### -->
<para>

</para>

@encoding: 
@format: 
@text: 
@length: 
@list: 
@Returns: 


Owen Taylor's avatar
Owen Taylor committed
142 143 144 145 146 147 148 149 150 151 152 153 154 155
<!-- ##### FUNCTION gdk_text_property_to_utf8_list_for_display ##### -->
<para>

</para>

@display: 
@encoding: 
@format: 
@text: 
@length: 
@list: 
@Returns: 


Owen Taylor's avatar
Owen Taylor committed
156 157
<!-- ##### FUNCTION gdk_string_to_compound_text ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
158
Converts a string from the encoding of the current locale 
Owen Taylor's avatar
Owen Taylor committed
159
into a form suitable for storing in a window property.
Owen Taylor's avatar
Owen Taylor committed
160 161
</para>

Matthias Clasen's avatar
Matthias Clasen committed
162
@str: a nul-terminated string.
Owen Taylor's avatar
Owen Taylor committed
163 164 165 166 167
@encoding: location to store the encoding atom (to be used as the type for the property).
@format: location to store the format for the property.
@ctext: location to store newly allocated data for the property.
@length: location to store the length of @ctext in items.
@Returns: 0 upon sucess, non-zero upon failure.
Owen Taylor's avatar
Owen Taylor committed
168 169


Owen Taylor's avatar
Owen Taylor committed
170 171 172 173 174 175 176 177 178 179 180 181 182 183
<!-- ##### FUNCTION gdk_string_to_compound_text_for_display ##### -->
<para>

</para>

@display: 
@str: 
@encoding: 
@format: 
@ctext: 
@length: 
@Returns: 


Owen Taylor's avatar
Owen Taylor committed
184 185
<!-- ##### FUNCTION gdk_free_compound_text ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
186
Frees the data returned from gdk_string_to_compound_text().
Owen Taylor's avatar
Owen Taylor committed
187 188
</para>

Owen Taylor's avatar
Owen Taylor committed
189
@ctext: The pointer stored in @ctext from a call to gdk_string_to_compound_text().
Owen Taylor's avatar
Owen Taylor committed
190 191


Owen Taylor's avatar
Owen Taylor committed
192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
<!-- ##### FUNCTION gdk_utf8_to_string_target ##### -->
<para>

</para>

@str: 
@Returns: 


<!-- ##### FUNCTION gdk_utf8_to_compound_text ##### -->
<para>

</para>

@str: 
@encoding: 
@format: 
@ctext: 
@length: 
@Returns: 


Owen Taylor's avatar
Owen Taylor committed
214 215 216 217 218 219 220 221 222 223 224 225 226 227
<!-- ##### FUNCTION gdk_utf8_to_compound_text_for_display ##### -->
<para>

</para>

@display: 
@str: 
@encoding: 
@format: 
@ctext: 
@length: 
@Returns: 


Owen Taylor's avatar
Owen Taylor committed
228 229
<!-- ##### FUNCTION gdk_atom_intern ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
230
Finds or creates an atom corresponding to a given string.
Owen Taylor's avatar
Owen Taylor committed
231 232
</para>

Owen Taylor's avatar
Owen Taylor committed
233
@atom_name: a string.
234 235 236 237
@only_if_exists: if %TRUE, GDK is allowed to not create a new atom, but
                 just return %GDK_NONE if the requested atom doesn't already
                 exists. Currently, the flag is ignored, since checking the 
                 existance of an atom is as expensive as creating it.
Matthias Clasen's avatar
Matthias Clasen committed
238
@Returns: the atom corresponding to @atom_name.
Owen Taylor's avatar
Owen Taylor committed
239 240


241 242 243 244 245 246 247 248 249
<!-- ##### FUNCTION gdk_atom_intern_static_string ##### -->
<para>

</para>

@atom_name: 
@Returns: 


Owen Taylor's avatar
Owen Taylor committed
250 251
<!-- ##### FUNCTION gdk_atom_name ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
252
Determines the string corresponding to an atom.
Owen Taylor's avatar
Owen Taylor committed
253 254
</para>

Owen Taylor's avatar
Owen Taylor committed
255
@atom: a #GdkAtom.
Matthias Clasen's avatar
Matthias Clasen committed
256
@Returns: a newly-allocated string containing the string
Owen Taylor's avatar
Owen Taylor committed
257 258 259
          corresponding to @atom. When you are done
          with the return value, you should free it 
          using g_free().
Owen Taylor's avatar
Owen Taylor committed
260 261 262 263


<!-- ##### FUNCTION gdk_property_get ##### -->
<para>
Owen Taylor's avatar
Owen Taylor committed
264
Retrieves a portion of the contents of a property. If the
Matthias Clasen's avatar
Matthias Clasen committed
265
property does not exist, then the function returns %FALSE,
Owen Taylor's avatar
Owen Taylor committed
266
and %GDK_NONE will be stored in @actual_property_type.
Matthias Clasen's avatar
Matthias Clasen committed
267 268 269
</para>
<note>
<para>
270 271
The XGetWindowProperty() function that gdk_property_get()
uses has a very confusing and complicated set of semantics.  
Owen Taylor's avatar
Owen Taylor committed
272 273 274 275
Unfortunately, gdk_property_get() makes the situation
worse instead of better (the semantics should be considered
undefined), and also prints warnings to stderr in cases where it
should return a useful error to the program. You are advised to use 
276 277
XGetWindowProperty() directly until a replacement function for 
gdk_property_get()
Owen Taylor's avatar
Owen Taylor committed
278
is provided. 
Owen Taylor's avatar
Owen Taylor committed
279
</para>
Matthias Clasen's avatar
Matthias Clasen committed
280
</note>
Owen Taylor's avatar
Owen Taylor committed
281

Owen Taylor's avatar
Owen Taylor committed
282 283
@window: a #GdkWindow.
@property: the property to retrieve.
284
@type: the desired property type, or %GDK_NONE, if any type of data
Owen Taylor's avatar
Owen Taylor committed
285 286 287 288 289
       is acceptable. If this does not match the actual
       type, then @actual_format and @actual_length will
       be filled in, a warning will be printed to stderr
       and no data will be returned.
@offset: the offset into the property at which to begin
290 291 292 293 294 295
         retrieving data, in 4 byte units.
@length: the length of the data to retrieve in bytes.  Data is
         considered to be retrieved in 4 byte chunks, so @length 
         will be rounded up to the next highest 4 byte boundary 
         (so be careful not to pass a value that might overflow 
          when rounded up).
Owen Taylor's avatar
Owen Taylor committed
296 297 298 299
@pdelete: if %TRUE, delete the property after retrieving the
          data.
@actual_property_type: location to store the actual type of 
                       the property.
300 301 302 303 304 305 306 307
@actual_format: location to store the actual return format of the
                data; either 8, 16 or 32 bits.
@actual_length: location to store the length of the retrieved data, in
                bytes.  Data returned in the 32 bit format is stored
                in a long variable, so the actual number of 32 bit
                elements should be be calculated via
                @actual_length/sizeof(glong) to ensure portability to
                64 bit systems.
Owen Taylor's avatar
Owen Taylor committed
308 309 310
@data: location to store a pointer to the data. The retrieved
       data should be freed with g_free() when you are finished
       using it.
311
@Returns: %TRUE if data was successfully received and stored
Owen Taylor's avatar
Owen Taylor committed
312
          in @data, otherwise %FALSE.
Owen Taylor's avatar
Owen Taylor committed
313 314 315 316


<!-- ##### FUNCTION gdk_property_change ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
317
Changes the contents of a property on a window.
Owen Taylor's avatar
Owen Taylor committed
318 319
</para>

Owen Taylor's avatar
Owen Taylor committed
320 321 322
@window: a #GdkWindow.
@property: the property to change.
@type: the new type for the property. If @mode is
323
       %GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this 
Owen Taylor's avatar
Owen Taylor committed
324 325
       must match the existing type or an error will occur.
@format: the new format for the property. If @mode is
326
         %GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this 
Owen Taylor's avatar
Owen Taylor committed
327 328 329 330 331 332 333 334 335 336
         must match the existing format or an error will occur.
@mode: a value describing how the new data is to be combined
       with the current data.
@data: the data
       (a <literal>guchar *</literal>
        <literal>gushort *</literal>, or 
        <literal>gulong *</literal>, depending on @format), cast to a 
        <literal>guchar *</literal>.
@nelements: the number of elements of size determined by the format,
            contained in @data.
Owen Taylor's avatar
Owen Taylor committed
337 338


Owen Taylor's avatar
Owen Taylor committed
339
<!-- ##### ENUM GdkPropMode ##### -->
Owen Taylor's avatar
Owen Taylor committed
340
<para>
Owen Taylor's avatar
Owen Taylor committed
341 342 343 344 345 346 347
Describes how existing data is combined with new data when
using gdk_property_change().
</para>

@GDK_PROP_MODE_REPLACE: the new data replaces the existing data.
@GDK_PROP_MODE_PREPEND: the new data is prepended to the existing data.
@GDK_PROP_MODE_APPEND: the new data is appended to the existing data.
Owen Taylor's avatar
Owen Taylor committed
348

Owen Taylor's avatar
Owen Taylor committed
349 350
<!-- ##### FUNCTION gdk_property_delete ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
351
Deletes a property from a window.
Owen Taylor's avatar
Owen Taylor committed
352 353
</para>

Owen Taylor's avatar
Owen Taylor committed
354 355
@window: a #GdkWindow.
@property: the property to delete.
Owen Taylor's avatar
Owen Taylor committed
356 357