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 * Returns: 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 * Returns: 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. @type 243 * is the type of the container: so to build a tuple of several values, @type 244 * must include the tuple itself. 245 * 246 * It is an error to call this function in any way that would cause an 247 * inconsistent value to be constructed (ie: adding too many values or 248 * a value of an incorrect type). 249 * 250 * Example of building a nested variant: 251 * |[<!-- language="C" --> 252 * GVariantBuilder builder; 253 * guint32 some_number = get_number (); 254 * g_autoptr (GHashTable) some_dict = get_dict (); 255 * GHashTableIter iter; 256 * const gchar *key; 257 * const GVariant *value; 258 * g_autoptr (GVariant) output = NULL; 259 * 260 * g_variant_builder_init (&builder, G_VARIANT_TYPE ("(ua{sv})")); 261 * g_variant_builder_add (&builder, "u", some_number); 262 * g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}")); 263 * 264 * g_hash_table_iter_init (&iter, some_dict); 265 * while (g_hash_table_iter_next (&iter, (gpointer *) &key, (gpointer *) &value)) 266 * { 267 * g_variant_builder_open (&builder, G_VARIANT_TYPE ("{sv}")); 268 * g_variant_builder_add (&builder, "s", key); 269 * g_variant_builder_add (&builder, "v", value); 270 * g_variant_builder_close (&builder); 271 * } 272 * 273 * g_variant_builder_close (&builder); 274 * 275 * output = g_variant_builder_end (&builder); 276 * ]| 277 * 278 * Params: 279 * type = the #GVariantType of the container 280 * 281 * Since: 2.24 282 */ 283 public void open(VariantType type) 284 { 285 g_variant_builder_open(gVariantBuilder, (type is null) ? null : type.getVariantTypeStruct()); 286 } 287 288 /** 289 * Increases the reference count on @builder. 290 * 291 * Don't call this on stack-allocated #GVariantBuilder instances or bad 292 * things will happen. 293 * 294 * Returns: a new reference to @builder 295 * 296 * Since: 2.24 297 */ 298 public VariantBuilder doref() 299 { 300 auto p = g_variant_builder_ref(gVariantBuilder); 301 302 if(p is null) 303 { 304 return null; 305 } 306 307 return new VariantBuilder(cast(GVariantBuilder*) p, true); 308 } 309 310 /** 311 * Decreases the reference count on @builder. 312 * 313 * In the event that there are no more references, releases all memory 314 * associated with the #GVariantBuilder. 315 * 316 * Don't call this on stack-allocated #GVariantBuilder instances or bad 317 * things will happen. 318 * 319 * Since: 2.24 320 */ 321 public void unref() 322 { 323 g_variant_builder_unref(gVariantBuilder); 324 } 325 }