Top |
Functions
#define | GDK_ATOM_TO_POINTER() |
#define | GDK_POINTER_TO_ATOM() |
gint | gdk_text_property_to_utf8_list_for_display () |
gchar * | gdk_utf8_to_string_target () |
GdkAtom | gdk_atom_intern () |
GdkAtom | gdk_atom_intern_static_string () |
gchar * | gdk_atom_name () |
gboolean | gdk_property_get () |
void | gdk_property_change () |
void | gdk_property_delete () |
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.
Parameters
display |
||
encoding |
an atom representing the encoding of the text |
|
format |
the format of the property |
|
text |
the text to convert. |
[array length=length] |
length |
the length of |
|
list |
location to store the list
of strings or |
[out][array zero-terminated=1] |
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.)
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.
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).
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.
Parameters
window |
||
property |
the property to retrieve |
|
type |
the desired property type, or |
|
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 |
|
pdelete |
if |
|
actual_property_type |
location to store the actual type of the property. |
[out][transfer none] |
actual_format |
location to store the actual return format of the data; either 8, 16 or 32 bits. |
[out] |
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
|
|
data |
location
to store a pointer to the data. The retrieved data should be
freed with |
[out][array length=actual_length][transfer full] |
gdk_property_change ()
void gdk_property_change (GdkWindow *window
,GdkAtom property
,GdkAtom type
,gint format
,GdkPropMode mode
,const guchar *data
,gint nelements
);
Changes the contents of a property on a window.
Parameters
window |
||
property |
the property to change |
|
type |
the new type for the property. If |
|
format |
the new format for the property. If |
|
mode |
a value describing how the new data is to be combined with the current data. |
|
data |
the data (a |
|
nelements |
the number of elements of size determined by the format,
contained in |
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.
enum GdkPropMode
Describes how existing data is combined with new data when
using gdk_property_change()
.