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