Properties and Atoms

Properties and Atoms — Functions to manipulate properties on windows

Types and Values

  GdkAtom

Includes

#include <gdk/gdk.h>

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_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

a GdkDisplay

 

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 text , in bytes

 

list

location to store the list of strings or NULL. The list should be freed with g_strfreev().

[out][array zero-terminated=1]

Returns

the number of strings in the resulting list


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.

Parameters

str

a UTF-8 string

 

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]

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.