1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 Functions to manipulate properties on windows
7 <!-- ##### SECTION Long_Description ##### -->
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
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.)
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.
40 <!-- ##### SECTION See_Also ##### -->
45 <!-- ##### SECTION Stability_Level ##### -->
48 <!-- ##### STRUCT GdkAtom ##### -->
50 An opaque type representing a string as an index into a table
51 of strings on the X server.
55 <!-- ##### MACRO GDK_ATOM_TO_POINTER ##### -->
57 Converts a #GdkAtom into a pointer type.
63 <!-- ##### MACRO GDK_POINTER_TO_ATOM ##### -->
65 Extracts a #GdkAtom from a pointer. The #GdkAtom must have been
66 stored in the pointer with GDK_ATOM_TO_POINTER().
69 @ptr: a pointer containing a #GdkAtom.
72 <!-- ##### MACRO GDK_NONE ##### -->
74 A null value for #GdkAtom, used in a similar way as <literal>None</literal>
80 <!-- ##### FUNCTION gdk_text_property_to_text_list ##### -->
82 Converts a text string from the encoding as it is stored in
83 a property into an array of strings in the encoding of
84 the current local. (The elements of the array represent
85 the nul-separated elements of the original text string.)
88 @encoding: an atom representing the encoding. The most common
89 values for this are <literal>STRING</literal>,
90 or <literal>COMPOUND_TEXT</literal>. This is
91 value used as the type for the property.
92 @format: the format of the property.
94 @length: the length of the property, in items.
95 @list: location to store a terminated array of strings
96 in the encoding of the current locale. This
97 array should be freed using gdk_free_text_list().
98 @Returns: the number of strings stored in @list, or 0,
99 if the conversion failed.
102 <!-- ##### FUNCTION gdk_text_property_to_text_list_for_display ##### -->
116 <!-- ##### FUNCTION gdk_free_text_list ##### -->
118 Frees the array of strings created by
119 gdk_text_property_to_text_list().
122 @list: the value stored in the @list parameter by
123 a call to gdk_text_property_to_text_list().
126 <!-- ##### FUNCTION gdk_text_property_to_utf8_list ##### -->
139 <!-- ##### FUNCTION gdk_text_property_to_utf8_list_for_display ##### -->
153 <!-- ##### FUNCTION gdk_string_to_compound_text ##### -->
155 Converts a string from the encoding of the current locale
156 into a form suitable for storing in a window property.
159 @str: a nul-terminated string.
160 @encoding: location to store the encoding atom (to be used as the type for the property).
161 @format: location to store the format for the property.
162 @ctext: location to store newly allocated data for the property.
163 @length: location to store the length of @ctext in items.
164 @Returns: 0 upon sucess, non-zero upon failure.
167 <!-- ##### FUNCTION gdk_string_to_compound_text_for_display ##### -->
181 <!-- ##### FUNCTION gdk_free_compound_text ##### -->
183 Frees the data returned from gdk_string_to_compound_text().
186 @ctext: The pointer stored in @ctext from a call to gdk_string_to_compound_text().
189 <!-- ##### FUNCTION gdk_utf8_to_string_target ##### -->
198 <!-- ##### FUNCTION gdk_utf8_to_compound_text ##### -->
211 <!-- ##### FUNCTION gdk_utf8_to_compound_text_for_display ##### -->
225 <!-- ##### FUNCTION gdk_atom_intern ##### -->
227 Finds or creates an atom corresponding to a given string.
230 @atom_name: a string.
231 @only_if_exists: if %TRUE, GDK is allowed to not create a new atom, but
232 just return %GDK_NONE if the requested atom doesn't already
233 exists. Currently, the flag is ignored, since checking the
234 existance of an atom is as expensive as creating it.
235 @Returns: the atom corresponding to @atom_name.
238 <!-- ##### FUNCTION gdk_atom_intern_static_string ##### -->
247 <!-- ##### FUNCTION gdk_atom_name ##### -->
249 Determines the string corresponding to an atom.
253 @Returns: a newly-allocated string containing the string
254 corresponding to @atom. When you are done
255 with the return value, you should free it
259 <!-- ##### FUNCTION gdk_property_get ##### -->
261 Retrieves a portion of the contents of a property. If the
262 property does not exist, then the function returns %FALSE,
263 and %GDK_NONE will be stored in @actual_property_type.
267 The XGetWindowProperty() function that gdk_property_get()
268 uses has a very confusing and complicated set of semantics.
269 Unfortunately, gdk_property_get() makes the situation
270 worse instead of better (the semantics should be considered
271 undefined), and also prints warnings to stderr in cases where it
272 should return a useful error to the program. You are advised to use
273 XGetWindowProperty() directly until a replacement function for
279 @window: a #GdkWindow.
280 @property: the property to retrieve.
281 @type: the desired property type, or %GDK_NONE, if any type of data
282 is acceptable. If this does not match the actual
283 type, then @actual_format and @actual_length will
284 be filled in, a warning will be printed to stderr
285 and no data will be returned.
286 @offset: the offset into the property at which to begin
287 retrieving data, in 4 byte units.
288 @length: the length of the data to retrieve in bytes. Data is
289 considered to be retrieved in 4 byte chunks, so @length
290 will be rounded up to the next highest 4 byte boundary
291 (so be careful not to pass a value that might overflow
293 @pdelete: if %TRUE, delete the property after retrieving the
295 @actual_property_type: location to store the actual type of
297 @actual_format: location to store the actual return format of the
298 data; either 8, 16 or 32 bits.
299 @actual_length: location to store the length of the retrieved data, in
300 bytes. Data returned in the 32 bit format is stored
301 in a long variable, so the actual number of 32 bit
302 elements should be be calculated via
303 @actual_length/sizeof(glong) to ensure portability to
305 @data: location to store a pointer to the data. The retrieved
306 data should be freed with g_free() when you are finished
308 @Returns: %TRUE if data was successfully received and stored
309 in @data, otherwise %FALSE.
312 <!-- ##### FUNCTION gdk_property_change ##### -->
314 Changes the contents of a property on a window.
317 @window: a #GdkWindow.
318 @property: the property to change.
319 @type: the new type for the property. If @mode is
320 %GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this
321 must match the existing type or an error will occur.
322 @format: the new format for the property. If @mode is
323 %GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this
324 must match the existing format or an error will occur.
325 @mode: a value describing how the new data is to be combined
326 with the current data.
328 (a <literal>guchar *</literal>
329 <literal>gushort *</literal>, or
330 <literal>gulong *</literal>, depending on @format), cast to a
331 <literal>guchar *</literal>.
332 @nelements: the number of elements of size determined by the format,
336 <!-- ##### ENUM GdkPropMode ##### -->
338 Describes how existing data is combined with new data when
339 using gdk_property_change().
342 @GDK_PROP_MODE_REPLACE: the new data replaces the existing data.
343 @GDK_PROP_MODE_PREPEND: the new data is prepended to the existing data.
344 @GDK_PROP_MODE_APPEND: the new data is appended to the existing data.
346 <!-- ##### FUNCTION gdk_property_delete ##### -->
348 Deletes a property from a window.
351 @window: a #GdkWindow.
352 @property: the property to delete.