glib/docs/reference/gobject/tmpl/gboxed.sgml

<!-- ##### 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_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


<!-- ##### TYPEDEF GStrv ##### -->
<para>
A C representable type name for #G_TYPE_STRV.
</para>