## Boxed Types

Boxed Types — A mechanism to wrap opaque C structures registered by the type system

## Synopsis

    #include <glib-object.h>

    gpointer            (*GBoxedCopyFunc)                   (gpointer boxed);
    void                (*GBoxedFreeFunc)                   (gpointer boxed);
    gpointer            g_boxed_copy                        (GType boxed_type,
                                                             gconstpointer src_boxed);
    void                g_boxed_free                        (GType boxed_type,
                                                             gpointer boxed);
    GType               g_boxed_type_register_static        (const gchar *name,
                                                             GBoxedCopyFunc boxed_copy,
                                                             GBoxedFreeFunc boxed_free);
    GType               g_pointer_type_register_static      (const gchar *name);

    #define             G_TYPE_HASH_TABLE
    #define             G_TYPE_DATE
    #define             G_TYPE_GSTRING
    #define             G_TYPE_STRV
    #define             G_TYPE_REGEX
    #define             G_TYPE_ARRAY
    #define             G_TYPE_BYTE_ARRAY
    #define             G_TYPE_PTR_ARRAY
    #define             G_TYPE_VARIANT_TYPE
    #define             G_TYPE_ERROR
    #define             G_TYPE_DATE_TIME
    typedef             GStrv;

## Description

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.

## Details

### GBoxedCopyFunc ()

    gpointer            (*GBoxedCopyFunc)                   (gpointer boxed);

This function is provided by the user and should produce a copy of the passed in boxed structure.

`boxed` : | The boxed structure to be copied.
Returns : | The newly created copy of the boxed structure.

### GBoxedFreeFunc ()

    void                (*GBoxedFreeFunc)                   (gpointer boxed);

This function is provided by the user and should free the boxed structure passed.

`boxed` : | The boxed structure to be freed.

### g_boxed_copy ()

    gpointer            g_boxed_copy                        (GType boxed_type,
                                                             gconstpointer src_boxed);

Provide a copy of a boxed structure `src_boxed` which is of type `boxed_type`.

`boxed_type` : | The type of `src_boxed`.
`src_boxed` : | The boxed structure to be copied.
Returns : | The newly created copy of the boxed structure.

### g_boxed_free ()

    void                g_boxed_free                        (GType boxed_type,
                                                             gpointer boxed);

Free the boxed structure `boxed` which is of type `boxed_type`.

`boxed_type` : | The type of `boxed`.
`boxed` : | The boxed structure to be freed.

### g_boxed_type_register_static ()

    GType               g_boxed_type_register_static        (const gchar *name,
                                                             GBoxedCopyFunc boxed_copy,
                                                             GBoxedFreeFunc boxed_free);

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.

`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`.

### g_pointer_type_register_static ()

    GType               g_pointer_type_register_static      (const gchar *name);

Creates a new `G_TYPE_POINTER` derived type id for a new pointer type with name `name`.

`name` : | the name of the new pointer type.
Returns : | a new `G_TYPE_POINTER` derived type id for `name`.

### G_TYPE_HASH_TABLE

    #define G_TYPE_HASH_TABLE (g_hash_table_get_type ())

The GType for a boxed type holding a GHashTable reference.

Since 2.10

### G_TYPE_DATE

    #define G_TYPE_DATE	        (g_date_get_type ())

The GType for GDate.

### G_TYPE_GSTRING

    #define G_TYPE_GSTRING		(g_gstring_get_type ())

The GType for GString.

### G_TYPE_STRV

    #define G_TYPE_STRV	        (g_strv_get_type ())

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()`.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17

    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", &writers, NULL);
    // do something with writers
    g_strfreev (writers);

Since 2.4

### G_TYPE_REGEX

    #define G_TYPE_REGEX (g_regex_get_type ())

The GType for a boxed type holding a GRegex reference.

Since 2.14

### G_TYPE_ARRAY

    #define G_TYPE_ARRAY (g_array_get_type ())

The GType for a boxed type holding a GArray reference.

Since 2.22

### G_TYPE_BYTE_ARRAY

    #define G_TYPE_BYTE_ARRAY (g_byte_array_get_type ())

The GType for a boxed type holding a GByteArray reference.

Since 2.22

### G_TYPE_PTR_ARRAY

    #define G_TYPE_PTR_ARRAY (g_ptr_array_get_type ())

The GType for a boxed type holding a GPtrArray reference.

Since 2.22

### G_TYPE_VARIANT_TYPE

    #define G_TYPE_VARIANT_TYPE (g_variant_type_get_gtype ())

The GType for a boxed type holding a GVariantType.

Since 2.24

### G_TYPE_ERROR

    #define G_TYPE_ERROR (g_error_get_type ())

The GType for a boxed type holding a GError.

Since 2.26

### G_TYPE_DATE_TIME

    #define G_TYPE_DATE_TIME (g_date_time_get_type ())

The GType for a boxed type holding a GDateTime.

Since 2.26

### GStrv

    typedef gchar** GStrv;

A C representable type name for G_TYPE_STRV.

## See Also

GParamSpecBoxed, `g_param_spec_boxed()`