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).
171 	 *
172 	 * It is an error to call this function in any way that would create an
173 	 * inconsistent value to be constructed (ie: insufficient number of
174 	 * items added to a container with a specific number of children
175 	 * required).  It is also an error to call this function if the builder
176 	 * was created with an indefinite array or maybe type and no children
177 	 * have been added; in this case it is impossible to infer the type of
178 	 * the empty array.
179 	 *
180 	 * Return: a new, floating, #GVariant
181 	 *
182 	 * Since: 2.24
183 	 */
184 	public Variant end()
185 	{
186 		auto p = g_variant_builder_end(gVariantBuilder);
187 		
188 		if(p is null)
189 		{
190 			return null;
191 		}
192 		
193 		return new Variant(cast(GVariant*) p);
194 	}
195 
196 	/**
197 	 * Initialises a #GVariantBuilder structure.
198 	 *
199 	 * @type must be non-%NULL.  It specifies the type of container to
200 	 * construct.  It can be an indefinite type such as
201 	 * %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)".
202 	 * Maybe, array, tuple, dictionary entry and variant-typed values may be
203 	 * constructed.
204 	 *
205 	 * After the builder is initialised, values are added using
206 	 * g_variant_builder_add_value() or g_variant_builder_add().
207 	 *
208 	 * After all the child values are added, g_variant_builder_end() frees
209 	 * the memory associated with the builder and returns the #GVariant that
210 	 * was created.
211 	 *
212 	 * This function completely ignores the previous contents of @builder.
213 	 * On one hand this means that it is valid to pass in completely
214 	 * uninitialised memory.  On the other hand, this means that if you are
215 	 * initialising over top of an existing #GVariantBuilder you need to
216 	 * first call g_variant_builder_clear() in order to avoid leaking
217 	 * memory.
218 	 *
219 	 * You must not call g_variant_builder_ref() or
220 	 * g_variant_builder_unref() on a #GVariantBuilder that was initialised
221 	 * with this function.  If you ever pass a reference to a
222 	 * #GVariantBuilder outside of the control of your own code then you
223 	 * should assume that the person receiving that reference may try to use
224 	 * reference counting; you should use g_variant_builder_new() instead of
225 	 * this function.
226 	 *
227 	 * Params:
228 	 *     type = a container type
229 	 *
230 	 * Since: 2.24
231 	 */
232 	public void init(VariantType type)
233 	{
234 		g_variant_builder_init(gVariantBuilder, (type is null) ? null : type.getVariantTypeStruct());
235 	}
236 
237 	/**
238 	 * Opens a subcontainer inside the given @builder.  When done adding
239 	 * items to the subcontainer, g_variant_builder_close() must be called.
240 	 *
241 	 * It is an error to call this function in any way that would cause an
242 	 * inconsistent value to be constructed (ie: adding too many values or
243 	 * a value of an incorrect type).
244 	 *
245 	 * Params:
246 	 *     type = a #GVariantType
247 	 *
248 	 * Since: 2.24
249 	 */
250 	public void open(VariantType type)
251 	{
252 		g_variant_builder_open(gVariantBuilder, (type is null) ? null : type.getVariantTypeStruct());
253 	}
254 
255 	/**
256 	 * Increases the reference count on @builder.
257 	 *
258 	 * Don't call this on stack-allocated #GVariantBuilder instances or bad
259 	 * things will happen.
260 	 *
261 	 * Return: a new reference to @builder
262 	 *
263 	 * Since: 2.24
264 	 */
265 	public VariantBuilder doref()
266 	{
267 		auto p = g_variant_builder_ref(gVariantBuilder);
268 		
269 		if(p is null)
270 		{
271 			return null;
272 		}
273 		
274 		return new VariantBuilder(cast(GVariantBuilder*) p, true);
275 	}
276 
277 	/**
278 	 * Decreases the reference count on @builder.
279 	 *
280 	 * In the event that there are no more references, releases all memory
281 	 * associated with the #GVariantBuilder.
282 	 *
283 	 * Don't call this on stack-allocated #GVariantBuilder instances or bad
284 	 * things will happen.
285 	 *
286 	 * Since: 2.24
287 	 */
288 	public void unref()
289 	{
290 		g_variant_builder_unref(gVariantBuilder);
291 	}
292 }