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