Description
Each window under X can have any number of associated
“properties” attached to it.
Properties are arbitrary chunks of data identified by
“atom”s. (An “atom”
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.
A property has an associated “format”,
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 long,
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.)
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.
Functions
GDK_ATOM_TO_POINTER()
#define GDK_ATOM_TO_POINTER(atom) (atom)
Converts a GdkAtom into a pointer type.
GDK_POINTER_TO_ATOM()
#define GDK_POINTER_TO_ATOM(ptr) ((GdkAtom)(ptr))
Extracts a GdkAtom from a pointer. The GdkAtom must have been
stored in the pointer with GDK_ATOM_TO_POINTER().
gdk_text_property_to_utf8_list_for_display ()
gint
gdk_text_property_to_utf8_list_for_display
(GdkDisplay *display,
GdkAtom encoding,
gint format,
const guchar *text,
gint length,
gchar ***list);
Converts a text property in the given encoding to
a list of UTF-8 strings.
Returns
the number of strings in the resulting list
Since: 2.2
gdk_utf8_to_string_target ()
gchar *
gdk_utf8_to_string_target (const gchar *str);
Converts an UTF-8 string into the best possible representation
as a STRING. The representation of characters not in STRING
is not specified; it may be as pseudo-escape sequences
\x{ABCD}, or it may be in some other form of approximation.
Returns
the newly-allocated string, or NULL if the
conversion failed. (It should not fail for any properly
formed UTF-8 string unless system limits like memory or
file descriptors are exceeded.).
[nullable]
gdk_atom_intern ()
GdkAtom
gdk_atom_intern (const gchar *atom_name,
gboolean only_if_exists);
Finds or creates an atom corresponding to a given string.
Returns
the atom corresponding to atom_name
.
[transfer none]
gdk_atom_intern_static_string ()
GdkAtom
gdk_atom_intern_static_string (const gchar *atom_name);
Finds or creates an atom corresponding to a given string.
Note that this function is identical to gdk_atom_intern() except
that if a new GdkAtom is created the string itself is used rather
than a copy. This saves memory, but can only be used if the string
will always exist. It can be used with statically
allocated strings in the main program, but not with statically
allocated memory in dynamically loaded modules, if you expect to
ever unload the module again (e.g. do not use this function in
GTK+ theme engines).
Returns
the atom corresponding to atom_name
.
[transfer none]
Since: 2.10
gdk_atom_name ()
gchar *
gdk_atom_name (GdkAtom atom);
Determines the string corresponding to an atom.
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().
gdk_property_get ()
gboolean
gdk_property_get (GdkWindow *window,
GdkAtom property,
GdkAtom type,
gulong offset,
gulong length,
gint pdelete,
GdkAtom *actual_property_type,
gint *actual_format,
gint *actual_length,
guchar **data);
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
.
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.
Returns
TRUE if data was successfully received and stored
in data
, otherwise FALSE.
gdk_property_delete ()
void
gdk_property_delete (GdkWindow *window,
GdkAtom property);
Deletes a property from a window.
Types and Values
GdkAtom
typedef struct _GdkAtom *GdkAtom;
An opaque type representing a string as an index into a table
of strings on the X server.
GDK_NONE
#define GDK_NONE _GDK_MAKE_ATOM (0)
A null value for GdkAtom, used in a similar way as
None in the Xlib API.