forked from AuroraMiddleware/gtk
5b291073b0
* gdk-pixbuf/porting-from-imlib.sgml: GDK instead of Gdk.
* gdk-pixbuf/tmpl/gdk-pixbuf-xlib-init.sgml: Replace references to
deprecated functions.
* gdk/tmpl/event_structs.sgml, gdk/tmpl/gcs.sgml,
gdk/tmpl/images.sgml: Replace references to deprecated functions.
* gdk/tmpl/properties.sgml, gdk/tmpl/selections.sgml: Additions.
* gdk/x11/gdkproperty-x11.c, gdk/x11/gdkselection-x11.c:
Minor documentation tweaks.
282 lines
8.5 KiB
Plaintext
282 lines
8.5 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>
|
|
|
|
<!-- ##### 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_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_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_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_atom_intern ##### -->
|
|
<para>
|
|
Finds or creates an atom corresponding to a given string.
|
|
</para>
|
|
|
|
@atom_name: a string.
|
|
@only_if_exists: if %TRUE, do not create a new atom, but
|
|
just return the atom if it already exists.
|
|
@Returns: the atom corresponding to @atom_name, or, if
|
|
@only_if_exists is %TRUE, and an atom does not
|
|
already exists for the string, %GDK_NONE.
|
|
|
|
|
|
<!-- ##### 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 <function>XGetWindowProperty()</function>
|
|
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
|
|
<function>XGetWindowProperty()</function>
|
|
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 0, 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 delete. (in bytes, but
|
|
the actual retrieved length will be the next
|
|
integer multiple multiple of four greater than
|
|
this!)
|
|
@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 format of the data.
|
|
@actual_length: location to store the length of the retrieved
|
|
data, in bytes.
|
|
@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 sucessfully 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_REPLACE 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_REPLACE 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.
|
|
|
|
|