~ubuntu-branches/debian/jessie/glib2.0/jessie

« back to all changes in this revision

Viewing changes to docs/reference/gobject/tmpl/gboxed.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Gustavo Noronha Silva
  • Date: 2009-02-15 13:00:43 UTC
  • mfrom: (1.3.1 upstream) (69.1.10 intrepid)
  • Revision ID: james.westby@ubuntu.com-20090215130043-q47fbt3owmt42m2f
Tags: 2.18.4-2
* Release to unstable
* debian/rules:
- bump SHVER, since we are already forcing a 2.18.0 dependecy on the
  symbols introduced in the development versions
* debian/control.in:
- added Homepage and Vcs-* control fields

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
1
<!-- ##### SECTION Title ##### -->
2
 
GBoxed
 
2
Boxed Types
3
3
 
4
4
<!-- ##### SECTION Short_Description ##### -->
5
 
A mechanism to wrap opaque C structures registered by the type system
 
5
 
6
6
 
7
7
<!-- ##### SECTION Long_Description ##### -->
8
8
<para>
9
 
GBoxed is a generic wrapper mechanism for arbitrary C structures. The only
10
 
thing the type system needs to know about the structures is how to copy and
11
 
free them, beyond that they are treated as opaque chunks of memory.
12
 
</para>
13
 
<para>
14
 
Boxed types are useful for simple value-holder structures like rectangles or
15
 
points. They can also be used for wrapping structures defined in non-GObject
16
 
based libraries.
17
 
</para>
 
9
 
 
10
</para>
 
11
 
18
12
 
19
13
<!-- ##### SECTION See_Also ##### -->
20
14
<para>
21
 
#GParamSpecBoxed, g_param_spec_boxed()
 
15
 
22
16
</para>
23
17
 
 
18
 
24
19
<!-- ##### SECTION Stability_Level ##### -->
25
20
 
26
21
 
27
22
<!-- ##### USER_FUNCTION GBoxedCopyFunc ##### -->
28
23
<para>
29
 
This function is provided by the user and should produce a copy of the passed
30
 
in boxed structure.
 
24
 
31
25
</para>
32
26
 
33
 
@boxed:   The boxed structure to be copied.
34
 
@Returns: The newly created copy of the boxed structure.
 
27
@boxed: 
 
28
@Returns: 
35
29
 
36
30
 
37
31
<!-- ##### USER_FUNCTION GBoxedFreeFunc ##### -->
38
32
<para>
39
 
This function is provided by the user and should free the boxed
40
 
structure passed.
 
33
 
41
34
</para>
42
35
 
43
 
@boxed: The boxed structure to be freed.
 
36
@boxed: 
44
37
 
45
38
 
46
39
<!-- ##### FUNCTION g_boxed_copy ##### -->
47
40
<para>
48
 
Provide a copy of a boxed structure @src_boxed which is of type @boxed_type.
 
41
 
49
42
</para>
50
43
 
51
 
@boxed_type: The type of @src_boxed.
52
 
@src_boxed:  The boxed structure to be copied.
53
 
@Returns:    The newly created copy of the boxed structure.
 
44
@boxed_type: 
 
45
@src_boxed: 
 
46
@Returns: 
54
47
 
55
48
 
56
49
<!-- ##### FUNCTION g_boxed_free ##### -->
57
50
<para>
58
 
Free the boxed structure @boxed which is of type @boxed_type.
 
51
 
59
52
</para>
60
53
 
61
 
@boxed_type: The type of @boxed.
62
 
@boxed:      The boxed structure to be freed.
 
54
@boxed_type: 
 
55
@boxed: 
63
56
 
64
57
 
65
58
<!-- ##### FUNCTION g_boxed_type_register_static ##### -->
66
59
<para>
67
 
This function creates a new %G_TYPE_BOXED derived type id for a new
68
 
boxed type with name @name. Boxed type handling functions have to be
69
 
provided to copy and free opaque boxed structures of this type.
 
60
 
70
61
</para>
71
62
 
72
 
@name: Name of the new boxed type.
73
 
@boxed_copy: Boxed structure copy function.
74
 
@boxed_free: Boxed structure free function.
75
 
@Returns: New %G_TYPE_BOXED derived type id for @name.
 
63
@name: 
 
64
@boxed_copy: 
 
65
@boxed_free: 
 
66
@Returns: 
76
67
 
77
68
 
78
69
<!-- ##### FUNCTION g_pointer_type_register_static ##### -->
79
70
<para>
80
 
Creates a new %G_TYPE_POINTER derived type id for a new
81
 
pointer type with name @name. 
 
71
 
82
72
</para>
83
73
 
84
 
@name: the name of the new pointer type.
85
 
@Returns: a new %G_TYPE_POINTER derived type id for @name.
 
74
@name: 
 
75
@Returns: 
86
76
 
87
77
 
88
78
<!-- ##### MACRO G_TYPE_HASH_TABLE ##### -->
89
79
<para>
90
 
The #GType for a boxed type holding a #GHashTable reference.
 
80
 
91
81
</para>
92
82
 
93
 
@Since: 2.10
94
83
 
95
84
 
96
85
<!-- ##### MACRO G_TYPE_DATE ##### -->
97
86
<para>
98
 
The #GType for #GDate.
 
87
 
99
88
</para>
100
89
 
101
90
 
102
91
 
103
92
<!-- ##### MACRO G_TYPE_GSTRING ##### -->
104
93
<para>
105
 
The #GType for #GString.
 
94
 
106
95
</para>
107
96
 
108
97
 
109
98
 
110
99
<!-- ##### MACRO G_TYPE_STRV ##### -->
111
100
<para>
112
 
The #GType for a boxed type holding a %NULL-terminated array of strings.
113
 
</para>
114
 
<para>
115
 
The code fragments in the following example show the use of a property of
116
 
type #G_TYPE_STRV with g_object_class_install_property(), g_object_set()
117
 
and g_object_get().
118
 
</para>
119
 
<informalexample><programlisting>
120
 
g_object_class_install_property (object_class,
121
 
                                 PROP_AUTHORS,
122
 
                                 g_param_spec_boxed ("authors",
123
 
                                                     _("Authors"),
124
 
                                                     _("List of authors"),
125
 
                                                     G_TYPE_STRV,
126
 
                                                     G_PARAM_READWRITE));
127
 
 
128
 
 
129
 
gchar *authors[] = { "Owen", "Tim", NULL };
130
 
g_object_set (obj, "authors", authors, NULL);
131
 
 
132
 
 
133
 
gchar *writers[];
134
 
g_object_get (obj, "authors", &amp;writers, NULL);
135
 
/* do something with writers */
136
 
g_strfreev (writers);
137
 
</programlisting></informalexample>
138
 
 
139
 
@Since: 2.4
 
101
 
 
102
</para>
 
103
 
140
104
 
141
105
 
142
106
<!-- ##### MACRO G_TYPE_REGEX ##### -->
143
107
<para>
144
 
The #GType for a boxed type holding a #GRegex reference.
 
108
 
145
109
</para>
146
110
 
147
 
@Since: 2.14
148
111
 
149
112
 
150
113
<!-- ##### TYPEDEF GStrv ##### -->
151
114
<para>
152
 
A C representable type name for #G_TYPE_STRV.
 
115
 
153
116
</para>
154
117
 
155
118