GDK Reference Manual
<<< Previous PageHomeUpNext Page >>>

Properties and Atoms

Name

Properties and Atoms -- functions to manipulate properties on windows.

Synopsis


#include <gdk/gdk.h>


typedef     GdkAtom;
#define     GDK_NONE
gint        gdk_text_property_to_text_list  (GdkAtom encoding,
                                             gint format,
                                             guchar *text,
                                             gint length,
                                             gchar ***list);
void        gdk_free_text_list              (gchar **list);
gint        gdk_string_to_compound_text     (gchar *str,
                                             GdkAtom *encoding,
                                             gint *format,
                                             guchar **ctext,
                                             gint *length);
void        gdk_free_compound_text          (guchar *ctext);
GdkAtom     gdk_atom_intern                 (const gchar *atom_name,
                                             gint only_if_exists);
gchar*      gdk_atom_name                   (GdkAtom atom);
gint        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);
void        gdk_property_change             (GdkWindow *window,
                                             GdkAtom property,
                                             GdkAtom type,
                                             gint format,
                                             GdkPropMode mode,
                                             guchar *data,
                                             gint nelements);
enum        GdkPropMode;
void        gdk_property_delete             (GdkWindow *window,
                                             GdkAtom property);

Description

Each window under X can have any number of associated properties attached to it. Properties are arbitrary chunks of data identified by atoms. (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 transfered 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.

Details

GdkAtom

typedef gulong			      GdkAtom;

A numeric type representing a string as an index into a table of strings on the X server.

GDK_NONE

#define GDK_NONE	     0L

gdk_text_property_to_text_list ()

gint        gdk_text_property_to_text_list  (GdkAtom encoding,
                                             gint format,
                                             guchar *text,
                                             gint length,
                                             gchar ***list);

Convert 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 null-separated elements of the original text string.)

encoding :an atom representing the encoding. The most common values for this are STRING, or COMPOUND_TEXT. 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 item.s
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.

gdk_free_text_list ()

void        gdk_free_text_list              (gchar **list);

Free the array of strings created by gdk_text_property_to_text_list().

list :the value stored in the list parameter by a call to gdk_text_property_to_text_list().

gdk_string_to_compound_text ()

gint        gdk_string_to_compound_text     (gchar *str,
                                             GdkAtom *encoding,
                                             gint *format,
                                             guchar **ctext,
                                             gint *length);

Convert a string from the encoding of the current locale into a form suitable for storing in a window property.

str :a null-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.

gdk_free_compound_text ()

void        gdk_free_compound_text          (guchar *ctext);

Free the data returned from gdk_string_to_compound_text().

ctext :The pointer stored in ctext from a call to gdk_string_to_compound_text().

gdk_atom_intern ()

GdkAtom     gdk_atom_intern                 (const gchar *atom_name,
                                             gint only_if_exists);

Find or create an atom corresponding to a given string.

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 false, and an atom does not already exists for the string, GDK_NONE.

gdk_atom_name ()

gchar*      gdk_atom_name                   (GdkAtom atom);

Determine the string corresponding to an atom.

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().

gdk_property_get ()

gint        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. Note: 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.

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.

gdk_property_change ()

void        gdk_property_change             (GdkWindow *window,
                                             GdkAtom property,
                                             GdkAtom type,
                                             gint format,
                                             GdkPropMode mode,
                                             guchar *data,
                                             gint nelements);

Change the contents of a property on a window.

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 guchar * gushort *, or gulong *, depending on format), cast to a guchar *.
nelements :the number of elements of size determined by the format, contained in data.

enum GdkPropMode

typedef enum
{
  GDK_PROP_MODE_REPLACE,
  GDK_PROP_MODE_PREPEND,
  GDK_PROP_MODE_APPEND
} GdkPropMode;

Describes how existing data is combined with new data when using gdk_property_change().

GDK_PROP_MODE_REPLACEthe new data replaces the existing data.
GDK_PROP_MODE_PREPENDthe new data is prepended to the existing data.
GDK_PROP_MODE_APPENDthe new data is appended to the existing data.

gdk_property_delete ()

void        gdk_property_delete             (GdkWindow *window,
                                             GdkAtom property);

Delete a property from a window.

window :a GdkWindow.
property :the property to delete.



<<< Previous PageHomeUpNext Page >>>
Drag and DropThreads