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