1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
6
<meta name="generator" content="DocBook XSL Stylesheets V1.72.0">
7
<link rel="start" href="index.html" title="GObject Reference Manual">
8
<link rel="up" href="rn01.html" title="API Reference">
9
<link rel="prev" href="gobject-Enumeration-and-Flag-Types.html" title="Enums and Flags">
10
<link rel="next" href="gobject-Generic-values.html" title="Generic Values">
11
<meta name="generator" content="GTK-Doc V1.7 (XML mode)">
12
<link rel="stylesheet" href="style.css" type="text/css">
13
<link rel="preface" href="pr01.html" title="Introduction">
14
<link rel="part" href="pt01.html" title="Part I. Concepts">
15
<link rel="chapter" href="ch01.html" title="Background">
16
<link rel="chapter" href="ch02.html" title="The Glib Dynamic Type System">
17
<link rel="chapter" href="chapter-gobject.html" title="The GObject base class">
18
<link rel="chapter" href="chapter-signal.html" title="The GObject messaging system">
19
<link rel="reference" href="rn01.html" title="API Reference">
20
<link rel="reference" href="rn02.html" title="Tools Reference">
21
<link rel="part" href="pt02.html" title="Part IV. Tutorial">
22
<link rel="chapter" href="howto-gobject.html" title="How To define and implement a new GObject?">
23
<link rel="chapter" href="howto-interface.html" title="How To define and implement Interfaces?">
24
<link rel="chapter" href="howto-signals.html" title="Howto create and use signals">
25
<link rel="part" href="pt03.html" title="Part V. Related Tools">
26
<link rel="chapter" href="tools-gob.html" title="GObject builder">
27
<link rel="chapter" href="tools-ginspector.html" title="Graphical inspection of Gobjects">
28
<link rel="chapter" href="tools-refdb.html" title="Debugging reference count problems">
29
<link rel="chapter" href="tools-gtkdoc.html" title="Writing API docs">
30
<link rel="index" href="ix01.html" title="Index">
31
<link rel="index" href="ix02.html" title="Index of deprecated symbols">
32
<link rel="index" href="ix03.html" title="Index of new symbols in 2.2">
33
<link rel="index" href="ix04.html" title="Index of new symbols in 2.4">
34
<link rel="index" href="ix05.html" title="Index of new symbols in 2.6">
35
<link rel="index" href="ix06.html" title="Index of new symbols in 2.8">
36
<link rel="index" href="ix07.html" title="Index of new symbols in 2.10">
37
<link rel="index" href="ix08.html" title="Index of new symbols in 2.12">
39
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
40
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
42
<td><a accesskey="p" href="gobject-Enumeration-and-Flag-Types.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
43
<td><a accesskey="u" href="rn01.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
44
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
45
<th width="100%" align="center">GObject Reference Manual</th>
46
<td><a accesskey="n" href="gobject-Generic-values.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
48
<tr><td colspan="5" class="shortcuts"><nobr><a href="#id3086271" class="shortcut">Top</a>
50
<a href="#id3086499" class="shortcut">Description</a></nobr></td></tr>
52
<div class="refentry" lang="en">
53
<a name="gobject-Boxed-Types"></a><div class="titlepage"></div>
54
<div class="refnamediv"><table width="100%"><tr>
57
<a name="id3086271"></a><span class="refentrytitle">GBoxed</span>
59
<p>GBoxed — A mechanism to wrap opaque C structures registered by the type system</p>
61
<td valign="top" align="right"></td>
63
<div class="refsynopsisdiv">
65
<pre class="synopsis">
67
#include <glib-object.h>
71
href="../glib/glib-Basic-Types.html#gpointer"
72
>gpointer</a> (<a href="gobject-Boxed-Types.html#GBoxedCopyFunc">*GBoxedCopyFunc</a>) (<a
73
href="../glib/glib-Basic-Types.html#gpointer"
75
void (<a href="gobject-Boxed-Types.html#GBoxedFreeFunc">*GBoxedFreeFunc</a>) (<a
76
href="../glib/glib-Basic-Types.html#gpointer"
79
href="../glib/glib-Basic-Types.html#gpointer"
80
>gpointer</a> <a href="gobject-Boxed-Types.html#g-boxed-copy">g_boxed_copy</a> (<a href="gobject-Type-Information.html#GType">GType</a> boxed_type,
82
href="../glib/glib-Basic-Types.html#gconstpointer"
83
>gconstpointer</a> src_boxed);
84
void <a href="gobject-Boxed-Types.html#g-boxed-free">g_boxed_free</a> (<a href="gobject-Type-Information.html#GType">GType</a> boxed_type,
86
href="../glib/glib-Basic-Types.html#gpointer"
88
<a href="gobject-Type-Information.html#GType">GType</a> <a href="gobject-Boxed-Types.html#g-boxed-type-register-static">g_boxed_type_register_static</a> (const <a
89
href="../glib/glib-Basic-Types.html#gchar"
91
<a href="gobject-Boxed-Types.html#GBoxedCopyFunc">GBoxedCopyFunc</a> boxed_copy,
92
<a href="gobject-Boxed-Types.html#GBoxedFreeFunc">GBoxedFreeFunc</a> boxed_free);
93
<a href="gobject-Type-Information.html#GType">GType</a> <a href="gobject-Boxed-Types.html#g-pointer-type-register-static">g_pointer_type_register_static</a> (const <a
94
href="../glib/glib-Basic-Types.html#gchar"
97
#define <a href="gobject-Boxed-Types.html#G-TYPE-HASH-TABLE:CAPS">G_TYPE_HASH_TABLE</a>
98
#define <a href="gobject-Boxed-Types.html#G-TYPE-DATE:CAPS">G_TYPE_DATE</a>
99
#define <a href="gobject-Boxed-Types.html#G-TYPE-GSTRING:CAPS">G_TYPE_GSTRING</a>
100
#define <a href="gobject-Boxed-Types.html#G-TYPE-STRV:CAPS">G_TYPE_STRV</a>
101
typedef <a href="gobject-Boxed-Types.html#GStrv">GStrv</a>;
106
<div class="refsect1" lang="en">
107
<a name="id3086499"></a><h2>Description</h2>
109
GBoxed is a generic wrapper mechanism for arbitrary C structures. The only
110
thing the type system needs to know about the structures is how to copy and
111
free them, beyond that they are treated as opaque chunks of memory.
114
Boxed types are useful for simple value-holder structures like rectangles or
115
points. They can also be used for wrapping structures defined in non-GObject
119
<div class="refsect1" lang="en">
120
<a name="id3086524"></a><h2>Details</h2>
121
<div class="refsect2" lang="en">
122
<a name="id3086534"></a><h3>
123
<a name="GBoxedCopyFunc"></a>GBoxedCopyFunc ()</h3>
124
<a class="indexterm" name="id3086547"></a><pre class="programlisting"><a
125
href="../glib/glib-Basic-Types.html#gpointer"
126
>gpointer</a> (*GBoxedCopyFunc) (<a
127
href="../glib/glib-Basic-Types.html#gpointer"
128
>gpointer</a> boxed);</pre>
130
This function is provided by the user and should produce a copy of the passed
133
<div class="variablelist"><table border="0">
134
<col align="left" valign="top">
137
<td><span class="term"><em class="parameter"><code>boxed</code></em> :</span></td>
138
<td> The boxed structure to be copied.
142
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
143
<td>The newly created copy of the boxed structure.
152
<div class="refsect2" lang="en">
153
<a name="id3086606"></a><h3>
154
<a name="GBoxedFreeFunc"></a>GBoxedFreeFunc ()</h3>
155
<a class="indexterm" name="id3086619"></a><pre class="programlisting">void (*GBoxedFreeFunc) (<a
156
href="../glib/glib-Basic-Types.html#gpointer"
157
>gpointer</a> boxed);</pre>
159
This function is provided by the user and should free the boxed
162
<div class="variablelist"><table border="0">
163
<col align="left" valign="top">
165
<td><span class="term"><em class="parameter"><code>boxed</code></em> :</span></td>
166
<td>The boxed structure to be freed.
174
<div class="refsect2" lang="en">
175
<a name="id3086668"></a><h3>
176
<a name="g-boxed-copy"></a>g_boxed_copy ()</h3>
177
<a class="indexterm" name="id3086680"></a><pre class="programlisting"><a
178
href="../glib/glib-Basic-Types.html#gpointer"
179
>gpointer</a> g_boxed_copy (<a href="gobject-Type-Information.html#GType">GType</a> boxed_type,
181
href="../glib/glib-Basic-Types.html#gconstpointer"
182
>gconstpointer</a> src_boxed);</pre>
184
Provide a copy of a boxed structure <em class="parameter"><code>src_boxed</code></em> which is of type <em class="parameter"><code>boxed_type</code></em>.
186
<div class="variablelist"><table border="0">
187
<col align="left" valign="top">
190
<td><span class="term"><em class="parameter"><code>boxed_type</code></em> :</span></td>
191
<td>The type of <em class="parameter"><code>src_boxed</code></em>.
195
<td><span class="term"><em class="parameter"><code>src_boxed</code></em> :</span></td>
196
<td> The boxed structure to be copied.
200
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
201
<td> The newly created copy of the boxed structure.
210
<div class="refsect2" lang="en">
211
<a name="id3086779"></a><h3>
212
<a name="g-boxed-free"></a>g_boxed_free ()</h3>
213
<a class="indexterm" name="id3086792"></a><pre class="programlisting">void g_boxed_free (<a href="gobject-Type-Information.html#GType">GType</a> boxed_type,
215
href="../glib/glib-Basic-Types.html#gpointer"
216
>gpointer</a> boxed);</pre>
218
Free the boxed structure <em class="parameter"><code>boxed</code></em> which is of type <em class="parameter"><code>boxed_type</code></em>.
220
<div class="variablelist"><table border="0">
221
<col align="left" valign="top">
224
<td><span class="term"><em class="parameter"><code>boxed_type</code></em> :</span></td>
225
<td>The type of <em class="parameter"><code>boxed</code></em>.
229
<td><span class="term"><em class="parameter"><code>boxed</code></em> :</span></td>
230
<td> The boxed structure to be freed.
239
<div class="refsect2" lang="en">
240
<a name="id3086878"></a><h3>
241
<a name="g-boxed-type-register-static"></a>g_boxed_type_register_static ()</h3>
242
<a class="indexterm" name="id3086892"></a><pre class="programlisting"><a href="gobject-Type-Information.html#GType">GType</a> g_boxed_type_register_static (const <a
243
href="../glib/glib-Basic-Types.html#gchar"
245
<a href="gobject-Boxed-Types.html#GBoxedCopyFunc">GBoxedCopyFunc</a> boxed_copy,
246
<a href="gobject-Boxed-Types.html#GBoxedFreeFunc">GBoxedFreeFunc</a> boxed_free);</pre>
248
This function creates a new <a href="gobject-Type-Information.html#G-TYPE-BOXED:CAPS"><code class="literal">G_TYPE_BOXED</code></a> derived type id for a new
249
boxed type with name <em class="parameter"><code>name</code></em>. Boxed type handling functions have to be
250
provided to copy and free opaque boxed structures of this type.
252
<div class="variablelist"><table border="0">
253
<col align="left" valign="top">
256
<td><span class="term"><em class="parameter"><code>name</code></em> :</span></td>
257
<td>Name of the new boxed type.
261
<td><span class="term"><em class="parameter"><code>boxed_copy</code></em> :</span></td>
262
<td>Boxed structure copy function.
266
<td><span class="term"><em class="parameter"><code>boxed_free</code></em> :</span></td>
267
<td>Boxed structure free function.
271
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
272
<td>New <a href="gobject-Type-Information.html#G-TYPE-BOXED:CAPS"><code class="literal">G_TYPE_BOXED</code></a> derived type id for <em class="parameter"><code>name</code></em>.
281
<div class="refsect2" lang="en">
282
<a name="id3087031"></a><h3>
283
<a name="g-pointer-type-register-static"></a>g_pointer_type_register_static ()</h3>
284
<a class="indexterm" name="id3087045"></a><pre class="programlisting"><a href="gobject-Type-Information.html#GType">GType</a> g_pointer_type_register_static (const <a
285
href="../glib/glib-Basic-Types.html#gchar"
286
>gchar</a> *name);</pre>
288
Creates a new <a href="gobject-Type-Information.html#G-TYPE-POINTER:CAPS"><code class="literal">G_TYPE_POINTER</code></a> derived type id for a new
289
pointer type with name <em class="parameter"><code>name</code></em>.
291
<div class="variablelist"><table border="0">
292
<col align="left" valign="top">
295
<td><span class="term"><em class="parameter"><code>name</code></em> :</span></td>
296
<td>the name of the new pointer type.
300
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
301
<td>a new <a href="gobject-Type-Information.html#G-TYPE-POINTER:CAPS"><code class="literal">G_TYPE_POINTER</code></a> derived type id for <em class="parameter"><code>name</code></em>.
310
<div class="refsect2" lang="en">
311
<a name="id3087137"></a><h3>
312
<a name="G-TYPE-HASH-TABLE:CAPS"></a>G_TYPE_HASH_TABLE</h3>
313
<a class="indexterm" name="id3087153"></a><pre class="programlisting">#define G_TYPE_HASH_TABLE (g_hash_table_get_type ())
316
The <a href="gobject-Type-Information.html#GType"><span class="type">GType</span></a> for a boxed type holding a <a
317
href="../glib/glib-Hash-Tables.html#GHashTable"
318
><span class="type">GHashTable</span></a> reference.
320
<p class="since">Since 2.10
326
<div class="refsect2" lang="en">
327
<a name="id3087193"></a><h3>
328
<a name="G-TYPE-DATE:CAPS"></a>G_TYPE_DATE</h3>
329
<a class="indexterm" name="id3087206"></a><pre class="programlisting">#define G_TYPE_DATE (g_date_get_type ())
332
The <a href="gobject-Type-Information.html#GType"><span class="type">GType</span></a> for <a
333
href="../glib/glib-Date-and-Time-Functions.html#GDate"
334
><span class="type">GDate</span></a>.
338
<div class="refsect2" lang="en">
339
<a name="id3087238"></a><h3>
340
<a name="G-TYPE-GSTRING:CAPS"></a>G_TYPE_GSTRING</h3>
341
<a class="indexterm" name="id3087251"></a><pre class="programlisting">#define G_TYPE_GSTRING (g_gstring_get_type ())
344
The <a href="gobject-Type-Information.html#GType"><span class="type">GType</span></a> for <a
345
href="../glib/glib-Strings.html#GString"
346
><span class="type">GString</span></a>.
350
<div class="refsect2" lang="en">
351
<a name="id3087284"></a><h3>
352
<a name="G-TYPE-STRV:CAPS"></a>G_TYPE_STRV</h3>
353
<a class="indexterm" name="id3087299"></a><pre class="programlisting">#define G_TYPE_STRV (g_strv_get_type ())
356
The <a href="gobject-Type-Information.html#GType"><span class="type">GType</span></a> for a boxed type holding a <a
357
href="../glib/glib-Standard-Macros.html#NULL:CAPS"
358
><code class="literal">NULL</code></a>-terminated array of strings.
361
The code fragments in the following example show the use of a property of
362
type <a href="gobject-Boxed-Types.html#G-TYPE-STRV:CAPS"><span class="type">G_TYPE_STRV</span></a> with <a href="gobject-The-Base-Object-Type.html#g-object-class-install-property"><code class="function">g_object_class_install_property()</code></a>, <a href="gobject-The-Base-Object-Type.html#g-object-set"><code class="function">g_object_set()</code></a>
363
and <a href="gobject-The-Base-Object-Type.html#g-object-get"><code class="function">g_object_get()</code></a>.
365
<div class="informalexample"><pre class="programlisting">
366
g_object_class_install_property (object_class,
368
g_param_spec_boxed ("authors",
370
_("List of authors"),
375
gchar *authors[] = { "Owen", "Tim", NULL };
376
g_object_set (obj, "authors", authors, NULL);
380
g_object_get (obj, "authors", &writers, NULL);
381
/* do something with writers */
382
g_strfreev (writers);
384
<p class="since">Since 2.4
390
<div class="refsect2" lang="en">
391
<a name="id3087392"></a><h3>
392
<a name="GStrv"></a>GStrv</h3>
393
<a class="indexterm" name="id3086148"></a><pre class="programlisting">typedef gchar** GStrv;
396
A C representable type name for <a href="gobject-Boxed-Types.html#G-TYPE-STRV:CAPS"><span class="type">G_TYPE_STRV</span></a>.
400
<div class="refsect1" lang="en">
401
<a name="id3086173"></a><h2>See Also</h2>
403
<a href="gobject-Standard-Parameter-and-Value-Types.html#GParamSpecBoxed"><span class="type">GParamSpecBoxed</span></a>, <a href="gobject-Standard-Parameter-and-Value-Types.html#g-param-spec-boxed"><code class="function">g_param_spec_boxed()</code></a>
added
removed
docs/reference/gobject/html/gobject-Boxed-Types.html
