From d2915ed9d1c8f6e0c1c58ba48cb7f4f0090fa05e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Javier=20Jard=C3=B3n?= Date: Mon, 15 Nov 2010 17:59:52 +0100 Subject: [PATCH] docs: Move documentation to inline comments: properties --- docs/reference/gdk/tmpl/.gitignore | 1 + docs/reference/gdk/tmpl/properties.sgml | 357 ------------------------ gdk/gdkproperty.h | 15 +- gdk/gdkselection.c | 35 +++ gdk/gdktypes.h | 27 ++ gdk/x11/gdkproperty-x11.c | 137 +++++++++ gdk/x11/gdkselection-x11.c | 15 + 7 files changed, 229 insertions(+), 358 deletions(-) delete mode 100644 docs/reference/gdk/tmpl/properties.sgml diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore index e835592bcb..cbc990eb2c 100644 --- a/docs/reference/gdk/tmpl/.gitignore +++ b/docs/reference/gdk/tmpl/.gitignore @@ -10,6 +10,7 @@ gdktesting.sgml general.sgml keys.sgml pango_interaction.sgml +properties.sgml pixbufs.sgml regions.sgml selections.sgml diff --git a/docs/reference/gdk/tmpl/properties.sgml b/docs/reference/gdk/tmpl/properties.sgml deleted file mode 100644 index 64a1b2d3f7..0000000000 --- a/docs/reference/gdk/tmpl/properties.sgml +++ /dev/null @@ -1,357 +0,0 @@ - -Properties and Atoms - - -Functions to manipulate properties on windows - - - -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 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. - - - - - - - - - - - - - - - -An opaque type representing a string as an index into a table -of strings on the X server. - - - - - -Converts a #GdkAtom into a pointer type. - - -@atom: a #GdkAtom. - - - - -Extracts a #GdkAtom from a pointer. The #GdkAtom must have been -stored in the pointer with GDK_ATOM_TO_POINTER(). - - -@ptr: a pointer containing a #GdkAtom. - - - - -A null value for #GdkAtom, used in a similar way as None -in the Xlib API. - - - - - - -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.) - - -@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 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. - - - - - - - -@display: -@encoding: -@format: -@text: -@length: -@list: -@Returns: - - - - -Frees 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(). - - - - - - - -@encoding: -@format: -@text: -@length: -@list: -@Returns: - - - - - - - -@display: -@encoding: -@format: -@text: -@length: -@list: -@Returns: - - - - -Converts a string from the encoding of the current locale -into a form suitable for storing in a window property. - - -@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. - - - - - - - -@display: -@str: -@encoding: -@format: -@ctext: -@length: -@Returns: - - - - -Frees the data returned from gdk_string_to_compound_text(). - - -@ctext: The pointer stored in @ctext from a call to gdk_string_to_compound_text(). - - - - - - - -@str: -@Returns: - - - - - - - -@str: -@encoding: -@format: -@ctext: -@length: -@Returns: - - - - - - - -@display: -@str: -@encoding: -@format: -@ctext: -@length: -@Returns: - - - - -Finds or creates an atom corresponding to a given string. - - -@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. - - - - - - - -@atom_name: -@Returns: - - - - -Determines 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(). - - - - -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. - - - -@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. - - - - -Changes 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_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 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. - - - - -Describes how existing data is combined with new data when -using gdk_property_change(). - - -@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. - - - -Deletes a property from a window. - - -@window: a #GdkWindow. -@property: the property to delete. - - diff --git a/gdk/gdkproperty.h b/gdk/gdkproperty.h index 48d5a07d67..4ea6f8153d 100644 --- a/gdk/gdkproperty.h +++ b/gdk/gdkproperty.h @@ -35,6 +35,16 @@ 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, @@ -42,11 +52,13 @@ typedef enum 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, @@ -66,6 +78,7 @@ void gdk_property_change (GdkWindow *window, 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, @@ -87,7 +100,7 @@ gint gdk_string_to_compound_text (const gchar *str, gint *format, guchar **ctext, gint *length); -#endif +#endif /* GDK_MULTIHEAD_SAFE */ gint gdk_text_property_to_text_list_for_display (GdkDisplay *display, GdkAtom encoding, diff --git a/gdk/gdkselection.c b/gdk/gdkselection.c index fc191aa74f..0a4b428e40 100644 --- a/gdk/gdkselection.c +++ b/gdk/gdkselection.c @@ -137,6 +137,27 @@ gdk_selection_send_notify (GdkNativeWindow requestor, target, property, time); } +/** + * gdk_text_property_to_text_list: + * @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 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, @@ -174,6 +195,20 @@ gdk_text_property_to_utf8_list (GdkAtom encoding, 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, diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h index 4a18bd1bb5..de5ebe27c7 100644 --- a/gdk/gdktypes.h +++ b/gdk/gdktypes.h @@ -73,9 +73,29 @@ typedef struct _GdkPoint GdkPoint; */ 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 @@ -85,6 +105,13 @@ typedef struct _GdkAtom *GdkAtom; #endif #define _GDK_MAKE_ATOM(val) ((GdkAtom)GUINT_TO_POINTER(val)) + +/** + * GDK_NONE: + * + * A null value for #GdkAtom, used in a similar way as + * None in the Xlib API. + */ #define GDK_NONE _GDK_MAKE_ATOM (0) #ifdef GDK_NATIVE_WINDOW_POINTER diff --git a/gdk/x11/gdkproperty-x11.c b/gdk/x11/gdkproperty-x11.c index 4f8d51bea3..b55cd42e5f 100644 --- a/gdk/x11/gdkproperty-x11.c +++ b/gdk/x11/gdkproperty-x11.c @@ -41,6 +41,41 @@ #include +/** + * SECTION:properties + * @Short_description: Functions to manipulate properties on windows + * @Title: Properties and Atoms + * + * 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 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. + */ + + static GPtrArray *virtual_atom_array; static GHashTable *virtual_atom_hash; @@ -395,6 +430,18 @@ intern_atom (const gchar *atom_name, 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) @@ -438,6 +485,16 @@ get_atom_name (GdkAtom atom) 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) { @@ -526,6 +583,59 @@ gdk_x11_get_xatom_name (Atom xatom) 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. + * + * + * + * 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. + */ gboolean gdk_property_get (GdkWindow *window, GdkAtom property, @@ -672,6 +782,26 @@ gdk_property_get (GdkWindow *window, 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 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. + * + * Changes the contents of a property on a window. + */ void gdk_property_change (GdkWindow *window, GdkAtom property, @@ -735,6 +865,13 @@ gdk_property_change (GdkWindow *window, 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) diff --git a/gdk/x11/gdkselection-x11.c b/gdk/x11/gdkselection-x11.c index 6d9e03ac68..03ec39670e 100644 --- a/gdk/x11/gdkselection-x11.c +++ b/gdk/x11/gdkselection-x11.c @@ -480,6 +480,14 @@ gdk_text_property_to_text_list_for_display (GdkDisplay *display, } } +/** + * 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) { @@ -884,6 +892,13 @@ gdk_utf8_to_compound_text_for_display (GdkDisplay *display, 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)