1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module glib.VariantBuilder;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import glib.Variant;
30 private import glib.VariantType;
31 private import glib.c.functions;
32 public  import glib.c.types;
33 public  import gtkc.glibtypes;
34 private import gtkd.Loader;
35 
36 
37 /**
38  * A utility type for constructing container-type #GVariant instances.
39  * 
40  * This is an opaque structure and may only be accessed using the
41  * following functions.
42  * 
43  * #GVariantBuilder is not threadsafe in any way.  Do not attempt to
44  * access it from more than one thread.
45  */
46 public class VariantBuilder
47 {
48 	/** the main Gtk struct */
49 	protected GVariantBuilder* gVariantBuilder;
50 	protected bool ownedRef;
51 
52 	/** Get the main Gtk struct */
53 	public GVariantBuilder* getVariantBuilderStruct(bool transferOwnership = false)
54 	{
55 		if (transferOwnership)
56 			ownedRef = false;
57 		return gVariantBuilder;
58 	}
59 
60 	/** the main Gtk struct as a void* */
61 	protected void* getStruct()
62 	{
63 		return cast(void*)gVariantBuilder;
64 	}
65 
66 	/**
67 	 * Sets our main struct and passes it to the parent class.
68 	 */
69 	public this (GVariantBuilder* gVariantBuilder, bool ownedRef = false)
70 	{
71 		this.gVariantBuilder = gVariantBuilder;
72 		this.ownedRef = ownedRef;
73 	}
74 
75 	~this ()
76 	{
77 		if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef )
78 			g_variant_builder_unref(gVariantBuilder);
79 	}
80 
81 
82 	/**
83 	 * Allocates and initialises a new #GVariantBuilder.
84 	 *
85 	 * You should call g_variant_builder_unref() on the return value when it
86 	 * is no longer needed.  The memory will not be automatically freed by
87 	 * any other call.
88 	 *
89 	 * In most cases it is easier to place a #GVariantBuilder directly on
90 	 * the stack of the calling function and initialise it with
91 	 * g_variant_builder_init().
92 	 *
93 	 * Params:
94 	 *     type = a container type
95 	 *
96 	 * Returns: a #GVariantBuilder
97 	 *
98 	 * Since: 2.24
99 	 *
100 	 * Throws: ConstructionException GTK+ fails to create the object.
101 	 */
102 	public this(VariantType type)
103 	{
104 		auto p = g_variant_builder_new((type is null) ? null : type.getVariantTypeStruct());
105 
106 		if(p is null)
107 		{
108 			throw new ConstructionException("null returned by new");
109 		}
110 
111 		this(cast(GVariantBuilder*) p);
112 	}
113 
114 	/**
115 	 * Adds @value to @builder.
116 	 *
117 	 * It is an error to call this function in any way that would create an
118 	 * inconsistent value to be constructed.  Some examples of this are
119 	 * putting different types of items into an array, putting the wrong
120 	 * types or number of items in a tuple, putting more than one value into
121 	 * a variant, etc.
122 	 *
123 	 * If @value is a floating reference (see g_variant_ref_sink()),
124 	 * the @builder instance takes ownership of @value.
125 	 *
126 	 * Params:
127 	 *     value = a #GVariant
128 	 *
129 	 * Since: 2.24
130 	 */
131 	public void addValue(Variant value)
132 	{
133 		g_variant_builder_add_value(gVariantBuilder, (value is null) ? null : value.getVariantStruct());
134 	}
135 
136 	/**
137 	 * Releases all memory associated with a #GVariantBuilder without
138 	 * freeing the #GVariantBuilder structure itself.
139 	 *
140 	 * It typically only makes sense to do this on a stack-allocated
141 	 * #GVariantBuilder if you want to abort building the value part-way
142 	 * through.  This function need not be called if you call
143 	 * g_variant_builder_end() and it also doesn't need to be called on
144 	 * builders allocated with g_variant_builder_new() (see
145 	 * g_variant_builder_unref() for that).
146 	 *
147 	 * This function leaves the #GVariantBuilder structure set to all-zeros.
148 	 * It is valid to call this function on either an initialised
149 	 * #GVariantBuilder or one that is set to all-zeros but it is not valid
150 	 * to call this function on uninitialised memory.
151 	 *
152 	 * Since: 2.24
153 	 */
154 	public void clear()
155 	{
156 		g_variant_builder_clear(gVariantBuilder);
157 	}
158 
159 	/**
160 	 * Closes the subcontainer inside the given @builder that was opened by
161 	 * the most recent call to g_variant_builder_open().
162 	 *
163 	 * It is an error to call this function in any way that would create an
164 	 * inconsistent value to be constructed (ie: too few values added to the
165 	 * subcontainer).
166 	 *
167 	 * Since: 2.24
168 	 */
169 	public void close()
170 	{
171 		g_variant_builder_close(gVariantBuilder);
172 	}
173 
174 	/**
175 	 * Ends the builder process and returns the constructed value.
176 	 *
177 	 * It is not permissible to use @builder in any way after this call
178 	 * except for reference counting operations (in the case of a
179 	 * heap-allocated #GVariantBuilder) or by reinitialising it with
180 	 * g_variant_builder_init() (in the case of stack-allocated). This
181 	 * means that for the stack-allocated builders there is no need to
182 	 * call g_variant_builder_clear() after the call to
183 	 * g_variant_builder_end().
184 	 *
185 	 * It is an error to call this function in any way that would create an
186 	 * inconsistent value to be constructed (ie: insufficient number of
187 	 * items added to a container with a specific number of children
188 	 * required).  It is also an error to call this function if the builder
189 	 * was created with an indefinite array or maybe type and no children
190 	 * have been added; in this case it is impossible to infer the type of
191 	 * the empty array.
192 	 *
193 	 * Returns: a new, floating, #GVariant
194 	 *
195 	 * Since: 2.24
196 	 */
197 	public Variant end()
198 	{
199 		auto p = g_variant_builder_end(gVariantBuilder);
200 
201 		if(p is null)
202 		{
203 			return null;
204 		}
205 
206 		return new Variant(cast(GVariant*) p);
207 	}
208 
209 	/**
210 	 * Initialises a #GVariantBuilder structure.
211 	 *
212 	 * @type must be non-%NULL.  It specifies the type of container to
213 	 * construct.  It can be an indefinite type such as
214 	 * %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)".
215 	 * Maybe, array, tuple, dictionary entry and variant-typed values may be
216 	 * constructed.
217 	 *
218 	 * After the builder is initialised, values are added using
219 	 * g_variant_builder_add_value() or g_variant_builder_add().
220 	 *
221 	 * After all the child values are added, g_variant_builder_end() frees
222 	 * the memory associated with the builder and returns the #GVariant that
223 	 * was created.
224 	 *
225 	 * This function completely ignores the previous contents of @builder.
226 	 * On one hand this means that it is valid to pass in completely
227 	 * uninitialised memory.  On the other hand, this means that if you are
228 	 * initialising over top of an existing #GVariantBuilder you need to
229 	 * first call g_variant_builder_clear() in order to avoid leaking
230 	 * memory.
231 	 *
232 	 * You must not call g_variant_builder_ref() or
233 	 * g_variant_builder_unref() on a #GVariantBuilder that was initialised
234 	 * with this function.  If you ever pass a reference to a
235 	 * #GVariantBuilder outside of the control of your own code then you
236 	 * should assume that the person receiving that reference may try to use
237 	 * reference counting; you should use g_variant_builder_new() instead of
238 	 * this function.
239 	 *
240 	 * Params:
241 	 *     type = a container type
242 	 *
243 	 * Since: 2.24
244 	 */
245 	public void init(VariantType type)
246 	{
247 		g_variant_builder_init(gVariantBuilder, (type is null) ? null : type.getVariantTypeStruct());
248 	}
249 
250 	/**
251 	 * Opens a subcontainer inside the given @builder.  When done adding
252 	 * items to the subcontainer, g_variant_builder_close() must be called. @type
253 	 * is the type of the container: so to build a tuple of several values, @type
254 	 * must include the tuple itself.
255 	 *
256 	 * It is an error to call this function in any way that would cause an
257 	 * inconsistent value to be constructed (ie: adding too many values or
258 	 * a value of an incorrect type).
259 	 *
260 	 * Example of building a nested variant:
261 	 * |[<!-- language="C" -->
262 	 * GVariantBuilder builder;
263 	 * guint32 some_number = get_number ();
264 	 * g_autoptr (GHashTable) some_dict = get_dict ();
265 	 * GHashTableIter iter;
266 	 * const gchar *key;
267 	 * const GVariant *value;
268 	 * g_autoptr (GVariant) output = NULL;
269 	 *
270 	 * g_variant_builder_init (&builder, G_VARIANT_TYPE ("(ua{sv})"));
271 	 * g_variant_builder_add (&builder, "u", some_number);
272 	 * g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}"));
273 	 *
274 	 * g_hash_table_iter_init (&iter, some_dict);
275 	 * while (g_hash_table_iter_next (&iter, (gpointer *) &key, (gpointer *) &value))
276 	 * {
277 	 * g_variant_builder_open (&builder, G_VARIANT_TYPE ("{sv}"));
278 	 * g_variant_builder_add (&builder, "s", key);
279 	 * g_variant_builder_add (&builder, "v", value);
280 	 * g_variant_builder_close (&builder);
281 	 * }
282 	 *
283 	 * g_variant_builder_close (&builder);
284 	 *
285 	 * output = g_variant_builder_end (&builder);
286 	 * ]|
287 	 *
288 	 * Params:
289 	 *     type = the #GVariantType of the container
290 	 *
291 	 * Since: 2.24
292 	 */
293 	public void open(VariantType type)
294 	{
295 		g_variant_builder_open(gVariantBuilder, (type is null) ? null : type.getVariantTypeStruct());
296 	}
297 
298 	/**
299 	 * Increases the reference count on @builder.
300 	 *
301 	 * Don't call this on stack-allocated #GVariantBuilder instances or bad
302 	 * things will happen.
303 	 *
304 	 * Returns: a new reference to @builder
305 	 *
306 	 * Since: 2.24
307 	 */
308 	public VariantBuilder doref()
309 	{
310 		auto p = g_variant_builder_ref(gVariantBuilder);
311 
312 		if(p is null)
313 		{
314 			return null;
315 		}
316 
317 		return new VariantBuilder(cast(GVariantBuilder*) p, true);
318 	}
319 
320 	/**
321 	 * Decreases the reference count on @builder.
322 	 *
323 	 * In the event that there are no more references, releases all memory
324 	 * associated with the #GVariantBuilder.
325 	 *
326 	 * Don't call this on stack-allocated #GVariantBuilder instances or bad
327 	 * things will happen.
328 	 *
329 	 * Since: 2.24
330 	 */
331 	public void unref()
332 	{
333 		g_variant_builder_unref(gVariantBuilder);
334 	}
335 }