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