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 gio.SettingsSchema;
26 
27 private import gio.SettingsSchemaKey;
28 private import gio.c.functions;
29 public  import gio.c.types;
30 private import glib.Str;
31 private import gobject.ObjectG;
32 public  import gtkc.giotypes;
33 private import gtkd.Loader;
34 
35 
36 /**
37  * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a
38  * mechanism for advanced control over the loading of schemas and a
39  * mechanism for introspecting their content.
40  * 
41  * Plugin loading systems that wish to provide plugins a way to access
42  * settings face the problem of how to make the schemas for these
43  * settings visible to GSettings.  Typically, a plugin will want to ship
44  * the schema along with itself and it won't be installed into the
45  * standard system directories for schemas.
46  * 
47  * #GSettingsSchemaSource provides a mechanism for dealing with this by
48  * allowing the creation of a new 'schema source' from which schemas can
49  * be acquired.  This schema source can then become part of the metadata
50  * associated with the plugin and queried whenever the plugin requires
51  * access to some settings.
52  * 
53  * Consider the following example:
54  * 
55  * |[<!-- language="C" -->
56  * typedef struct
57  * {
58  * ...
59  * GSettingsSchemaSource *schema_source;
60  * ...
61  * } Plugin;
62  * 
63  * Plugin *
64  * initialise_plugin (const gchar *dir)
65  * {
66  * Plugin *plugin;
67  * 
68  * ...
69  * 
70  * plugin->schema_source =
71  * g_settings_schema_source_new_from_directory (dir,
72  * g_settings_schema_source_get_default (), FALSE, NULL);
73  * 
74  * ...
75  * 
76  * return plugin;
77  * }
78  * 
79  * ...
80  * 
81  * GSettings *
82  * plugin_get_settings (Plugin      *plugin,
83  * const gchar *schema_id)
84  * {
85  * GSettingsSchema *schema;
86  * 
87  * if (schema_id == NULL)
88  * schema_id = plugin->identifier;
89  * 
90  * schema = g_settings_schema_source_lookup (plugin->schema_source,
91  * schema_id, FALSE);
92  * 
93  * if (schema == NULL)
94  * {
95  * ... disable the plugin or abort, etc ...
96  * }
97  * 
98  * return g_settings_new_full (schema, NULL, NULL);
99  * }
100  * ]|
101  * 
102  * The code above shows how hooks should be added to the code that
103  * initialises (or enables) the plugin to create the schema source and
104  * how an API can be added to the plugin system to provide a convenient
105  * way for the plugin to access its settings, using the schemas that it
106  * ships.
107  * 
108  * From the standpoint of the plugin, it would need to ensure that it
109  * ships a gschemas.compiled file as part of itself, and then simply do
110  * the following:
111  * 
112  * |[<!-- language="C" -->
113  * {
114  * GSettings *settings;
115  * gint some_value;
116  * 
117  * settings = plugin_get_settings (self, NULL);
118  * some_value = g_settings_get_int (settings, "some-value");
119  * ...
120  * }
121  * ]|
122  * 
123  * It's also possible that the plugin system expects the schema source
124  * files (ie: .gschema.xml files) instead of a gschemas.compiled file.
125  * In that case, the plugin loading system must compile the schemas for
126  * itself before attempting to create the settings source.
127  *
128  * Since: 2.32
129  */
130 public class SettingsSchema
131 {
132 	/** the main Gtk struct */
133 	protected GSettingsSchema* gSettingsSchema;
134 	protected bool ownedRef;
135 
136 	/** Get the main Gtk struct */
137 	public GSettingsSchema* getSettingsSchemaStruct(bool transferOwnership = false)
138 	{
139 		if (transferOwnership)
140 			ownedRef = false;
141 		return gSettingsSchema;
142 	}
143 
144 	/** the main Gtk struct as a void* */
145 	protected void* getStruct()
146 	{
147 		return cast(void*)gSettingsSchema;
148 	}
149 
150 	/**
151 	 * Sets our main struct and passes it to the parent class.
152 	 */
153 	public this (GSettingsSchema* gSettingsSchema, bool ownedRef = false)
154 	{
155 		this.gSettingsSchema = gSettingsSchema;
156 		this.ownedRef = ownedRef;
157 	}
158 
159 	~this ()
160 	{
161 		if ( Linker.isLoaded(LIBRARY_GIO) && ownedRef )
162 			g_settings_schema_unref(gSettingsSchema);
163 	}
164 
165 
166 	/** */
167 	public static GType getType()
168 	{
169 		return g_settings_schema_get_type();
170 	}
171 
172 	/**
173 	 * Get the ID of @schema.
174 	 *
175 	 * Returns: the ID
176 	 */
177 	public string getId()
178 	{
179 		return Str.toString(g_settings_schema_get_id(gSettingsSchema));
180 	}
181 
182 	/**
183 	 * Gets the key named @name from @schema.
184 	 *
185 	 * It is a programmer error to request a key that does not exist.  See
186 	 * g_settings_schema_list_keys().
187 	 *
188 	 * Params:
189 	 *     name = the name of a key
190 	 *
191 	 * Returns: the #GSettingsSchemaKey for @name
192 	 *
193 	 * Since: 2.40
194 	 */
195 	public SettingsSchemaKey getKey(string name)
196 	{
197 		auto p = g_settings_schema_get_key(gSettingsSchema, Str.toStringz(name));
198 
199 		if(p is null)
200 		{
201 			return null;
202 		}
203 
204 		return ObjectG.getDObject!(SettingsSchemaKey)(cast(GSettingsSchemaKey*) p, true);
205 	}
206 
207 	/**
208 	 * Gets the path associated with @schema, or %NULL.
209 	 *
210 	 * Schemas may be single-instance or relocatable.  Single-instance
211 	 * schemas correspond to exactly one set of keys in the backend
212 	 * database: those located at the path returned by this function.
213 	 *
214 	 * Relocatable schemas can be referenced by other schemas and can
215 	 * threfore describe multiple sets of keys at different locations.  For
216 	 * relocatable schemas, this function will return %NULL.
217 	 *
218 	 * Returns: the path of the schema, or %NULL
219 	 *
220 	 * Since: 2.32
221 	 */
222 	public string getPath()
223 	{
224 		return Str.toString(g_settings_schema_get_path(gSettingsSchema));
225 	}
226 
227 	/**
228 	 * Checks if @schema has a key named @name.
229 	 *
230 	 * Params:
231 	 *     name = the name of a key
232 	 *
233 	 * Returns: %TRUE if such a key exists
234 	 *
235 	 * Since: 2.40
236 	 */
237 	public bool hasKey(string name)
238 	{
239 		return g_settings_schema_has_key(gSettingsSchema, Str.toStringz(name)) != 0;
240 	}
241 
242 	/**
243 	 * Gets the list of children in @schema.
244 	 *
245 	 * You should free the return value with g_strfreev() when you are done
246 	 * with it.
247 	 *
248 	 * Returns: a list of the children on @settings
249 	 *
250 	 * Since: 2.44
251 	 */
252 	public string[] listChildren()
253 	{
254 		auto retStr = g_settings_schema_list_children(gSettingsSchema);
255 
256 		scope(exit) Str.freeStringArray(retStr);
257 		return Str.toStringArray(retStr);
258 	}
259 
260 	/**
261 	 * Introspects the list of keys on @schema.
262 	 *
263 	 * You should probably not be calling this function from "normal" code
264 	 * (since you should already know what keys are in your schema).  This
265 	 * function is intended for introspection reasons.
266 	 *
267 	 * Returns: a list of the keys on
268 	 *     @schema
269 	 *
270 	 * Since: 2.46
271 	 */
272 	public string[] listKeys()
273 	{
274 		auto retStr = g_settings_schema_list_keys(gSettingsSchema);
275 
276 		scope(exit) Str.freeStringArray(retStr);
277 		return Str.toStringArray(retStr);
278 	}
279 
280 	/**
281 	 * Increase the reference count of @schema, returning a new reference.
282 	 *
283 	 * Returns: a new reference to @schema
284 	 *
285 	 * Since: 2.32
286 	 */
287 	public SettingsSchema doref()
288 	{
289 		auto p = g_settings_schema_ref(gSettingsSchema);
290 
291 		if(p is null)
292 		{
293 			return null;
294 		}
295 
296 		return ObjectG.getDObject!(SettingsSchema)(cast(GSettingsSchema*) p, true);
297 	}
298 
299 	/**
300 	 * Decrease the reference count of @schema, possibly freeing it.
301 	 *
302 	 * Since: 2.32
303 	 */
304 	public void unref()
305 	{
306 		g_settings_schema_unref(gSettingsSchema);
307 	}
308 }