Boxed Types

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

Functions

Types and Values

Includes

#include <glib-object.h>

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

GBoxed is 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().

Functions

GBoxedCopyFunc ()

gpointer
(*GBoxedCopyFunc) (gpointer boxed);

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

Parameters

boxed

The boxed structure to be copied.

[not nullable]

Returns

The newly created copy of the boxed structure.

[not nullable]


GBoxedFreeFunc ()

void
(*GBoxedFreeFunc) (gpointer boxed);

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

Parameters

boxed

The boxed structure to be freed.

[not nullable]

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 .

Parameters

boxed_type

The type of src_boxed .

 

src_boxed

The boxed structure to be copied.

[not nullable]

Returns

The newly created copy of the boxed structure.

[transfer full][not nullable]


g_boxed_free ()

void
g_boxed_free (GType boxed_type,
              gpointer boxed);

Free the boxed structure boxed which is of type boxed_type .

Parameters

boxed_type

The type of boxed .

 

boxed

The boxed structure to be freed.

[not nullable]

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.

For the general case, it is recommended to use G_DEFINE_BOXED_TYPE() instead of calling g_boxed_type_register_static() directly. The macro will create the appropriate *_get_type() function for the boxed type.

Parameters

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 .

Parameters

name

the name of the new pointer type.

 

Returns

a new G_TYPE_POINTER derived type id for name .

Types and Values

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
g_object_class_install_property (object_class,
                                 PROP_AUTHORS,
                                 g_param_spec_boxed ("authors",
                                                     _("Authors"),
                                                     _("List of authors"),
                                                     G_TYPE_STRV,
                                                     G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));

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_MATCH_INFO

#define G_TYPE_MATCH_INFO (g_match_info_get_type ())

The GType for a boxed type holding a GMatchInfo reference.

Since: 2.30


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_BYTES

#define G_TYPE_BYTES (g_bytes_get_type ())

The GType for GBytes.

Since: 2.32


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


G_TYPE_TIME_ZONE

#define G_TYPE_TIME_ZONE (g_time_zone_get_type ())

The GType for a boxed type holding a GTimeZone.

Since: 2.34


G_TYPE_IO_CHANNEL

#define G_TYPE_IO_CHANNEL (g_io_channel_get_type ())

The GType for GIOChannel.


G_TYPE_IO_CONDITION

#define G_TYPE_IO_CONDITION (g_io_condition_get_type ())

The GType for GIOCondition.


G_TYPE_VARIANT_BUILDER

#define G_TYPE_VARIANT_BUILDER (g_variant_builder_get_type ())

The GType for a boxed type holding a GVariantBuilder.

Since: 2.30


G_TYPE_VARIANT_DICT

#define G_TYPE_VARIANT_DICT (g_variant_dict_get_type ())

The GType for a boxed type holding a GVariantDict.

Since: 2.40


G_TYPE_KEY_FILE

#define G_TYPE_KEY_FILE (g_key_file_get_type ())

The GType for a boxed type holding a GKeyFile.

Since: 2.32


G_TYPE_MAIN_CONTEXT

#define G_TYPE_MAIN_CONTEXT (g_main_context_get_type ())

The GType for a boxed type holding a GMainContext.

Since: 2.30


G_TYPE_MAIN_LOOP

#define G_TYPE_MAIN_LOOP (g_main_loop_get_type ())

The GType for a boxed type holding a GMainLoop.

Since: 2.30


G_TYPE_MAPPED_FILE

#define G_TYPE_MAPPED_FILE (g_mapped_file_get_type ())

The GType for a boxed type holding a GMappedFile.

Since: 2.40


G_TYPE_MARKUP_PARSE_CONTEXT

#define G_TYPE_MARKUP_PARSE_CONTEXT (g_markup_parse_context_get_type ())

The GType for a boxed type holding a GMarkupParseContext.

Since: 2.36


G_TYPE_SOURCE

#define G_TYPE_SOURCE (g_source_get_type ())

The GType for a boxed type holding a GSource.

Since: 2.30


G_TYPE_POLLFD

#define G_TYPE_POLLFD (g_pollfd_get_type ())

The GType for a boxed type holding a GPollFD.

Since: 2.36


G_TYPE_THREAD

#define G_TYPE_THREAD (g_thread_get_type ())

The GType for a boxed type holding a GThread.

Since: 2.36


G_TYPE_OPTION_GROUP

#define G_TYPE_OPTION_GROUP (g_option_group_get_type ())

The GType for a boxed type holding a GOptionGroup.

Since: 2.44


G_TYPE_URI

#define G_TYPE_URI (g_uri_get_type ())

The GType for a boxed type holding a GUri.

Since: 2.66


G_TYPE_TREE

#define G_TYPE_TREE (g_tree_get_type ())

The GType for GTree.

Since: 2.68


G_TYPE_PATTERN_SPEC

#define G_TYPE_PATTERN_SPEC (g_pattern_spec_get_type ())

The GType for GPatternSpec.

Since: 2.70

See Also

GParamSpecBoxed, g_param_spec_boxed()