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 }