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.VariantDict; 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 * #GVariantDict is a mutable interface to #GVariant dictionaries. 37 * 38 * It can be used for doing a sequence of dictionary lookups in an 39 * efficient way on an existing #GVariant dictionary or it can be used 40 * to construct new dictionaries with a hashtable-like interface. It 41 * can also be used for taking existing dictionaries and modifying them 42 * in order to create new ones. 43 * 44 * #GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT 45 * dictionaries. 46 * 47 * It is possible to use #GVariantDict allocated on the stack or on the 48 * heap. When using a stack-allocated #GVariantDict, you begin with a 49 * call to g_variant_dict_init() and free the resources with a call to 50 * g_variant_dict_clear(). 51 * 52 * Heap-allocated #GVariantDict follows normal refcounting rules: you 53 * allocate it with g_variant_dict_new() and use g_variant_dict_ref() 54 * and g_variant_dict_unref(). 55 * 56 * g_variant_dict_end() is used to convert the #GVariantDict back into a 57 * dictionary-type #GVariant. When used with stack-allocated instances, 58 * this also implicitly frees all associated memory, but for 59 * heap-allocated instances, you must still call g_variant_dict_unref() 60 * afterwards. 61 * 62 * You will typically want to use a heap-allocated #GVariantDict when 63 * you expose it as part of an API. For most other uses, the 64 * stack-allocated form will be more convenient. 65 * 66 * Consider the following two examples that do the same thing in each 67 * style: take an existing dictionary and look up the "count" uint32 68 * key, adding 1 to it if it is found, or returning an error if the 69 * key is not found. Each returns the new dictionary as a floating 70 * #GVariant. 71 * 72 * ## Using a stack-allocated GVariantDict 73 * 74 * |[<!-- language="C" --> 75 * GVariant * 76 * add_to_count (GVariant *orig, 77 * GError **error) 78 * { 79 * GVariantDict dict; 80 * guint32 count; 81 * 82 * g_variant_dict_init (&dict, orig); 83 * if (!g_variant_dict_lookup (&dict, "count", "u", &count)) 84 * { 85 * g_set_error (...); 86 * g_variant_dict_clear (&dict); 87 * return NULL; 88 * } 89 * 90 * g_variant_dict_insert (&dict, "count", "u", count + 1); 91 * 92 * return g_variant_dict_end (&dict); 93 * } 94 * ]| 95 * 96 * ## Using heap-allocated GVariantDict 97 * 98 * |[<!-- language="C" --> 99 * GVariant * 100 * add_to_count (GVariant *orig, 101 * GError **error) 102 * { 103 * GVariantDict *dict; 104 * GVariant *result; 105 * guint32 count; 106 * 107 * dict = g_variant_dict_new (orig); 108 * 109 * if (g_variant_dict_lookup (dict, "count", "u", &count)) 110 * { 111 * g_variant_dict_insert (dict, "count", "u", count + 1); 112 * result = g_variant_dict_end (dict); 113 * } 114 * else 115 * { 116 * g_set_error (...); 117 * result = NULL; 118 * } 119 * 120 * g_variant_dict_unref (dict); 121 * 122 * return result; 123 * } 124 * ]| 125 * 126 * Since: 2.40 127 */ 128 public class VariantDict 129 { 130 /** the main Gtk struct */ 131 protected GVariantDict* gVariantDict; 132 133 /** Get the main Gtk struct */ 134 public GVariantDict* getVariantDictStruct() 135 { 136 return gVariantDict; 137 } 138 139 /** the main Gtk struct as a void* */ 140 protected void* getStruct() 141 { 142 return cast(void*)gVariantDict; 143 } 144 145 /** 146 * Sets our main struct and passes it to the parent class. 147 */ 148 public this (GVariantDict* gVariantDict) 149 { 150 this.gVariantDict = gVariantDict; 151 } 152 153 154 /** 155 * Allocates and initialises a new #GVariantDict. 156 * 157 * You should call g_variant_dict_unref() on the return value when it 158 * is no longer needed. The memory will not be automatically freed by 159 * any other call. 160 * 161 * In some cases it may be easier to place a #GVariantDict directly on 162 * the stack of the calling function and initialise it with 163 * g_variant_dict_init(). This is particularly useful when you are 164 * using #GVariantDict to construct a #GVariant. 165 * 166 * Params: 167 * fromAsv = the #GVariant with which to initialise the 168 * dictionary 169 * 170 * Return: a #GVariantDict 171 * 172 * Since: 2.40 173 * 174 * Throws: ConstructionException GTK+ fails to create the object. 175 */ 176 public this(Variant fromAsv) 177 { 178 auto p = g_variant_dict_new((fromAsv is null) ? null : fromAsv.getVariantStruct()); 179 180 if(p is null) 181 { 182 throw new ConstructionException("null returned by new"); 183 } 184 185 this(cast(GVariantDict*) p); 186 } 187 188 /** 189 * Releases all memory associated with a #GVariantDict without freeing 190 * the #GVariantDict structure itself. 191 * 192 * It typically only makes sense to do this on a stack-allocated 193 * #GVariantDict if you want to abort building the value part-way 194 * through. This function need not be called if you call 195 * g_variant_dict_end() and it also doesn't need to be called on dicts 196 * allocated with g_variant_dict_new (see g_variant_dict_unref() for 197 * that). 198 * 199 * It is valid to call this function on either an initialised 200 * #GVariantDict or one that was previously cleared by an earlier call 201 * to g_variant_dict_clear() but it is not valid to call this function 202 * on uninitialised memory. 203 * 204 * Since: 2.40 205 */ 206 public void clear() 207 { 208 g_variant_dict_clear(gVariantDict); 209 } 210 211 /** 212 * Checks if @key exists in @dict. 213 * 214 * Params: 215 * key = the key to lookup in the dictionary 216 * 217 * Return: %TRUE if @key is in @dict 218 * 219 * Since: 2.40 220 */ 221 public bool contains(string key) 222 { 223 return g_variant_dict_contains(gVariantDict, Str.toStringz(key)) != 0; 224 } 225 226 /** 227 * Returns the current value of @dict as a #GVariant of type 228 * %G_VARIANT_TYPE_VARDICT, clearing it in the process. 229 * 230 * It is not permissible to use @dict in any way after this call except 231 * for reference counting operations (in the case of a heap-allocated 232 * #GVariantDict) or by reinitialising it with g_variant_dict_init() (in 233 * the case of stack-allocated). 234 * 235 * Return: a new, floating, #GVariant 236 * 237 * Since: 2.40 238 */ 239 public Variant end() 240 { 241 auto p = g_variant_dict_end(gVariantDict); 242 243 if(p is null) 244 { 245 return null; 246 } 247 248 return new Variant(cast(GVariant*) p); 249 } 250 251 /** 252 * Initialises a #GVariantDict structure. 253 * 254 * If @from_asv is given, it is used to initialise the dictionary. 255 * 256 * This function completely ignores the previous contents of @dict. On 257 * one hand this means that it is valid to pass in completely 258 * uninitialised memory. On the other hand, this means that if you are 259 * initialising over top of an existing #GVariantDict you need to first 260 * call g_variant_dict_clear() in order to avoid leaking memory. 261 * 262 * You must not call g_variant_dict_ref() or g_variant_dict_unref() on a 263 * #GVariantDict that was initialised with this function. If you ever 264 * pass a reference to a #GVariantDict outside of the control of your 265 * own code then you should assume that the person receiving that 266 * reference may try to use reference counting; you should use 267 * g_variant_dict_new() instead of this function. 268 * 269 * Params: 270 * fromAsv = the initial value for @dict 271 * 272 * Since: 2.40 273 */ 274 public void init(Variant fromAsv) 275 { 276 g_variant_dict_init(gVariantDict, (fromAsv is null) ? null : fromAsv.getVariantStruct()); 277 } 278 279 /** 280 * Inserts (or replaces) a key in a #GVariantDict. 281 * 282 * @value is consumed if it is floating. 283 * 284 * Params: 285 * key = the key to insert a value for 286 * value = the value to insert 287 * 288 * Since: 2.40 289 */ 290 public void insertValue(string key, Variant value) 291 { 292 g_variant_dict_insert_value(gVariantDict, Str.toStringz(key), (value is null) ? null : value.getVariantStruct()); 293 } 294 295 /** 296 * Looks up a value in a #GVariantDict. 297 * 298 * If @key is not found in @dictionary, %NULL is returned. 299 * 300 * The @expected_type string specifies what type of value is expected. 301 * If the value associated with @key has a different type then %NULL is 302 * returned. 303 * 304 * If the key is found and the value has the correct type, it is 305 * returned. If @expected_type was specified then any non-%NULL return 306 * value will have this type. 307 * 308 * Params: 309 * key = the key to lookup in the dictionary 310 * expectedType = a #GVariantType, or %NULL 311 * 312 * Return: the value of the dictionary key, or %NULL 313 * 314 * Since: 2.40 315 */ 316 public Variant lookupValue(string key, VariantType expectedType) 317 { 318 auto p = g_variant_dict_lookup_value(gVariantDict, Str.toStringz(key), (expectedType is null) ? null : expectedType.getVariantTypeStruct()); 319 320 if(p is null) 321 { 322 return null; 323 } 324 325 return new Variant(cast(GVariant*) p); 326 } 327 328 /** 329 * Increases the reference count on @dict. 330 * 331 * Don't call this on stack-allocated #GVariantDict instances or bad 332 * things will happen. 333 * 334 * Return: a new reference to @dict 335 * 336 * Since: 2.40 337 */ 338 public VariantDict doref() 339 { 340 auto p = g_variant_dict_ref(gVariantDict); 341 342 if(p is null) 343 { 344 return null; 345 } 346 347 return new VariantDict(cast(GVariantDict*) p); 348 } 349 350 /** 351 * Removes a key and its associated value from a #GVariantDict. 352 * 353 * Params: 354 * key = the key to remove 355 * 356 * Return: %TRUE if the key was found and removed 357 * 358 * Since: 2.40 359 */ 360 public bool remove(string key) 361 { 362 return g_variant_dict_remove(gVariantDict, Str.toStringz(key)) != 0; 363 } 364 365 /** 366 * Decreases the reference count on @dict. 367 * 368 * In the event that there are no more references, releases all memory 369 * associated with the #GVariantDict. 370 * 371 * Don't call this on stack-allocated #GVariantDict instances or bad 372 * things will happen. 373 * 374 * Since: 2.40 375 */ 376 public void unref() 377 { 378 g_variant_dict_unref(gVariantDict); 379 } 380 }