1 gparam.h |
1 /* GObject - GLib Type, Object, Parameter and Signal Library |
|
2 * Copyright (C) 1997-1999, 2000-2001 Tim Janik and Red Hat, Inc. |
|
3 * Portions copyright (c) 2006 Nokia Corporation. All rights reserved. |
|
4 * |
|
5 * This library is free software; you can redistribute it and/or |
|
6 * modify it under the terms of the GNU Lesser General Public |
|
7 * License as published by the Free Software Foundation; either |
|
8 * version 2 of the License, or (at your option) any later version. |
|
9 * |
|
10 * This library 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 GNU |
|
13 * Lesser General Public License for more details. |
|
14 * |
|
15 * You should have received a copy of the GNU Lesser General |
|
16 * Public License along with this library; if not, write to the |
|
17 * Free Software Foundation, Inc., 59 Temple Place, Suite 330, |
|
18 * Boston, MA 02111-1307, USA. |
|
19 * |
|
20 * gparam.h: GParamSpec base class implementation |
|
21 */ |
|
22 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION) |
|
23 #error "Only <glib-object.h> can be included directly." |
|
24 #endif |
|
25 |
|
26 #ifndef __G_PARAM_H__ |
|
27 #define __G_PARAM_H__ |
|
28 |
|
29 #include <_ansi.h> |
|
30 #include <gobject/gvalue.h> |
|
31 |
|
32 G_BEGIN_DECLS |
|
33 |
|
34 /* --- standard type macros --- */ |
|
35 #define G_TYPE_IS_PARAM(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM) |
|
36 #define G_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec)) |
|
37 #define G_IS_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM)) |
|
38 #define G_PARAM_SPEC_CLASS(pclass) (G_TYPE_CHECK_CLASS_CAST ((pclass), G_TYPE_PARAM, GParamSpecClass)) |
|
39 #define G_IS_PARAM_SPEC_CLASS(pclass) (G_TYPE_CHECK_CLASS_TYPE ((pclass), G_TYPE_PARAM)) |
|
40 #define G_PARAM_SPEC_GET_CLASS(pspec) (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass)) |
|
41 |
|
42 |
|
43 /* --- convenience macros --- */ |
|
44 #define G_PARAM_SPEC_TYPE(pspec) (G_TYPE_FROM_INSTANCE (pspec)) |
|
45 #define G_PARAM_SPEC_TYPE_NAME(pspec) (g_type_name (G_PARAM_SPEC_TYPE (pspec))) |
|
46 #define G_PARAM_SPEC_VALUE_TYPE(pspec) (G_PARAM_SPEC (pspec)->value_type) |
|
47 #define G_VALUE_HOLDS_PARAM(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM)) |
|
48 |
|
49 |
|
50 /* --- flags --- */ |
|
51 typedef enum |
|
52 { |
|
53 G_PARAM_READABLE = 1 << 0, |
|
54 G_PARAM_WRITABLE = 1 << 1, |
|
55 G_PARAM_CONSTRUCT = 1 << 2, |
|
56 G_PARAM_CONSTRUCT_ONLY = 1 << 3, |
|
57 G_PARAM_LAX_VALIDATION = 1 << 4, |
|
58 G_PARAM_STATIC_NAME = 1 << 5, |
|
59 #ifndef G_DISABLE_DEPRECATED |
|
60 G_PARAM_PRIVATE = G_PARAM_STATIC_NAME, |
|
61 #endif |
|
62 G_PARAM_STATIC_NICK = 1 << 6, |
|
63 G_PARAM_STATIC_BLURB = 1 << 7 |
|
64 } GParamFlags; |
|
65 #define G_PARAM_READWRITE (G_PARAM_READABLE | G_PARAM_WRITABLE) |
|
66 #define G_PARAM_MASK (0x000000ff) |
|
67 /* bits in the range 0xffffff00 are reserved for 3rd party usage */ |
|
68 #define G_PARAM_USER_SHIFT (8) |
|
69 |
|
70 |
|
71 /* --- typedefs & structures --- */ |
|
72 typedef struct _GParamSpec GParamSpec; |
|
73 typedef struct _GParamSpecClass GParamSpecClass; |
|
74 typedef struct _GParameter GParameter; |
|
75 typedef struct _GParamSpecPool GParamSpecPool; |
|
76 struct _GParamSpec |
|
77 { |
|
78 GTypeInstance g_type_instance; |
|
79 |
|
80 gchar *name; |
|
81 GParamFlags flags; |
|
82 GType value_type; |
|
83 GType owner_type; /* class or interface using this property */ |
|
84 |
|
85 /*< private >*/ |
|
86 gchar *_nick; |
|
87 gchar *_blurb; |
|
88 GData *qdata; |
|
89 guint ref_count; |
|
90 guint param_id; /* sort-criteria */ |
|
91 }; |
|
92 struct _GParamSpecClass |
|
93 { |
|
94 GTypeClass g_type_class; |
|
95 |
|
96 GType value_type; |
|
97 |
|
98 void (*finalize) (GParamSpec *pspec); |
|
99 |
|
100 /* GParam methods */ |
|
101 void (*value_set_default) (GParamSpec *pspec, |
|
102 GValue *value); |
|
103 gboolean (*value_validate) (GParamSpec *pspec, |
|
104 GValue *value); |
|
105 gint (*values_cmp) (GParamSpec *pspec, |
|
106 const GValue *value1, |
|
107 const GValue *value2); |
|
108 /*< private >*/ |
|
109 gpointer dummy[4]; |
|
110 }; |
|
111 struct _GParameter /* auxillary structure for _setv() variants */ |
|
112 { |
|
113 const gchar *name; |
|
114 GValue value; |
|
115 }; |
|
116 |
|
117 |
|
118 /* --- prototypes --- */ |
|
119 IMPORT_C GParamSpec* g_param_spec_ref (GParamSpec *pspec); |
|
120 IMPORT_C void g_param_spec_unref (GParamSpec *pspec); |
|
121 IMPORT_C void g_param_spec_sink (GParamSpec *pspec); |
|
122 IMPORT_C GParamSpec* g_param_spec_ref_sink (GParamSpec *pspec); |
|
123 IMPORT_C gpointer g_param_spec_get_qdata (GParamSpec *pspec, |
|
124 GQuark quark); |
|
125 IMPORT_C void g_param_spec_set_qdata (GParamSpec *pspec, |
|
126 GQuark quark, |
|
127 gpointer data); |
|
128 IMPORT_C void g_param_spec_set_qdata_full (GParamSpec *pspec, |
|
129 GQuark quark, |
|
130 gpointer data, |
|
131 GDestroyNotify destroy); |
|
132 IMPORT_C gpointer g_param_spec_steal_qdata (GParamSpec *pspec, |
|
133 GQuark quark); |
|
134 IMPORT_C GParamSpec* g_param_spec_get_redirect_target (GParamSpec *pspec); |
|
135 |
|
136 IMPORT_C void g_param_value_set_default (GParamSpec *pspec, |
|
137 GValue *value); |
|
138 IMPORT_C gboolean g_param_value_defaults (GParamSpec *pspec, |
|
139 GValue *value); |
|
140 IMPORT_C gboolean g_param_value_validate (GParamSpec *pspec, |
|
141 GValue *value); |
|
142 IMPORT_C gboolean g_param_value_convert (GParamSpec *pspec, |
|
143 const GValue *src_value, |
|
144 GValue *dest_value, |
|
145 gboolean strict_validation); |
|
146 IMPORT_C gint g_param_values_cmp (GParamSpec *pspec, |
|
147 const GValue *value1, |
|
148 const GValue *value2); |
|
149 IMPORT_C G_CONST_RETURN gchar* g_param_spec_get_name (GParamSpec *pspec); |
|
150 IMPORT_C G_CONST_RETURN gchar* g_param_spec_get_nick (GParamSpec *pspec); |
|
151 IMPORT_C G_CONST_RETURN gchar* g_param_spec_get_blurb (GParamSpec *pspec); |
|
152 IMPORT_C void g_value_set_param (GValue *value, |
|
153 GParamSpec *param); |
|
154 IMPORT_C GParamSpec* g_value_get_param (const GValue *value); |
|
155 IMPORT_C GParamSpec* g_value_dup_param (const GValue *value); |
|
156 |
|
157 |
|
158 IMPORT_C void g_value_take_param (GValue *value, |
|
159 GParamSpec *param); |
|
160 #ifndef G_DISABLE_DEPRECATED |
|
161 IMPORT_C void g_value_set_param_take_ownership (GValue *value, |
|
162 GParamSpec *param); |
|
163 #endif |
|
164 |
|
165 /* --- convenience functions --- */ |
|
166 typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo; |
|
167 struct _GParamSpecTypeInfo |
|
168 { |
|
169 /* type system portion */ |
|
170 guint16 instance_size; /* obligatory */ |
|
171 guint16 n_preallocs; /* optional */ |
|
172 void (*instance_init) (GParamSpec *pspec); /* optional */ |
|
173 |
|
174 /* class portion */ |
|
175 GType value_type; /* obligatory */ |
|
176 void (*finalize) (GParamSpec *pspec); /* optional */ |
|
177 void (*value_set_default) (GParamSpec *pspec, /* recommended */ |
|
178 GValue *value); |
|
179 gboolean (*value_validate) (GParamSpec *pspec, /* optional */ |
|
180 GValue *value); |
|
181 gint (*values_cmp) (GParamSpec *pspec, /* recommended */ |
|
182 const GValue *value1, |
|
183 const GValue *value2); |
|
184 }; |
|
185 IMPORT_C GType g_param_type_register_static (const gchar *name, |
|
186 const GParamSpecTypeInfo *pspec_info); |
|
187 |
|
188 /* For registering builting types */ |
|
189 GType _g_param_type_register_static_constant (const gchar *name, |
|
190 const GParamSpecTypeInfo *pspec_info, |
|
191 GType opt_type); |
|
192 |
|
193 |
|
194 /* --- protected --- */ |
|
195 IMPORT_C gpointer g_param_spec_internal (GType param_type, |
|
196 const gchar *name, |
|
197 const gchar *nick, |
|
198 const gchar *blurb, |
|
199 GParamFlags flags); |
|
200 IMPORT_C GParamSpecPool* g_param_spec_pool_new (gboolean type_prefixing); |
|
201 IMPORT_C void g_param_spec_pool_insert (GParamSpecPool *pool, |
|
202 GParamSpec *pspec, |
|
203 GType owner_type); |
|
204 IMPORT_C void g_param_spec_pool_remove (GParamSpecPool *pool, |
|
205 GParamSpec *pspec); |
|
206 IMPORT_C GParamSpec* g_param_spec_pool_lookup (GParamSpecPool *pool, |
|
207 const gchar *param_name, |
|
208 GType owner_type, |
|
209 gboolean walk_ancestors); |
|
210 IMPORT_C GList* g_param_spec_pool_list_owned (GParamSpecPool *pool, |
|
211 GType owner_type); |
|
212 IMPORT_C GParamSpec** g_param_spec_pool_list (GParamSpecPool *pool, |
|
213 GType owner_type, |
|
214 guint *n_pspecs_p); |
|
215 |
|
216 |
|
217 |
|
218 /* contracts: |
|
219 * |
|
220 * gboolean value_validate (GParamSpec *pspec, |
|
221 * GValue *value): |
|
222 * modify value contents in the least destructive way, so |
|
223 * that it complies with pspec's requirements (i.e. |
|
224 * according to minimum/maximum ranges etc...). return |
|
225 * whether modification was necessary. |
|
226 * |
|
227 * gint values_cmp (GParamSpec *pspec, |
|
228 * const GValue *value1, |
|
229 * const GValue *value2): |
|
230 * return value1 - value2, i.e. (-1) if value1 < value2, |
|
231 * (+1) if value1 > value2, and (0) otherwise (equality) |
|
232 */ |
|
233 |
|
234 G_END_DECLS |
|
235 |
|
236 #endif /* __G_PARAM_H__ */ |