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