gio/auto/
settings_schema.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, SettingsSchemaKey};
6use glib::translate::*;
7
8glib::wrapper! {
9    /// The [`SettingsSchemaSource`][crate::SettingsSchemaSource] and `GSettingsSchema` APIs provide a
10    /// mechanism for advanced control over the loading of schemas and a
11    /// mechanism for introspecting their content.
12    ///
13    /// Plugin loading systems that wish to provide plugins a way to access
14    /// settings face the problem of how to make the schemas for these
15    /// settings visible to GSettings.  Typically, a plugin will want to ship
16    /// the schema along with itself and it won't be installed into the
17    /// standard system directories for schemas.
18    ///
19    /// [`SettingsSchemaSource`][crate::SettingsSchemaSource] provides a mechanism for dealing with this
20    /// by allowing the creation of a new ‘schema source’ from which schemas can
21    /// be acquired.  This schema source can then become part of the metadata
22    /// associated with the plugin and queried whenever the plugin requires
23    /// access to some settings.
24    ///
25    /// Consider the following example:
26    ///
27    /// **⚠️ The following code is in c ⚠️**
28    ///
29    /// ```c
30    /// typedef struct
31    /// {
32    ///    …
33    ///    GSettingsSchemaSource *schema_source;
34    ///    …
35    /// } Plugin;
36    ///
37    /// Plugin *
38    /// initialise_plugin (const gchar *dir)
39    /// {
40    ///   Plugin *plugin;
41    ///
42    ///   …
43    ///
44    ///   plugin->schema_source =
45    ///     g_settings_schema_source_new_from_directory (dir,
46    ///       g_settings_schema_source_get_default (), FALSE, NULL);
47    ///
48    ///   …
49    ///
50    ///   return plugin;
51    /// }
52    ///
53    /// …
54    ///
55    /// GSettings *
56    /// plugin_get_settings (Plugin      *plugin,
57    ///                      const gchar *schema_id)
58    /// {
59    ///   GSettingsSchema *schema;
60    ///
61    ///   if (schema_id == NULL)
62    ///     schema_id = plugin->identifier;
63    ///
64    ///   schema = g_settings_schema_source_lookup (plugin->schema_source,
65    ///                                             schema_id, FALSE);
66    ///
67    ///   if (schema == NULL)
68    ///     {
69    ///       … disable the plugin or abort, etc …
70    ///     }
71    ///
72    ///   return g_settings_new_full (schema, NULL, NULL);
73    /// }
74    /// ```
75    ///
76    /// The code above shows how hooks should be added to the code that
77    /// initialises (or enables) the plugin to create the schema source and
78    /// how an API can be added to the plugin system to provide a convenient
79    /// way for the plugin to access its settings, using the schemas that it
80    /// ships.
81    ///
82    /// From the standpoint of the plugin, it would need to ensure that it
83    /// ships a gschemas.compiled file as part of itself, and then simply do
84    /// the following:
85    ///
86    /// **⚠️ The following code is in c ⚠️**
87    ///
88    /// ```c
89    /// {
90    ///   GSettings *settings;
91    ///   gint some_value;
92    ///
93    ///   settings = plugin_get_settings (self, NULL);
94    ///   some_value = g_settings_get_int (settings, "some-value");
95    ///   …
96    /// }
97    /// ```
98    ///
99    /// It's also possible that the plugin system expects the schema source
100    /// files (ie: `.gschema.xml` files) instead of a `gschemas.compiled` file.
101    /// In that case, the plugin loading system must compile the schemas for
102    /// itself before attempting to create the settings source.
103    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
104    pub struct SettingsSchema(Shared<ffi::GSettingsSchema>);
105
106    match fn {
107        ref => |ptr| ffi::g_settings_schema_ref(ptr),
108        unref => |ptr| ffi::g_settings_schema_unref(ptr),
109        type_ => || ffi::g_settings_schema_get_type(),
110    }
111}
112
113impl SettingsSchema {
114    /// Get the ID of @self.
115    ///
116    /// # Returns
117    ///
118    /// the ID
119    #[doc(alias = "g_settings_schema_get_id")]
120    #[doc(alias = "get_id")]
121    pub fn id(&self) -> glib::GString {
122        unsafe { from_glib_none(ffi::g_settings_schema_get_id(self.to_glib_none().0)) }
123    }
124
125    /// Gets the key named @name from @self.
126    ///
127    /// It is a programmer error to request a key that does not exist.  See
128    /// g_settings_schema_list_keys().
129    /// ## `name`
130    /// the name of a key
131    ///
132    /// # Returns
133    ///
134    /// the #GSettingsSchemaKey for @name
135    #[doc(alias = "g_settings_schema_get_key")]
136    #[doc(alias = "get_key")]
137    pub fn key(&self, name: &str) -> SettingsSchemaKey {
138        unsafe {
139            from_glib_full(ffi::g_settings_schema_get_key(
140                self.to_glib_none().0,
141                name.to_glib_none().0,
142            ))
143        }
144    }
145
146    /// Gets the path associated with @self, or [`None`].
147    ///
148    /// Schemas may be single-instance or relocatable.  Single-instance
149    /// schemas correspond to exactly one set of keys in the backend
150    /// database: those located at the path returned by this function.
151    ///
152    /// Relocatable schemas can be referenced by other schemas and can
153    /// therefore describe multiple sets of keys at different locations.  For
154    /// relocatable schemas, this function will return [`None`].
155    ///
156    /// # Returns
157    ///
158    /// the path of the schema, or [`None`]
159    #[doc(alias = "g_settings_schema_get_path")]
160    #[doc(alias = "get_path")]
161    pub fn path(&self) -> Option<glib::GString> {
162        unsafe { from_glib_none(ffi::g_settings_schema_get_path(self.to_glib_none().0)) }
163    }
164
165    /// Checks if @self has a key named @name.
166    /// ## `name`
167    /// the name of a key
168    ///
169    /// # Returns
170    ///
171    /// [`true`] if such a key exists
172    #[doc(alias = "g_settings_schema_has_key")]
173    pub fn has_key(&self, name: &str) -> bool {
174        unsafe {
175            from_glib(ffi::g_settings_schema_has_key(
176                self.to_glib_none().0,
177                name.to_glib_none().0,
178            ))
179        }
180    }
181
182    /// Gets the list of children in @self.
183    ///
184    /// You should free the return value with g_strfreev() when you are done
185    /// with it.
186    ///
187    /// # Returns
188    ///
189    /// a list of
190    ///    the children on @settings, in no defined order
191    #[doc(alias = "g_settings_schema_list_children")]
192    pub fn list_children(&self) -> Vec<glib::GString> {
193        unsafe {
194            FromGlibPtrContainer::from_glib_full(ffi::g_settings_schema_list_children(
195                self.to_glib_none().0,
196            ))
197        }
198    }
199
200    /// Introspects the list of keys on @self.
201    ///
202    /// You should probably not be calling this function from "normal" code
203    /// (since you should already know what keys are in your schema).  This
204    /// function is intended for introspection reasons.
205    ///
206    /// # Returns
207    ///
208    /// a list
209    ///   of the keys on @self, in no defined order
210    #[doc(alias = "g_settings_schema_list_keys")]
211    pub fn list_keys(&self) -> Vec<glib::GString> {
212        unsafe {
213            FromGlibPtrContainer::from_glib_full(ffi::g_settings_schema_list_keys(
214                self.to_glib_none().0,
215            ))
216        }
217    }
218}