GObject – 2.0: Boxed Types
Description: Reference for GObject-2.0: Boxed Types

#### Boxed Types

A “boxed type” 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 them (a `GBoxedCopyFunc`) and how to free them (a `GBoxedFreeFunc`)—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. They allow arbitrary structures to be handled in a uniform way, allowing uniform copying (or referencing) and freeing (or unreferencing) of them, and uniform representation of the type of the contained structure. In turn, this allows any type which can be boxed to be set as the data in a `GValue`, which allows for polymorphic handling of a much wider range of data types, and hence usage of such types as `GObject` property values.

All boxed types inherit from the `G_TYPE_BOXED` fundamental type.

It is very important to note that boxed types are not deeply inheritable: you cannot register a boxed type that inherits from another boxed type. This means you cannot create your own custom, parallel type hierarchy and map it to GType using boxed types. If you want to have deeply inheritable types without using GObject, you will need to use `GTypeInstance`.

## Registering a new boxed type

The recommended way to register a new boxed type is to use the `G_DEFINE_BOXED_TYPE()` macro:

    // In the header

    #define EXAMPLE_TYPE_RECTANGLE (example_rectangle_get_type())

    typedef struct {
      double x, y;
      double width, height;
    } ExampleRectangle;

    GType
    example_rectangle_get_type (void);

    ExampleRectangle *
    example_rectangle_copy (ExampleRectangle *r);

    void
    example_rectangle_free (ExampleRectangle *r);

    // In the source
    G_DEFINE_BOXED_TYPE (ExampleRectangle, example_rectangle,
                         example_rectangle_copy,
                         example_rectangle_free)

Just like `G_DEFINE_TYPE` and `G_DEFINE_INTERFACE_TYPE`, the `G_DEFINE_BOXED_TYPE` macro will provide the definition of the `get_type()` function, which will call `g_boxed_type_register_static()` with the given type name as well as the `GBoxedCopyFunc` and `GBoxedFreeFunc` functions.

## Using boxed types

### Object properties

In order to use a boxed type with GObject properties you will need to register the property using `g_param_spec_boxed()`, e.g.

    obj_props[PROP_BOUNDS] =
      g_param_spec_boxed ("bounds", NULL, NULL,
                          EXAMPLE_TYPE_RECTANGLE,
                          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);

In the `set_property` implementation you can use `g_value_get_boxed()` to retrieve a pointer to the boxed type:

    switch (prop_id)
      {
      // ...
      case PROP_BOUNDS:
        example_object_set_bounds (self, g_value_get_boxed (value));
        break;
      // ...
      }

Similarly, you can use `g_value_set_boxed()` in the implementation of the `get_property` virtual function:

    switch (prop_id)
      {
      // ...
      case PROP_BOUNDS:
        g_value_set_boxed (self, &self->bounds);
        break;
      // ...
      }

## Reference counting

Boxed types are designed so that reference counted types can be boxed. Use the type’s ‘ref’ function as the `GBoxedCopyFunc`, and its ‘unref’ function as the `GBoxedFreeFunc`. For example, for `GBytes`, the `GBoxedCopyFunc` is `g_bytes_ref()`, and the GBoxedFreeFunc is `g_bytes_unref()`.