forked from AuroraMiddleware/gtk
358 lines
9.7 KiB
Plaintext
358 lines
9.7 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
Properties and Atoms
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
Functions to manipulate properties on windows
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
When data is transferred between the server and client,
|
|
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.)
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### SECTION Stability_Level ##### -->
|
|
|
|
|
|
<!-- ##### SECTION Image ##### -->
|
|
|
|
|
|
<!-- ##### STRUCT GdkAtom ##### -->
|
|
<para>
|
|
An opaque type representing a string as an index into a table
|
|
of strings on the X server.
|
|
</para>
|
|
|
|
|
|
<!-- ##### MACRO GDK_ATOM_TO_POINTER ##### -->
|
|
<para>
|
|
Converts a #GdkAtom into a pointer type.
|
|
</para>
|
|
|
|
@atom: a #GdkAtom.
|
|
|
|
|
|
<!-- ##### MACRO GDK_POINTER_TO_ATOM ##### -->
|
|
<para>
|
|
Extracts a #GdkAtom from a pointer. The #GdkAtom must have been
|
|
stored in the pointer with GDK_ATOM_TO_POINTER().
|
|
</para>
|
|
|
|
@ptr: a pointer containing a #GdkAtom.
|
|
|
|
|
|
<!-- ##### MACRO GDK_NONE ##### -->
|
|
<para>
|
|
A null value for #GdkAtom, used in a similar way as <literal>None</literal>
|
|
in the Xlib API.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_text_property_to_text_list ##### -->
|
|
<para>
|
|
Converts a text string from the encoding as it is stored in
|
|
a property into an array of strings in the encoding of
|
|
the current local. (The elements of the array represent
|
|
the nul-separated elements of the original text string.)
|
|
</para>
|
|
|
|
@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.
|
|
@length: the length of the property, in items.
|
|
@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.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_text_property_to_text_list_for_display ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@display:
|
|
@encoding:
|
|
@format:
|
|
@text:
|
|
@length:
|
|
@list:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_free_text_list ##### -->
|
|
<para>
|
|
Frees the array of strings created by
|
|
gdk_text_property_to_text_list().
|
|
</para>
|
|
|
|
@list: the value stored in the @list parameter by
|
|
a call to gdk_text_property_to_text_list().
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_text_property_to_utf8_list ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@encoding:
|
|
@format:
|
|
@text:
|
|
@length:
|
|
@list:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_text_property_to_utf8_list_for_display ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@display:
|
|
@encoding:
|
|
@format:
|
|
@text:
|
|
@length:
|
|
@list:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_string_to_compound_text ##### -->
|
|
<para>
|
|
Converts a string from the encoding of the current locale
|
|
into a form suitable for storing in a window property.
|
|
</para>
|
|
|
|
@str: a nul-terminated string.
|
|
@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.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_string_to_compound_text_for_display ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@display:
|
|
@str:
|
|
@encoding:
|
|
@format:
|
|
@ctext:
|
|
@length:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_free_compound_text ##### -->
|
|
<para>
|
|
Frees the data returned from gdk_string_to_compound_text().
|
|
</para>
|
|
|
|
@ctext: The pointer stored in @ctext from a call to gdk_string_to_compound_text().
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_utf8_to_string_target ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@str:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_utf8_to_compound_text ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@str:
|
|
@encoding:
|
|
@format:
|
|
@ctext:
|
|
@length:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_utf8_to_compound_text_for_display ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@display:
|
|
@str:
|
|
@encoding:
|
|
@format:
|
|
@ctext:
|
|
@length:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_atom_intern ##### -->
|
|
<para>
|
|
Finds or creates an atom corresponding to a given string.
|
|
</para>
|
|
|
|
@atom_name: a string.
|
|
@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.
|
|
@Returns: the atom corresponding to @atom_name.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_atom_intern_static_string ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@atom_name:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_atom_name ##### -->
|
|
<para>
|
|
Determines the string corresponding to an atom.
|
|
</para>
|
|
|
|
@atom: a #GdkAtom.
|
|
@Returns: a newly-allocated string containing the string
|
|
corresponding to @atom. When you are done
|
|
with the return value, you should free it
|
|
using g_free().
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_property_get ##### -->
|
|
<para>
|
|
Retrieves a portion of the contents of a property. If the
|
|
property does not exist, then the function returns %FALSE,
|
|
and %GDK_NONE will be stored in @actual_property_type.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
The XGetWindowProperty() function that gdk_property_get()
|
|
uses has a very confusing and complicated set of semantics.
|
|
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
|
|
XGetWindowProperty() directly until a replacement function for
|
|
gdk_property_get()
|
|
is provided.
|
|
</para>
|
|
</note>
|
|
|
|
@window: a #GdkWindow.
|
|
@property: the property to retrieve.
|
|
@type: the desired property type, or %GDK_NONE, if any type of data
|
|
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
|
|
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).
|
|
@pdelete: if %TRUE, delete the property after retrieving the
|
|
data.
|
|
@actual_property_type: location to store the actual type of
|
|
the property.
|
|
@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.
|
|
@data: location to store a pointer to the data. The retrieved
|
|
data should be freed with g_free() when you are finished
|
|
using it.
|
|
@Returns: %TRUE if data was successfully received and stored
|
|
in @data, otherwise %FALSE.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_property_change ##### -->
|
|
<para>
|
|
Changes the contents of a property on a window.
|
|
</para>
|
|
|
|
@window: a #GdkWindow.
|
|
@property: the property to change.
|
|
@type: the new type for the property. If @mode is
|
|
%GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this
|
|
must match the existing type or an error will occur.
|
|
@format: the new format for the property. If @mode is
|
|
%GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this
|
|
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.
|
|
|
|
|
|
<!-- ##### ENUM GdkPropMode ##### -->
|
|
<para>
|
|
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.
|
|
|
|
<!-- ##### FUNCTION gdk_property_delete ##### -->
|
|
<para>
|
|
Deletes a property from a window.
|
|
</para>
|
|
|
|
@window: a #GdkWindow.
|
|
@property: the property to delete.
|
|
|
|
|