general.sgml
keys.sgml
pango_interaction.sgml
+properties.sgml
pixbufs.sgml
regions.sgml
selections.sgml
+++ /dev/null
-<!-- ##### 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>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### 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_text_property_to_text_list_for_display ##### -->
-<para>
-
-</para>
-
-@display:
-@encoding:
-@format:
-@text:
-@length:
-@list:
-@Returns:
-
-
-<!-- ##### 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_text_property_to_utf8_list_for_display ##### -->
-<para>
-
-</para>
-
-@display:
-@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_string_to_compound_text_for_display ##### -->
-<para>
-
-</para>
-
-@display:
-@str:
-@encoding:
-@format:
-@ctext:
-@length:
-@Returns:
-
-
-<!-- ##### 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_utf8_to_compound_text_for_display ##### -->
-<para>
-
-</para>
-
-@display:
-@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, GDK is allowed to not create a new atom, but
- just return %GDK_NONE if the requested atom doesn't already
- exists. Currently, the flag is ignored, since checking the
- existance of an atom is as expensive as creating it.
-@Returns: the atom corresponding to @atom_name.
-
-
-<!-- ##### FUNCTION gdk_atom_intern_static_string ##### -->
-<para>
-
-</para>
-
-@atom_name:
-@Returns:
-
-
-<!-- ##### 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 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.
-</para>
-</note>
-
-@window: a #GdkWindow.
-@property: the property to retrieve.
-@type: the desired property type, or %GDK_NONE, 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 retrieve in bytes. Data is
- considered to be retrieved in 4 byte chunks, so @length
- will be rounded up to the next highest 4 byte boundary
- (so be careful not to pass a value that might overflow
- when rounded up).
-@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 return format of the
- data; either 8, 16 or 32 bits.
-@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
- @actual_length/sizeof(glong) to ensure portability to
- 64 bit systems.
-@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 successfully 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_PREPEND 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_PREPEND 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.
-
-
G_BEGIN_DECLS
+
+/**
+ * GdkPropMode:
+ * @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.
+ *
+ * Describes how existing data is combined with new data when
+ * using gdk_property_change().
+ */
typedef enum
{
GDK_PROP_MODE_REPLACE,
GDK_PROP_MODE_APPEND
} GdkPropMode;
+
GdkAtom gdk_atom_intern (const gchar *atom_name,
gboolean only_if_exists);
GdkAtom gdk_atom_intern_static_string (const gchar *atom_name);
gchar* gdk_atom_name (GdkAtom atom);
+
gboolean gdk_property_get (GdkWindow *window,
GdkAtom property,
GdkAtom type,
gint nelements);
void gdk_property_delete (GdkWindow *window,
GdkAtom property);
+
#ifndef GDK_MULTIHEAD_SAFE
gint gdk_text_property_to_text_list (GdkAtom encoding,
gint format,
gint *format,
guchar **ctext,
gint *length);
-#endif
+#endif /* GDK_MULTIHEAD_SAFE */
gint gdk_text_property_to_text_list_for_display (GdkDisplay *display,
GdkAtom encoding,
target, property, time);
}
+/**
+ * gdk_text_property_to_text_list:
+ * @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().
+ *
+ * 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.)
+ *
+ * Returns: the number of strings stored in @list, or 0,
+ * if the conversion failed.
+ */
gint
gdk_text_property_to_text_list (GdkAtom encoding,
gint format,
encoding, format, text, length, list);
}
+/**
+ * gdk_string_to_compound_text:
+ * @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.
+ *
+ * Converts a string from the encoding of the current locale
+ * into a form suitable for storing in a window property.
+ *
+ * Returns: 0 upon sucess, non-zero upon failure.
+ */
gint
gdk_string_to_compound_text (const gchar *str,
GdkAtom *encoding,
*/
typedef cairo_rectangle_int_t GdkRectangle;
+/**
+ * GdkAtom:
+ *
+ * An opaque type representing a string as an index into a table
+ * of strings on the X server.
+ */
typedef struct _GdkAtom *GdkAtom;
+/**
+ * GDK_ATOM_TO_POINTER:
+ * @atom: a #GdkAtom.
+ *
+ * Converts a #GdkAtom into a pointer type.
+ */
#define GDK_ATOM_TO_POINTER(atom) (atom)
+
+/**
+ * GDK_POINTER_TO_ATOM:
+ * @ptr: a pointer containing a #GdkAtom.
+ *
+ * Extracts a #GdkAtom from a pointer. The #GdkAtom must have been
+ * stored in the pointer with GDK_ATOM_TO_POINTER().
+ */
#define GDK_POINTER_TO_ATOM(ptr) ((GdkAtom)(ptr))
#ifdef GDK_NATIVE_WINDOW_POINTER
#endif
#define _GDK_MAKE_ATOM(val) ((GdkAtom)GUINT_TO_POINTER(val))
+
+/**
+ * GDK_NONE:
+ *
+ * A null value for #GdkAtom, used in a similar way as
+ * <literal>None</literal> in the Xlib API.
+ */
#define GDK_NONE _GDK_MAKE_ATOM (0)
#ifdef GDK_NATIVE_WINDOW_POINTER
#include <string.h>
+/**
+ * SECTION:properties
+ * @Short_description: Functions to manipulate properties on windows
+ * @Title: Properties and Atoms
+ *
+ * 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.
+ *
+ * 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.)
+ *
+ * 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.
+ */
+
+
static GPtrArray *virtual_atom_array;
static GHashTable *virtual_atom_hash;
return result;
}
+/**
+ * gdk_atom_intern:
+ * @atom_name: a string.
+ * @only_if_exists: if %TRUE, GDK is allowed to not create a new atom, but
+ * just return %GDK_NONE if the requested atom doesn't already
+ * exists. Currently, the flag is ignored, since checking the
+ * existance of an atom is as expensive as creating it.
+ *
+ * Finds or creates an atom corresponding to a given string.
+ *
+ * Returns: the atom corresponding to @atom_name.
+ */
GdkAtom
gdk_atom_intern (const gchar *atom_name,
gboolean only_if_exists)
return NULL;
}
+/**
+ * gdk_atom_name:
+ * @atom: a #GdkAtom.
+ *
+ * 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().
+ */
gchar *
gdk_atom_name (GdkAtom atom)
{
return get_atom_name (gdk_x11_xatom_to_atom (xatom));
}
+/**
+ * gdk_property_get:
+ * @window: a #GdkWindow.
+ * @property: the property to retrieve.
+ * @type: the desired property type, or %GDK_NONE, 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 retrieve in bytes. Data is
+ * considered to be retrieved in 4 byte chunks, so @length
+ * will be rounded up to the next highest 4 byte boundary
+ * (so be careful not to pass a value that might overflow
+ * when rounded up).
+ * @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 return format of the
+ * data; either 8, 16 or 32 bits.
+ * @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
+ * @actual_length / sizeof(glong) to ensure portability to
+ * 64 bit systems.
+ * @data: location to store a pointer to the data. The retrieved
+ * data should be freed with g_free() when you are finished
+ * using it.
+ *
+ * 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>
+ * <para>
+ * 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.
+ * </para>
+ * </note>
+ *
+ * Returns: %TRUE if data was successfully received and stored
+ * in @data, otherwise %FALSE.
+ */
gboolean
gdk_property_get (GdkWindow *window,
GdkAtom property,
return TRUE;
}
+/**
+ * gdk_property_change:
+ * @window: a #GdkWindow.
+ * @property: the property to change.
+ * @type: the new type for the property. If @mode is
+ * %GDK_PROP_MODE_PREPEND 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_PREPEND 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.
+ *
+ * Changes the contents of a property on a window.
+ */
void
gdk_property_change (GdkWindow *window,
GdkAtom property,
xtype, format, mode, (guchar *)data, nelements);
}
+/**
+ * gdk_property_delete:
+ * @window: a #GdkWindow.
+ * @property: the property to delete.
+ *
+ * Deletes a property from a window.
+ */
void
gdk_property_delete (GdkWindow *window,
GdkAtom property)
}
}
+/**
+ * gdk_free_text_list:
+ * @list: the value stored in the @list parameter by
+ * a call to gdk_text_property_to_text_list().
+ *
+ * Frees the array of strings created by
+ * gdk_text_property_to_text_list().
+ */
void
gdk_free_text_list (gchar **list)
{
return result;
}
+/**
+ * gdk_free_compound_text:
+ * @ctext: The pointer stored in @ctext from a call to
+ * gdk_string_to_compound_text().
+ *
+ * Frees the data returned from gdk_string_to_compound_text().
+ */
void gdk_free_compound_text (guchar *ctext)
{
if (ctext)
projects / ~andy / gtk / commitdiff