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}