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 protected bool ownedRef; 133 134 /** Get the main Gtk struct */ 135 public GVariantDict* getVariantDictStruct() 136 { 137 return gVariantDict; 138 } 139 140 /** the main Gtk struct as a void* */ 141 protected void* getStruct() 142 { 143 return cast(void*)gVariantDict; 144 } 145 146 /** 147 * Sets our main struct and passes it to the parent class. 148 */ 149 public this (GVariantDict* gVariantDict, bool ownedRef = false) 150 { 151 this.gVariantDict = gVariantDict; 152 this.ownedRef = ownedRef; 153 } 154 155 156 /** 157 * Allocates and initialises a new #GVariantDict. 158 * 159 * You should call g_variant_dict_unref() on the return value when it 160 * is no longer needed. The memory will not be automatically freed by 161 * any other call. 162 * 163 * In some cases it may be easier to place a #GVariantDict directly on 164 * the stack of the calling function and initialise it with 165 * g_variant_dict_init(). This is particularly useful when you are 166 * using #GVariantDict to construct a #GVariant. 167 * 168 * Params: 169 * fromAsv = the #GVariant with which to initialise the 170 * dictionary 171 * 172 * Return: a #GVariantDict 173 * 174 * Since: 2.40 175 * 176 * Throws: ConstructionException GTK+ fails to create the object. 177 */ 178 public this(Variant fromAsv) 179 { 180 auto p = g_variant_dict_new((fromAsv is null) ? null : fromAsv.getVariantStruct()); 181 182 if(p is null) 183 { 184 throw new ConstructionException("null returned by new"); 185 } 186 187 this(cast(GVariantDict*) p); 188 } 189 190 /** 191 * Releases all memory associated with a #GVariantDict without freeing 192 * the #GVariantDict structure itself. 193 * 194 * It typically only makes sense to do this on a stack-allocated 195 * #GVariantDict if you want to abort building the value part-way 196 * through. This function need not be called if you call 197 * g_variant_dict_end() and it also doesn't need to be called on dicts 198 * allocated with g_variant_dict_new (see g_variant_dict_unref() for 199 * that). 200 * 201 * It is valid to call this function on either an initialised 202 * #GVariantDict or one that was previously cleared by an earlier call 203 * to g_variant_dict_clear() but it is not valid to call this function 204 * on uninitialised memory. 205 * 206 * Since: 2.40 207 */ 208 public void clear() 209 { 210 g_variant_dict_clear(gVariantDict); 211 } 212 213 /** 214 * Checks if @key exists in @dict. 215 * 216 * Params: 217 * key = the key to lookup in the dictionary 218 * 219 * Return: %TRUE if @key is in @dict 220 * 221 * Since: 2.40 222 */ 223 public bool contains(string key) 224 { 225 return g_variant_dict_contains(gVariantDict, Str.toStringz(key)) != 0; 226 } 227 228 /** 229 * Returns the current value of @dict as a #GVariant of type 230 * %G_VARIANT_TYPE_VARDICT, clearing it in the process. 231 * 232 * It is not permissible to use @dict in any way after this call except 233 * for reference counting operations (in the case of a heap-allocated 234 * #GVariantDict) or by reinitialising it with g_variant_dict_init() (in 235 * the case of stack-allocated). 236 * 237 * Return: a new, floating, #GVariant 238 * 239 * Since: 2.40 240 */ 241 public Variant end() 242 { 243 auto p = g_variant_dict_end(gVariantDict); 244 245 if(p is null) 246 { 247 return null; 248 } 249 250 return new Variant(cast(GVariant*) p); 251 } 252 253 /** 254 * Initialises a #GVariantDict structure. 255 * 256 * If @from_asv is given, it is used to initialise the dictionary. 257 * 258 * This function completely ignores the previous contents of @dict. On 259 * one hand this means that it is valid to pass in completely 260 * uninitialised memory. On the other hand, this means that if you are 261 * initialising over top of an existing #GVariantDict you need to first 262 * call g_variant_dict_clear() in order to avoid leaking memory. 263 * 264 * You must not call g_variant_dict_ref() or g_variant_dict_unref() on a 265 * #GVariantDict that was initialised with this function. If you ever 266 * pass a reference to a #GVariantDict outside of the control of your 267 * own code then you should assume that the person receiving that 268 * reference may try to use reference counting; you should use 269 * g_variant_dict_new() instead of this function. 270 * 271 * Params: 272 * fromAsv = the initial value for @dict 273 * 274 * Since: 2.40 275 */ 276 public void init(Variant fromAsv) 277 { 278 g_variant_dict_init(gVariantDict, (fromAsv is null) ? null : fromAsv.getVariantStruct()); 279 } 280 281 /** 282 * Inserts (or replaces) a key in a #GVariantDict. 283 * 284 * @value is consumed if it is floating. 285 * 286 * Params: 287 * key = the key to insert a value for 288 * value = the value to insert 289 * 290 * Since: 2.40 291 */ 292 public void insertValue(string key, Variant value) 293 { 294 g_variant_dict_insert_value(gVariantDict, Str.toStringz(key), (value is null) ? null : value.getVariantStruct()); 295 } 296 297 /** 298 * Looks up a value in a #GVariantDict. 299 * 300 * If @key is not found in @dictionary, %NULL is returned. 301 * 302 * The @expected_type string specifies what type of value is expected. 303 * If the value associated with @key has a different type then %NULL is 304 * returned. 305 * 306 * If the key is found and the value has the correct type, it is 307 * returned. If @expected_type was specified then any non-%NULL return 308 * value will have this type. 309 * 310 * Params: 311 * key = the key to lookup in the dictionary 312 * expectedType = a #GVariantType, or %NULL 313 * 314 * Return: the value of the dictionary key, or %NULL 315 * 316 * Since: 2.40 317 */ 318 public Variant lookupValue(string key, VariantType expectedType) 319 { 320 auto p = g_variant_dict_lookup_value(gVariantDict, Str.toStringz(key), (expectedType is null) ? null : expectedType.getVariantTypeStruct()); 321 322 if(p is null) 323 { 324 return null; 325 } 326 327 return new Variant(cast(GVariant*) p, true); 328 } 329 330 /** 331 * Increases the reference count on @dict. 332 * 333 * Don't call this on stack-allocated #GVariantDict instances or bad 334 * things will happen. 335 * 336 * Return: a new reference to @dict 337 * 338 * Since: 2.40 339 */ 340 public VariantDict doref() 341 { 342 auto p = g_variant_dict_ref(gVariantDict); 343 344 if(p is null) 345 { 346 return null; 347 } 348 349 return new VariantDict(cast(GVariantDict*) p, true); 350 } 351 352 /** 353 * Removes a key and its associated value from a #GVariantDict. 354 * 355 * Params: 356 * key = the key to remove 357 * 358 * Return: %TRUE if the key was found and removed 359 * 360 * Since: 2.40 361 */ 362 public bool remove(string key) 363 { 364 return g_variant_dict_remove(gVariantDict, Str.toStringz(key)) != 0; 365 } 366 367 /** 368 * Decreases the reference count on @dict. 369 * 370 * In the event that there are no more references, releases all memory 371 * associated with the #GVariantDict. 372 * 373 * Don't call this on stack-allocated #GVariantDict instances or bad 374 * things will happen. 375 * 376 * Since: 2.40 377 */ 378 public void unref() 379 { 380 g_variant_dict_unref(gVariantDict); 381 } 382 }