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