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 gtkc.glib;
32 public  import gtkc.glibtypes;
33 
34 
35 /**
36  * A utility type for constructing container-type #GVariant instances.
37  * 
38  * This is an opaque structure and may only be accessed using the
39  * following functions.
40  * 
41  * #GVariantBuilder is not threadsafe in any way.  Do not attempt to
42  * access it from more than one thread.
43  */
44 public class VariantBuilder
45 {
46 	/** the main Gtk struct */
47 	protected GVariantBuilder* gVariantBuilder;
48 	protected bool ownedRef;
49 
50 	/** Get the main Gtk struct */
51 	public GVariantBuilder* getVariantBuilderStruct()
52 	{
53 		return gVariantBuilder;
54 	}
55 
56 	/** the main Gtk struct as a void* */
57 	protected void* getStruct()
58 	{
59 		return cast(void*)gVariantBuilder;
60 	}
61 
62 	/**
63 	 * Sets our main struct and passes it to the parent class.
64 	 */
65 	public this (GVariantBuilder* gVariantBuilder, bool ownedRef = false)
66 	{
67 		this.gVariantBuilder = gVariantBuilder;
68 		this.ownedRef = ownedRef;
69 	}
70 
71 
72 	/**
73 	 * Allocates and initialises a new #GVariantBuilder.
74 	 *
75 	 * You should call g_variant_builder_unref() on the return value when it
76 	 * is no longer needed.  The memory will not be automatically freed by
77 	 * any other call.
78 	 *
79 	 * In most cases it is easier to place a #GVariantBuilder directly on
80 	 * the stack of the calling function and initialise it with
81 	 * g_variant_builder_init().
82 	 *
83 	 * Params:
84 	 *     type = a container type
85 	 *
86 	 * Return: a #GVariantBuilder
87 	 *
88 	 * Since: 2.24
89 	 *
90 	 * Throws: ConstructionException GTK+ fails to create the object.
91 	 */
92 	public this(VariantType type)
93 	{
94 		auto p = g_variant_builder_new((type is null) ? null : type.getVariantTypeStruct());
95 		
96 		if(p is null)
97 		{
98 			throw new ConstructionException("null returned by new");
99 		}
100 		
101 		this(cast(GVariantBuilder*) p);
102 	}
103 
104 	/**
105 	 * Adds @value to @builder.
106 	 *
107 	 * It is an error to call this function in any way that would create an
108 	 * inconsistent value to be constructed.  Some examples of this are
109 	 * putting different types of items into an array, putting the wrong
110 	 * types or number of items in a tuple, putting more than one value into
111 	 * a variant, etc.
112 	 *
113 	 * If @value is a floating reference (see g_variant_ref_sink()),
114 	 * the @builder instance takes ownership of @value.
115 	 *
116 	 * Params:
117 	 *     value = a #GVariant
118 	 *
119 	 * Since: 2.24
120 	 */
121 	public void addValue(Variant value)
122 	{
123 		g_variant_builder_add_value(gVariantBuilder, (value is null) ? null : value.getVariantStruct());
124 	}
125 
126 	/**
127 	 * Releases all memory associated with a #GVariantBuilder without
128 	 * freeing the #GVariantBuilder structure itself.
129 	 *
130 	 * It typically only makes sense to do this on a stack-allocated
131 	 * #GVariantBuilder if you want to abort building the value part-way
132 	 * through.  This function need not be called if you call
133 	 * g_variant_builder_end() and it also doesn't need to be called on
134 	 * builders allocated with g_variant_builder_new (see
135 	 * g_variant_builder_unref() for that).
136 	 *
137 	 * This function leaves the #GVariantBuilder structure set to all-zeros.
138 	 * It is valid to call this function on either an initialised
139 	 * #GVariantBuilder or one that is set to all-zeros but it is not valid
140 	 * to call this function on uninitialised memory.
141 	 *
142 	 * Since: 2.24
143 	 */
144 	public void clear()
145 	{
146 		g_variant_builder_clear(gVariantBuilder);
147 	}
148 
149 	/**
150 	 * Closes the subcontainer inside the given @builder that was opened by
151 	 * the most recent call to g_variant_builder_open().
152 	 *
153 	 * It is an error to call this function in any way that would create an
154 	 * inconsistent value to be constructed (ie: too few values added to the
155 	 * subcontainer).
156 	 *
157 	 * Since: 2.24
158 	 */
159 	public void close()
160 	{
161 		g_variant_builder_close(gVariantBuilder);
162 	}
163 
164 	/**
165 	 * Ends the builder process and returns the constructed value.
166 	 *
167 	 * It is not permissible to use @builder in any way after this call
168 	 * except for reference counting operations (in the case of a
169 	 * heap-allocated #GVariantBuilder) or by reinitialising it with
170 	 * g_variant_builder_init() (in the case of stack-allocated). This
171 	 * means that for the stack-allocated builders there is no need to
172 	 * call g_variant_builder_clear() after the call to
173 	 * g_variant_builder_end().
174 	 *
175 	 * It is an error to call this function in any way that would create an
176 	 * inconsistent value to be constructed (ie: insufficient number of
177 	 * items added to a container with a specific number of children
178 	 * required).  It is also an error to call this function if the builder
179 	 * was created with an indefinite array or maybe type and no children
180 	 * have been added; in this case it is impossible to infer the type of
181 	 * the empty array.
182 	 *
183 	 * Return: a new, floating, #GVariant
184 	 *
185 	 * Since: 2.24
186 	 */
187 	public Variant end()
188 	{
189 		auto p = g_variant_builder_end(gVariantBuilder);
190 		
191 		if(p is null)
192 		{
193 			return null;
194 		}
195 		
196 		return new Variant(cast(GVariant*) p);
197 	}
198 
199 	/**
200 	 * Initialises a #GVariantBuilder structure.
201 	 *
202 	 * @type must be non-%NULL.  It specifies the type of container to
203 	 * construct.  It can be an indefinite type such as
204 	 * %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)".
205 	 * Maybe, array, tuple, dictionary entry and variant-typed values may be
206 	 * constructed.
207 	 *
208 	 * After the builder is initialised, values are added using
209 	 * g_variant_builder_add_value() or g_variant_builder_add().
210 	 *
211 	 * After all the child values are added, g_variant_builder_end() frees
212 	 * the memory associated with the builder and returns the #GVariant that
213 	 * was created.
214 	 *
215 	 * This function completely ignores the previous contents of @builder.
216 	 * On one hand this means that it is valid to pass in completely
217 	 * uninitialised memory.  On the other hand, this means that if you are
218 	 * initialising over top of an existing #GVariantBuilder you need to
219 	 * first call g_variant_builder_clear() in order to avoid leaking
220 	 * memory.
221 	 *
222 	 * You must not call g_variant_builder_ref() or
223 	 * g_variant_builder_unref() on a #GVariantBuilder that was initialised
224 	 * with this function.  If you ever pass a reference to a
225 	 * #GVariantBuilder outside of the control of your own code then you
226 	 * should assume that the person receiving that reference may try to use
227 	 * reference counting; you should use g_variant_builder_new() instead of
228 	 * this function.
229 	 *
230 	 * Params:
231 	 *     type = a container type
232 	 *
233 	 * Since: 2.24
234 	 */
235 	public void init(VariantType type)
236 	{
237 		g_variant_builder_init(gVariantBuilder, (type is null) ? null : type.getVariantTypeStruct());
238 	}
239 
240 	/**
241 	 * Opens a subcontainer inside the given @builder.  When done adding
242 	 * items to the subcontainer, g_variant_builder_close() must be called.
243 	 *
244 	 * It is an error to call this function in any way that would cause an
245 	 * inconsistent value to be constructed (ie: adding too many values or
246 	 * a value of an incorrect type).
247 	 *
248 	 * Params:
249 	 *     type = a #GVariantType
250 	 *
251 	 * Since: 2.24
252 	 */
253 	public void open(VariantType type)
254 	{
255 		g_variant_builder_open(gVariantBuilder, (type is null) ? null : type.getVariantTypeStruct());
256 	}
257 
258 	/**
259 	 * Increases the reference count on @builder.
260 	 *
261 	 * Don't call this on stack-allocated #GVariantBuilder instances or bad
262 	 * things will happen.
263 	 *
264 	 * Return: a new reference to @builder
265 	 *
266 	 * Since: 2.24
267 	 */
268 	public VariantBuilder doref()
269 	{
270 		auto p = g_variant_builder_ref(gVariantBuilder);
271 		
272 		if(p is null)
273 		{
274 			return null;
275 		}
276 		
277 		return new VariantBuilder(cast(GVariantBuilder*) p, true);
278 	}
279 
280 	/**
281 	 * Decreases the reference count on @builder.
282 	 *
283 	 * In the event that there are no more references, releases all memory
284 	 * associated with the #GVariantBuilder.
285 	 *
286 	 * Don't call this on stack-allocated #GVariantBuilder instances or bad
287 	 * things will happen.
288 	 *
289 	 * Since: 2.24
290 	 */
291 	public void unref()
292 	{
293 		g_variant_builder_unref(gVariantBuilder);
294 	}
295 }