source: appstream-generator/build/girepo/gobject/ParamSpec.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

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