luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-13 07:56:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

Migrating docs.

Browse Source 
* docs/reference/gobject/tmpl/gboxed.sgml:
	* gobject/gboxed.c:
	* gobject/gboxed.h:
	* gobject/gvaluetypes.c:
	  Migrating docs.


svn path=/trunk/; revision=7065
This commit is contained in:
Stefan Kost 2008-06-21 10:19:58 +00:00
parent 304c030d02
commit 86a0f779f6
5 changed files with 140 additions and 159 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
ChangeLog
View File

@ -1,3 +1,11 @@
2008-06-21 Stefan Kost <ensonic@users.sf.net>
* docs/reference/gobject/tmpl/gboxed.sgml:
* gobject/gboxed.c:
* gobject/gboxed.h:
* gobject/gvaluetypes.c:
Migrating docs.
2008-06-20 Sebastian Dröge <slomo@circular-chaos.org> 2008-06-20 Sebastian Dröge <slomo@circular-chaos.org>
Bug 316221 - G_LOCK warns about breaking strict-aliasing rules Bug 316221 - G_LOCK warns about breaking strict-aliasing rules

155
docs/reference/gobject/tmpl/gboxed.sgml
View File

@ -1,155 +0,0 @@
<!-- ##### SECTION Title ##### -->
GBoxed
<!-- ##### SECTION Short_Description ##### -->
A mechanism to wrap opaque C structures registered by the type system
<!-- ##### SECTION Long_Description ##### -->
<para>
GBoxed is a generic wrapper mechanism for arbitrary C structures. The only
thing the type system needs to know about the structures is how to copy and
free them, beyond that they are treated as opaque chunks of memory.
</para>
<para>
Boxed types are useful for simple value-holder structures like rectangles or
points. They can also be used for wrapping structures defined in non-GObject
based libraries.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GParamSpecBoxed, g_param_spec_boxed()
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### USER_FUNCTION GBoxedCopyFunc ##### -->
<para>
This function is provided by the user and should produce a copy of the passed
in boxed structure.
</para>
@boxed: The boxed structure to be copied.
@Returns: The newly created copy of the boxed structure.
<!-- ##### USER_FUNCTION GBoxedFreeFunc ##### -->
<para>
This function is provided by the user and should free the boxed
structure passed.
</para>
@boxed: The boxed structure to be freed.
<!-- ##### FUNCTION g_boxed_copy ##### -->
<para>
Provide a copy of a boxed structure @src_boxed which is of type @boxed_type.
</para>
@boxed_type: The type of @src_boxed.
@src_boxed: The boxed structure to be copied.
@Returns: The newly created copy of the boxed structure.
<!-- ##### FUNCTION g_boxed_free ##### -->
<para>
Free the boxed structure @boxed which is of type @boxed_type.
</para>
@boxed_type: The type of @boxed.
@boxed: The boxed structure to be freed.
<!-- ##### FUNCTION g_boxed_type_register_static ##### -->
<para>
This function creates a new %G_TYPE_BOXED derived type id for a new
boxed type with name @name. Boxed type handling functions have to be
provided to copy and free opaque boxed structures of this type.
</para>
@name: Name of the new boxed type.
@boxed_copy: Boxed structure copy function.
@boxed_free: Boxed structure free function.
@Returns: New %G_TYPE_BOXED derived type id for @name.
<!-- ##### FUNCTION g_pointer_type_register_static ##### -->
<para>
Creates a new %G_TYPE_POINTER derived type id for a new
pointer type with name @name.
</para>
@name: the name of the new pointer type.
@Returns: a new %G_TYPE_POINTER derived type id for @name.
<!-- ##### MACRO G_TYPE_HASH_TABLE ##### -->
<para>
The #GType for a boxed type holding a #GHashTable reference.
</para>
@Since: 2.10
<!-- ##### MACRO G_TYPE_DATE ##### -->
<para>
The #GType for #GDate.
</para>
<!-- ##### MACRO G_TYPE_GSTRING ##### -->
<para>
The #GType for #GString.
</para>
<!-- ##### MACRO G_TYPE_STRV ##### -->
<para>
The #GType for a boxed type holding a %NULL-terminated array of strings.
</para>
<para>
The code fragments in the following example show the use of a property of
type #G_TYPE_STRV with g_object_class_install_property(), g_object_set()
and g_object_get().
</para>
<informalexample><programlisting>
g_object_class_install_property (object_class,
PROP_AUTHORS,
g_param_spec_boxed ("authors",
_("Authors"),
_("List of authors"),
G_TYPE_STRV,
G_PARAM_READWRITE));
gchar *authors[] = { "Owen", "Tim", NULL };
g_object_set (obj, "authors", authors, NULL);
gchar *writers[];
g_object_get (obj, "authors", &amp;writers, NULL);
/* do something with writers */
g_strfreev (writers);
</programlisting></informalexample>
@Since: 2.4
<!-- ##### MACRO G_TYPE_REGEX ##### -->
<para>
The #GType for a boxed type holding a #GRegex reference.
</para>
@Since: 2.14
<!-- ##### TYPEDEF GStrv ##### -->
<para>
A C representable type name for #G_TYPE_STRV.
</para>

42
gobject/gboxed.c
View File

@ -16,6 +16,20 @@
* Free Software Foundation, Inc., 59 Temple Place, Suite 330, * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA. * Boston, MA 02111-1307, USA.
*/ */
/**
* SECTION:GBoxed
* @Short_description: A mechanism to wrap opaque C structures registered by the type system
* @See_also:#GParamSpecBoxed, g_param_spec_boxed()
*
* GBoxed is a generic wrapper mechanism for arbitrary C structures. The only
* thing the type system needs to know about the structures is how to copy and
* free them, beyond that they are treated as opaque chunks of memory.
*
* Boxed types are useful for simple value-holder structures like rectangles or
* points. They can also be used for wrapping structures defined in non-GObject
* based libraries.
*/
#include "gboxed.h" #include "gboxed.h"
#include "gbsearcharray.h" #include "gbsearcharray.h"
@ -347,6 +361,18 @@ boxed_proxy_lcopy_value (const GValue *value,
return NULL; return NULL;
} }
/**
* g_boxed_type_register_static:
* @name: Name of the new boxed type.
* @boxed_copy: Boxed structure copy function.
* @boxed_free: Boxed structure free function.
*
* This function creates a new %G_TYPE_BOXED derived type id for a new
* boxed type with name @name. Boxed type handling functions have to be
* provided to copy and free opaque boxed structures of this type.
*
* Returns: New %G_TYPE_BOXED derived type id for @name.
*/
GType GType
g_boxed_type_register_static (const gchar *name, g_boxed_type_register_static (const gchar *name,
GBoxedCopyFunc boxed_copy, GBoxedCopyFunc boxed_copy,
@ -397,6 +423,15 @@ g_boxed_type_register_static (const gchar *name,
return type; return type;
} }
/**
* g_boxed_copy:
* @boxed_type: The type of @src_boxed.
* @src_boxed: The boxed structure to be copied.
*
* Provide a copy of a boxed structure @src_boxed which is of type @boxed_type.
*
* Returns: The newly created copy of the boxed structure.
*/
gpointer gpointer
g_boxed_copy (GType boxed_type, g_boxed_copy (GType boxed_type,
gconstpointer src_boxed) gconstpointer src_boxed)
@ -455,6 +490,13 @@ g_boxed_copy (GType boxed_type,
return dest_boxed; return dest_boxed;
} }
/**
* g_boxed_free:
* @boxed_type: The type of @boxed.
* @boxed: The boxed structure to be freed.
*
* Free the boxed structure @boxed which is of type @boxed_type.
*/
void void
g_boxed_free (GType boxed_type, g_boxed_free (GType boxed_type,
gpointer boxed) gpointer boxed)

85
gobject/gboxed.h
View File

@ -33,8 +33,25 @@ G_BEGIN_DECLS
/* --- typedefs --- */ /* --- typedefs --- */
typedef gpointer (*GBoxedCopyFunc) (gpointer boxed); /**
typedef void (*GBoxedFreeFunc) (gpointer boxed); * GBoxedCopyFunc:
* @boxed: The boxed structure to be copied.
*
* This function is provided by the user and should produce a copy of the passed
* in boxed structure.
*
* Returns: The newly created copy of the boxed structure.
*/
typedef gpointer (*GBoxedCopyFunc) (gpointer boxed);
/**
* GBoxedFreeFunc:
* @boxed: The boxed structure to be freed.
*
* This function is provided by the user and should free the boxed
* structure passed.
*/
typedef void (*GBoxedFreeFunc) (gpointer boxed);
/* --- prototypes --- */ /* --- prototypes --- */
@ -60,11 +77,66 @@ GType g_boxed_type_register_static (const gchar *name,
#define G_TYPE_CLOSURE (g_closure_get_type ()) #define G_TYPE_CLOSURE (g_closure_get_type ())
#define G_TYPE_VALUE (g_value_get_type ()) #define G_TYPE_VALUE (g_value_get_type ())
#define G_TYPE_VALUE_ARRAY (g_value_array_get_type ()) #define G_TYPE_VALUE_ARRAY (g_value_array_get_type ())
/**
* G_TYPE_DATE:
*
* The #GType for #GDate.
*/
#define G_TYPE_DATE (g_date_get_type ()) #define G_TYPE_DATE (g_date_get_type ())
/**
* G_TYPE_STRV:
*
* The #GType for a boxed type holding a %NULL-terminated array of strings.
*
* The code fragments in the following example show the use of a property of
* type #G_TYPE_STRV with g_object_class_install_property(), g_object_set()
* and g_object_get().
*
* |[
* g_object_class_install_property (object_class,
* PROP_AUTHORS,
* g_param_spec_boxed ("authors",
* _("Authors"),
* _("List of authors"),
* G_TYPE_STRV,
* G_PARAM_READWRITE));
*
*
* gchar *authors[] = { "Owen", "Tim", NULL };
* g_object_set (obj, "authors", authors, NULL);
*
*
* gchar *writers[];
* g_object_get (obj, "authors", &amp;writers, NULL);
* // do something with writers
* g_strfreev (writers);
* ]|
*
* Since: 2.4
*/
#define G_TYPE_STRV (g_strv_get_type ()) #define G_TYPE_STRV (g_strv_get_type ())
/**
* G_TYPE_GSTRING:
*
* The #GType for #GString.
*/
#define G_TYPE_GSTRING (g_gstring_get_type ()) #define G_TYPE_GSTRING (g_gstring_get_type ())
#define G_TYPE_HASH_TABLE (g_hash_table_get_type ()) /**
#define G_TYPE_REGEX (g_regex_get_type ()) * G_TYPE_HASH_TABLE:
*
* The #GType for a boxed type holding a #GHashTable reference.
*
* Since: 2.10
*/
#define G_TYPE_HASH_TABLE (g_hash_table_get_type ())
/**
* G_TYPE_REGEX:
*
* The #GType for a boxed type holding a #GRegex reference.
*
* Since: 2.14
*/
#define G_TYPE_REGEX (g_regex_get_type ())
void g_value_take_boxed (GValue *value, void g_value_take_boxed (GValue *value,
@ -82,6 +154,11 @@ GType g_gstring_get_type (void) G_GNUC_CONST;
GType g_hash_table_get_type (void) G_GNUC_CONST; GType g_hash_table_get_type (void) G_GNUC_CONST;
GType g_regex_get_type (void) G_GNUC_CONST; GType g_regex_get_type (void) G_GNUC_CONST;
/**
* GStrv:
*
* A C representable type name for #G_TYPE_STRV.
*/
typedef gchar** GStrv; typedef gchar** GStrv;
G_END_DECLS G_END_DECLS

9
gobject/gvaluetypes.c
View File

@ -915,6 +915,15 @@ g_strdup_value_contents (const GValue *value)
return contents; return contents;
} }
/**
* g_pointer_type_register_static:
* @name: the name of the new pointer type.
*
* Creates a new %G_TYPE_POINTER derived type id for a new
* pointer type with name @name.
*
* Returns: a new %G_TYPE_POINTER derived type id for @name.
*/
GType GType
g_pointer_type_register_static (const gchar *name) g_pointer_type_register_static (const gchar *name)
{ {