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 gobject.ParamSpec; 26 27 private import glib.Str; 28 private import gobject.ObjectG; 29 private import gobject.Value; 30 private import gobject.c.functions; 31 public import gobject.c.types; 32 public import gtkc.gobjecttypes; 33 private import gtkd.Loader; 34 35 36 /** 37 * #GParamSpec is an object structure that encapsulates the metadata 38 * required to specify parameters, such as e.g. #GObject properties. 39 * 40 * ## Parameter names # {#canonical-parameter-names} 41 * 42 * Parameter names need to start with a letter (a-z or A-Z). 43 * Subsequent characters can be letters, numbers or a '-'. 44 * All other characters are replaced by a '-' during construction. 45 * The result of this replacement is called the canonical name of 46 * the parameter. 47 */ 48 public class ParamSpec 49 { 50 /** the main Gtk struct */ 51 protected GParamSpec* gParamSpec; 52 protected bool ownedRef; 53 54 /** Get the main Gtk struct */ 55 public GParamSpec* getParamSpecStruct(bool transferOwnership = false) 56 { 57 if (transferOwnership) 58 ownedRef = false; 59 return gParamSpec; 60 } 61 62 /** the main Gtk struct as a void* */ 63 protected void* getStruct() 64 { 65 return cast(void*)gParamSpec; 66 } 67 68 /** 69 * Sets our main struct and passes it to the parent class. 70 */ 71 public this (GParamSpec* gParamSpec, bool ownedRef = false) 72 { 73 this.gParamSpec = gParamSpec; 74 this.ownedRef = ownedRef; 75 } 76 77 ~this () 78 { 79 if ( Linker.isLoaded(LIBRARY_GOBJECT) && ownedRef ) 80 g_param_spec_unref(gParamSpec); 81 } 82 83 84 /** 85 * Creates a new #GParamSpec instance. 86 * 87 * A property name consists of segments consisting of ASCII letters and 88 * digits, separated by either the '-' or '_' character. The first 89 * character of a property name must be a letter. Names which violate these 90 * rules lead to undefined behaviour. 91 * 92 * When creating and looking up a #GParamSpec, either separator can be 93 * used, but they cannot be mixed. Using '-' is considerably more 94 * efficient and in fact required when using property names as detail 95 * strings for signals. 96 * 97 * Beyond the name, #GParamSpecs have two more descriptive 98 * strings associated with them, the @nick, which should be suitable 99 * for use as a label for the property in a property editor, and the 100 * @blurb, which should be a somewhat longer description, suitable for 101 * e.g. a tooltip. The @nick and @blurb should ideally be localized. 102 * 103 * Params: 104 * paramType = the #GType for the property; must be derived from #G_TYPE_PARAM 105 * name = the canonical name of the property 106 * nick = the nickname of the property 107 * blurb = a short description of the property 108 * flags = a combination of #GParamFlags 109 * 110 * Returns: a newly allocated #GParamSpec instance 111 */ 112 public static ParamSpec internal(GType paramType, string name, string nick, string blurb, GParamFlags flags) 113 { 114 auto p = g_param_spec_internal(paramType, Str.toStringz(name), Str.toStringz(nick), Str.toStringz(blurb), flags); 115 116 if(p is null) 117 { 118 return null; 119 } 120 121 return ObjectG.getDObject!(ParamSpec)(cast(GParamSpec*) p); 122 } 123 124 /** 125 * Get the short description of a #GParamSpec. 126 * 127 * Returns: the short description of @pspec. 128 */ 129 public string getBlurb() 130 { 131 return Str.toString(g_param_spec_get_blurb(gParamSpec)); 132 } 133 134 /** 135 * Gets the default value of @pspec as a pointer to a #GValue. 136 * 137 * The #GValue will remain valid for the life of @pspec. 138 * 139 * Returns: a pointer to a #GValue which must not be modified 140 * 141 * Since: 2.38 142 */ 143 public Value getDefaultValue() 144 { 145 auto p = g_param_spec_get_default_value(gParamSpec); 146 147 if(p is null) 148 { 149 return null; 150 } 151 152 return ObjectG.getDObject!(Value)(cast(GValue*) p); 153 } 154 155 /** 156 * Get the name of a #GParamSpec. 157 * 158 * The name is always an "interned" string (as per g_intern_string()). 159 * This allows for pointer-value comparisons. 160 * 161 * Returns: the name of @pspec. 162 */ 163 public string getName() 164 { 165 return Str.toString(g_param_spec_get_name(gParamSpec)); 166 } 167 168 /** 169 * Gets the GQuark for the name. 170 * 171 * Returns: the GQuark for @pspec->name. 172 * 173 * Since: 2.46 174 */ 175 public GQuark getNameQuark() 176 { 177 return g_param_spec_get_name_quark(gParamSpec); 178 } 179 180 /** 181 * Get the nickname of a #GParamSpec. 182 * 183 * Returns: the nickname of @pspec. 184 */ 185 public string getNick() 186 { 187 return Str.toString(g_param_spec_get_nick(gParamSpec)); 188 } 189 190 /** 191 * Gets back user data pointers stored via g_param_spec_set_qdata(). 192 * 193 * Params: 194 * quark = a #GQuark, naming the user data pointer 195 * 196 * Returns: the user data pointer set, or %NULL 197 */ 198 public void* getQdata(GQuark quark) 199 { 200 return g_param_spec_get_qdata(gParamSpec, quark); 201 } 202 203 /** 204 * If the paramspec redirects operations to another paramspec, 205 * returns that paramspec. Redirect is used typically for 206 * providing a new implementation of a property in a derived 207 * type while preserving all the properties from the parent 208 * type. Redirection is established by creating a property 209 * of type #GParamSpecOverride. See g_object_class_override_property() 210 * for an example of the use of this capability. 211 * 212 * Returns: paramspec to which requests on this 213 * paramspec should be redirected, or %NULL if none. 214 * 215 * Since: 2.4 216 */ 217 public ParamSpec getRedirectTarget() 218 { 219 auto p = g_param_spec_get_redirect_target(gParamSpec); 220 221 if(p is null) 222 { 223 return null; 224 } 225 226 return ObjectG.getDObject!(ParamSpec)(cast(GParamSpec*) p); 227 } 228 229 alias doref = ref_; 230 /** 231 * Increments the reference count of @pspec. 232 * 233 * Returns: the #GParamSpec that was passed into this function 234 */ 235 public ParamSpec ref_() 236 { 237 auto p = g_param_spec_ref(gParamSpec); 238 239 if(p is null) 240 { 241 return null; 242 } 243 244 return ObjectG.getDObject!(ParamSpec)(cast(GParamSpec*) p); 245 } 246 247 /** 248 * Convenience function to ref and sink a #GParamSpec. 249 * 250 * Returns: the #GParamSpec that was passed into this function 251 * 252 * Since: 2.10 253 */ 254 public ParamSpec refSink() 255 { 256 auto p = g_param_spec_ref_sink(gParamSpec); 257 258 if(p is null) 259 { 260 return null; 261 } 262 263 return ObjectG.getDObject!(ParamSpec)(cast(GParamSpec*) p); 264 } 265 266 /** 267 * Sets an opaque, named pointer on a #GParamSpec. The name is 268 * specified through a #GQuark (retrieved e.g. via 269 * g_quark_from_static_string()), and the pointer can be gotten back 270 * from the @pspec with g_param_spec_get_qdata(). Setting a 271 * previously set user data pointer, overrides (frees) the old pointer 272 * set, using %NULL as pointer essentially removes the data stored. 273 * 274 * Params: 275 * quark = a #GQuark, naming the user data pointer 276 * data = an opaque user data pointer 277 */ 278 public void setQdata(GQuark quark, void* data) 279 { 280 g_param_spec_set_qdata(gParamSpec, quark, data); 281 } 282 283 /** 284 * This function works like g_param_spec_set_qdata(), but in addition, 285 * a `void (*destroy) (gpointer)` function may be 286 * specified which is called with @data as argument when the @pspec is 287 * finalized, or the data is being overwritten by a call to 288 * g_param_spec_set_qdata() with the same @quark. 289 * 290 * Params: 291 * quark = a #GQuark, naming the user data pointer 292 * data = an opaque user data pointer 293 * destroy = function to invoke with @data as argument, when @data needs to 294 * be freed 295 */ 296 public void setQdataFull(GQuark quark, void* data, GDestroyNotify destroy) 297 { 298 g_param_spec_set_qdata_full(gParamSpec, quark, data, destroy); 299 } 300 301 /** 302 * The initial reference count of a newly created #GParamSpec is 1, 303 * even though no one has explicitly called g_param_spec_ref() on it 304 * yet. So the initial reference count is flagged as "floating", until 305 * someone calls `g_param_spec_ref (pspec); g_param_spec_sink 306 * (pspec);` in sequence on it, taking over the initial 307 * reference count (thus ending up with a @pspec that has a reference 308 * count of 1 still, but is not flagged "floating" anymore). 309 */ 310 public void sink() 311 { 312 g_param_spec_sink(gParamSpec); 313 } 314 315 /** 316 * Gets back user data pointers stored via g_param_spec_set_qdata() 317 * and removes the @data from @pspec without invoking its destroy() 318 * function (if any was set). Usually, calling this function is only 319 * required to update user data pointers with a destroy notifier. 320 * 321 * Params: 322 * quark = a #GQuark, naming the user data pointer 323 * 324 * Returns: the user data pointer set, or %NULL 325 */ 326 public void* stealQdata(GQuark quark) 327 { 328 return g_param_spec_steal_qdata(gParamSpec, quark); 329 } 330 331 /** 332 * Decrements the reference count of a @pspec. 333 */ 334 public void unref() 335 { 336 g_param_spec_unref(gParamSpec); 337 } 338 339 /** 340 * Registers @name as the name of a new static type derived from 341 * #G_TYPE_PARAM. The type system uses the information contained in 342 * the #GParamSpecTypeInfo structure pointed to by @info to manage the 343 * #GParamSpec type and its instances. 344 * 345 * Params: 346 * name = 0-terminated string used as the name of the new #GParamSpec type. 347 * pspecInfo = The #GParamSpecTypeInfo for this #GParamSpec type. 348 * 349 * Returns: The new type identifier. 350 */ 351 public static GType paramTypeRegisterStatic(string name, GParamSpecTypeInfo* pspecInfo) 352 { 353 return g_param_type_register_static(Str.toStringz(name), pspecInfo); 354 } 355 356 /** 357 * Transforms @src_value into @dest_value if possible, and then 358 * validates @dest_value, in order for it to conform to @pspec. If 359 * @strict_validation is %TRUE this function will only succeed if the 360 * transformed @dest_value complied to @pspec without modifications. 361 * 362 * See also g_value_type_transformable(), g_value_transform() and 363 * g_param_value_validate(). 364 * 365 * Params: 366 * pspec = a valid #GParamSpec 367 * srcValue = souce #GValue 368 * destValue = destination #GValue of correct type for @pspec 369 * strictValidation = %TRUE requires @dest_value to conform to @pspec 370 * without modifications 371 * 372 * Returns: %TRUE if transformation and validation were successful, 373 * %FALSE otherwise and @dest_value is left untouched. 374 */ 375 public static bool paramValueConvert(ParamSpec pspec, Value srcValue, Value destValue, bool strictValidation) 376 { 377 return g_param_value_convert((pspec is null) ? null : pspec.getParamSpecStruct(), (srcValue is null) ? null : srcValue.getValueStruct(), (destValue is null) ? null : destValue.getValueStruct(), strictValidation) != 0; 378 } 379 380 /** 381 * Checks whether @value contains the default value as specified in @pspec. 382 * 383 * Params: 384 * pspec = a valid #GParamSpec 385 * value = a #GValue of correct type for @pspec 386 * 387 * Returns: whether @value contains the canonical default for this @pspec 388 */ 389 public static bool paramValueDefaults(ParamSpec pspec, Value value) 390 { 391 return g_param_value_defaults((pspec is null) ? null : pspec.getParamSpecStruct(), (value is null) ? null : value.getValueStruct()) != 0; 392 } 393 394 /** 395 * Sets @value to its default value as specified in @pspec. 396 * 397 * Params: 398 * pspec = a valid #GParamSpec 399 * value = a #GValue of correct type for @pspec 400 */ 401 public static void paramValueSetDefault(ParamSpec pspec, Value value) 402 { 403 g_param_value_set_default((pspec is null) ? null : pspec.getParamSpecStruct(), (value is null) ? null : value.getValueStruct()); 404 } 405 406 /** 407 * Ensures that the contents of @value comply with the specifications 408 * set out by @pspec. For example, a #GParamSpecInt might require 409 * that integers stored in @value may not be smaller than -42 and not be 410 * greater than +42. If @value contains an integer outside of this range, 411 * it is modified accordingly, so the resulting value will fit into the 412 * range -42 .. +42. 413 * 414 * Params: 415 * pspec = a valid #GParamSpec 416 * value = a #GValue of correct type for @pspec 417 * 418 * Returns: whether modifying @value was necessary to ensure validity 419 */ 420 public static bool paramValueValidate(ParamSpec pspec, Value value) 421 { 422 return g_param_value_validate((pspec is null) ? null : pspec.getParamSpecStruct(), (value is null) ? null : value.getValueStruct()) != 0; 423 } 424 425 /** 426 * Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1, 427 * if @value1 is found to be less than, equal to or greater than @value2, 428 * respectively. 429 * 430 * Params: 431 * pspec = a valid #GParamSpec 432 * value1 = a #GValue of correct type for @pspec 433 * value2 = a #GValue of correct type for @pspec 434 * 435 * Returns: -1, 0 or +1, for a less than, equal to or greater than result 436 */ 437 public static int paramValuesCmp(ParamSpec pspec, Value value1, Value value2) 438 { 439 return g_param_values_cmp((pspec is null) ? null : pspec.getParamSpecStruct(), (value1 is null) ? null : value1.getValueStruct(), (value2 is null) ? null : value2.getValueStruct()); 440 } 441 }