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.SettingsBackend;
26 
27 private import gio.c.functions;
28 public  import gio.c.types;
29 private import glib.BBTree;
30 private import glib.Str;
31 private import glib.Variant;
32 private import gobject.ObjectG;
33 public  import gtkc.giotypes;
34 
35 
36 /**
37  * The #GSettingsBackend interface defines a generic interface for
38  * non-strictly-typed data that is stored in a hierarchy. To implement
39  * an alternative storage backend for #GSettings, you need to implement
40  * the #GSettingsBackend interface and then make it implement the
41  * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
42  * 
43  * The interface defines methods for reading and writing values, a
44  * method for determining if writing of certain values will fail
45  * (lockdown) and a change notification mechanism.
46  * 
47  * The semantics of the interface are very precisely defined and
48  * implementations must carefully adhere to the expectations of
49  * callers that are documented on each of the interface methods.
50  * 
51  * Some of the #GSettingsBackend functions accept or return a #GTree.
52  * These trees always have strings as keys and #GVariant as values.
53  * g_settings_backend_create_tree() is a convenience function to create
54  * suitable trees.
55  * 
56  * The #GSettingsBackend API is exported to allow third-party
57  * implementations, but does not carry the same stability guarantees
58  * as the public GIO API. For this reason, you have to define the
59  * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including
60  * `gio/gsettingsbackend.h`.
61  */
62 public class SettingsBackend : ObjectG
63 {
64 	/** the main Gtk struct */
65 	protected GSettingsBackend* gSettingsBackend;
66 
67 	/** Get the main Gtk struct */
68 	public GSettingsBackend* getSettingsBackendStruct(bool transferOwnership = false)
69 	{
70 		if (transferOwnership)
71 			ownedRef = false;
72 		return gSettingsBackend;
73 	}
74 
75 	/** the main Gtk struct as a void* */
76 	protected override void* getStruct()
77 	{
78 		return cast(void*)gSettingsBackend;
79 	}
80 
81 	/**
82 	 * Sets our main struct and passes it to the parent class.
83 	 */
84 	public this (GSettingsBackend* gSettingsBackend, bool ownedRef = false)
85 	{
86 		this.gSettingsBackend = gSettingsBackend;
87 		super(cast(GObject*)gSettingsBackend, ownedRef);
88 	}
89 
90 
91 	/** */
92 	public static GType getType()
93 	{
94 		return g_settings_backend_get_type();
95 	}
96 
97 	/**
98 	 * Calculate the longest common prefix of all keys in a tree and write
99 	 * out an array of the key names relative to that prefix and,
100 	 * optionally, the value to store at each of those keys.
101 	 *
102 	 * You must free the value returned in @path, @keys and @values using
103 	 * g_free().  You should not attempt to free or unref the contents of
104 	 * @keys or @values.
105 	 *
106 	 * Params:
107 	 *     tree = a #GTree containing the changes
108 	 *     path = the location to save the path
109 	 *     keys = the
110 	 *         location to save the relative keys
111 	 *     values = the location to save the values, or %NULL
112 	 *
113 	 * Since: 2.26
114 	 */
115 	public static void flattenTree(BBTree tree, out string path, out string[] keys, out Variant[] values)
116 	{
117 		char* outpath = null;
118 		char** outkeys = null;
119 		GVariant** outvalues = null;
120 
121 		g_settings_backend_flatten_tree((tree is null) ? null : tree.getBBTreeStruct(), &outpath, &outkeys, &outvalues);
122 
123 		path = Str.toString(outpath);
124 		keys = Str.toStringArray(outkeys);
125 
126 		values = new Variant[getArrayLength(outvalues)];
127 		for(size_t i = 0; i < getArrayLength(outvalues); i++)
128 		{
129 			values[i] = new Variant(cast(GVariant*) outvalues[i]);
130 		}
131 	}
132 
133 	/**
134 	 * Returns the default #GSettingsBackend. It is possible to override
135 	 * the default by setting the `GSETTINGS_BACKEND` environment variable
136 	 * to the name of a settings backend.
137 	 *
138 	 * The user gets a reference to the backend.
139 	 *
140 	 * Returns: the default #GSettingsBackend
141 	 *
142 	 * Since: 2.28
143 	 */
144 	public static SettingsBackend getDefault()
145 	{
146 		auto p = g_settings_backend_get_default();
147 
148 		if(p is null)
149 		{
150 			return null;
151 		}
152 
153 		return ObjectG.getDObject!(SettingsBackend)(cast(GSettingsBackend*) p, true);
154 	}
155 
156 	/**
157 	 * Signals that a single key has possibly changed.  Backend
158 	 * implementations should call this if a key has possibly changed its
159 	 * value.
160 	 *
161 	 * @key must be a valid key (ie starting with a slash, not containing
162 	 * '//', and not ending with a slash).
163 	 *
164 	 * The implementation must call this function during any call to
165 	 * g_settings_backend_write(), before the call returns (except in the
166 	 * case that no keys are actually changed and it cares to detect this
167 	 * fact).  It may not rely on the existence of a mainloop for
168 	 * dispatching the signal later.
169 	 *
170 	 * The implementation may call this function at any other time it likes
171 	 * in response to other events (such as changes occurring outside of the
172 	 * program).  These calls may originate from a mainloop or may originate
173 	 * in response to any other action (including from calls to
174 	 * g_settings_backend_write()).
175 	 *
176 	 * In the case that this call is in response to a call to
177 	 * g_settings_backend_write() then @origin_tag must be set to the same
178 	 * value that was passed to that call.
179 	 *
180 	 * Params:
181 	 *     key = the name of the key
182 	 *     originTag = the origin tag
183 	 *
184 	 * Since: 2.26
185 	 */
186 	public void changed(string key, void* originTag)
187 	{
188 		g_settings_backend_changed(gSettingsBackend, Str.toStringz(key), originTag);
189 	}
190 
191 	/**
192 	 * This call is a convenience wrapper.  It gets the list of changes from
193 	 * @tree, computes the longest common prefix and calls
194 	 * g_settings_backend_changed().
195 	 *
196 	 * Params:
197 	 *     tree = a #GTree containing the changes
198 	 *     originTag = the origin tag
199 	 *
200 	 * Since: 2.26
201 	 */
202 	public void changedTree(BBTree tree, void* originTag)
203 	{
204 		g_settings_backend_changed_tree(gSettingsBackend, (tree is null) ? null : tree.getBBTreeStruct(), originTag);
205 	}
206 
207 	/**
208 	 * Signals that a list of keys have possibly changed.  Backend
209 	 * implementations should call this if keys have possibly changed their
210 	 * values.
211 	 *
212 	 * @path must be a valid path (ie starting and ending with a slash and
213 	 * not containing '//').  Each string in @items must form a valid key
214 	 * name when @path is prefixed to it (ie: each item must not start or
215 	 * end with '/' and must not contain '//').
216 	 *
217 	 * The meaning of this signal is that any of the key names resulting
218 	 * from the contatenation of @path with each item in @items may have
219 	 * changed.
220 	 *
221 	 * The same rules for when notifications must occur apply as per
222 	 * g_settings_backend_changed().  These two calls can be used
223 	 * interchangeably if exactly one item has changed (although in that
224 	 * case g_settings_backend_changed() is definitely preferred).
225 	 *
226 	 * For efficiency reasons, the implementation should strive for @path to
227 	 * be as long as possible (ie: the longest common prefix of all of the
228 	 * keys that were changed) but this is not strictly required.
229 	 *
230 	 * Params:
231 	 *     path = the path containing the changes
232 	 *     items = the %NULL-terminated list of changed keys
233 	 *     originTag = the origin tag
234 	 *
235 	 * Since: 2.26
236 	 */
237 	public void keysChanged(string path, string[] items, void* originTag)
238 	{
239 		g_settings_backend_keys_changed(gSettingsBackend, Str.toStringz(path), Str.toStringzArray(items), originTag);
240 	}
241 
242 	/**
243 	 * Signals that all keys below a given path may have possibly changed.
244 	 * Backend implementations should call this if an entire path of keys
245 	 * have possibly changed their values.
246 	 *
247 	 * @path must be a valid path (ie starting and ending with a slash and
248 	 * not containing '//').
249 	 *
250 	 * The meaning of this signal is that any of the key which has a name
251 	 * starting with @path may have changed.
252 	 *
253 	 * The same rules for when notifications must occur apply as per
254 	 * g_settings_backend_changed().  This call might be an appropriate
255 	 * reasponse to a 'reset' call but implementations are also free to
256 	 * explicitly list the keys that were affected by that call if they can
257 	 * easily do so.
258 	 *
259 	 * For efficiency reasons, the implementation should strive for @path to
260 	 * be as long as possible (ie: the longest common prefix of all of the
261 	 * keys that were changed) but this is not strictly required.  As an
262 	 * example, if this function is called with the path of "/" then every
263 	 * single key in the application will be notified of a possible change.
264 	 *
265 	 * Params:
266 	 *     path = the path containing the changes
267 	 *     originTag = the origin tag
268 	 *
269 	 * Since: 2.26
270 	 */
271 	public void pathChanged(string path, void* originTag)
272 	{
273 		g_settings_backend_path_changed(gSettingsBackend, Str.toStringz(path), originTag);
274 	}
275 
276 	/**
277 	 * Signals that the writability of all keys below a given path may have
278 	 * changed.
279 	 *
280 	 * Since GSettings performs no locking operations for itself, this call
281 	 * will always be made in response to external events.
282 	 *
283 	 * Params:
284 	 *     path = the name of the path
285 	 *
286 	 * Since: 2.26
287 	 */
288 	public void pathWritableChanged(string path)
289 	{
290 		g_settings_backend_path_writable_changed(gSettingsBackend, Str.toStringz(path));
291 	}
292 
293 	/**
294 	 * Signals that the writability of a single key has possibly changed.
295 	 *
296 	 * Since GSettings performs no locking operations for itself, this call
297 	 * will always be made in response to external events.
298 	 *
299 	 * Params:
300 	 *     key = the name of the key
301 	 *
302 	 * Since: 2.26
303 	 */
304 	public void writableChanged(string key)
305 	{
306 		g_settings_backend_writable_changed(gSettingsBackend, Str.toStringz(key));
307 	}
308 
309 	/**
310 	 * Creates a keyfile-backed #GSettingsBackend.
311 	 *
312 	 * The filename of the keyfile to use is given by @filename.
313 	 *
314 	 * All settings read to or written from the backend must fall under the
315 	 * path given in @root_path (which must start and end with a slash and
316 	 * not contain two consecutive slashes).  @root_path may be "/".
317 	 *
318 	 * If @root_group is non-%NULL then it specifies the name of the keyfile
319 	 * group used for keys that are written directly below @root_path.  For
320 	 * example, if @root_path is "/apps/example/" and @root_group is
321 	 * "toplevel", then settings the key "/apps/example/enabled" to a value
322 	 * of %TRUE will cause the following to appear in the keyfile:
323 	 *
324 	 * |[
325 	 * [toplevel]
326 	 * enabled=true
327 	 * ]|
328 	 *
329 	 * If @root_group is %NULL then it is not permitted to store keys
330 	 * directly below the @root_path.
331 	 *
332 	 * For keys not stored directly below @root_path (ie: in a sub-path),
333 	 * the name of the subpath (with the final slash stripped) is used as
334 	 * the name of the keyfile group.  To continue the example, if
335 	 * "/apps/example/profiles/default/font-size" were set to
336 	 * 12 then the following would appear in the keyfile:
337 	 *
338 	 * |[
339 	 * [profiles/default]
340 	 * font-size=12
341 	 * ]|
342 	 *
343 	 * The backend will refuse writes (and return writability as being
344 	 * %FALSE) for keys outside of @root_path and, in the event that
345 	 * @root_group is %NULL, also for keys directly under @root_path.
346 	 * Writes will also be refused if the backend detects that it has the
347 	 * inability to rewrite the keyfile (ie: the containing directory is not
348 	 * writable).
349 	 *
350 	 * There is no checking done for your key namespace clashing with the
351 	 * syntax of the key file format.  For example, if you have '[' or ']'
352 	 * characters in your path names or '=' in your key names you may be in
353 	 * trouble.
354 	 *
355 	 * Params:
356 	 *     filename = the filename of the keyfile
357 	 *     rootPath = the path under which all settings keys appear
358 	 *     rootGroup = the group name corresponding to
359 	 *         @root_path, or %NULL
360 	 *
361 	 * Returns: a keyfile-backed #GSettingsBackend
362 	 */
363 	public static SettingsBackend keyfileSettingsBackendNew(string filename, string rootPath, string rootGroup)
364 	{
365 		auto p = g_keyfile_settings_backend_new(Str.toStringz(filename), Str.toStringz(rootPath), Str.toStringz(rootGroup));
366 
367 		if(p is null)
368 		{
369 			return null;
370 		}
371 
372 		return ObjectG.getDObject!(SettingsBackend)(cast(GSettingsBackend*) p, true);
373 	}
374 
375 	/**
376 	 * Creates a memory-backed #GSettingsBackend.
377 	 *
378 	 * This backend allows changes to settings, but does not write them
379 	 * to any backing storage, so the next time you run your application,
380 	 * the memory backend will start out with the default values again.
381 	 *
382 	 * Returns: a newly created #GSettingsBackend
383 	 *
384 	 * Since: 2.28
385 	 */
386 	public static SettingsBackend memorySettingsBackendNew()
387 	{
388 		auto p = g_memory_settings_backend_new();
389 
390 		if(p is null)
391 		{
392 			return null;
393 		}
394 
395 		return ObjectG.getDObject!(SettingsBackend)(cast(GSettingsBackend*) p, true);
396 	}
397 
398 	/**
399 	 * Creates a readonly #GSettingsBackend.
400 	 *
401 	 * This backend does not allow changes to settings, so all settings
402 	 * will always have their default values.
403 	 *
404 	 * Returns: a newly created #GSettingsBackend
405 	 *
406 	 * Since: 2.28
407 	 */
408 	public static SettingsBackend nullSettingsBackendNew()
409 	{
410 		auto p = g_null_settings_backend_new();
411 
412 		if(p is null)
413 		{
414 			return null;
415 		}
416 
417 		return ObjectG.getDObject!(SettingsBackend)(cast(GSettingsBackend*) p, true);
418 	}
419 }