AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-09-19 21:40:22 +00:00
Code Issues Projects Releases Wiki Activity

docs: Move documentation to inline comments: properties

Browse Source
This commit is contained in:
Javier Jardón 2010-11-15 17:59:52 +01:00
parent 2f06ec02be
commit d2915ed9d1
7 changed files with 229 additions and 358 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/gdk/tmpl/.gitignore vendored
View File

@ -10,6 +10,7 @@ gdktesting.sgml
general.sgml
keys.sgml
pango_interaction.sgml
properties.sgml
pixbufs.sgml
regions.sgml
selections.sgml

357
docs/reference/gdk/tmpl/properties.sgml
View File

@ -1,357 +0,0 @@
<!-- ##### 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.

15
gdk/gdkproperty.h
View File

@ -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,

35
gdk/gdkselection.c
View File

@ -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 <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,
@ -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,

27
gdk/gdktypes.h
View File

@ -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
* <literal>None</literal> in the Xlib API.
*/
#define GDK_NONE _GDK_MAKE_ATOM (0)
#ifdef GDK_NATIVE_WINDOW_POINTER

137
gdk/x11/gdkproperty-x11.c
View File

@ -41,6 +41,41 @@
#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;
@ -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.
*
* <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,
@ -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 <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,
@ -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)

15
gdk/x11/gdkselection-x11.c
View File

@ -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)