gio/auto/settings.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
5#[cfg(feature = "v2_82")]
6#[cfg_attr(docsrs, doc(cfg(feature = "v2_82")))]
7use crate::SettingsBindFlags;
8use crate::{ffi, Action, SettingsBackend, SettingsSchema};
9use glib::{
10 object::ObjectType as _,
11 prelude::*,
12 signal::{connect_raw, SignalHandlerId},
13 translate::*,
14};
15use std::boxed::Box as Box_;
16
17glib::wrapper! {
18 /// The `GSettings` class provides a convenient API for storing and retrieving
19 /// application settings.
20 ///
21 /// Reads and writes can be considered to be non-blocking. Reading
22 /// settings with `GSettings` is typically extremely fast: on
23 /// approximately the same order of magnitude (but slower than) a
24 /// `GLib::HashTable` lookup. Writing settings is also extremely fast in
25 /// terms of time to return to your application, but can be extremely expensive
26 /// for other threads and other processes. Many settings backends
27 /// (including dconf) have lazy initialisation which means in the common
28 /// case of the user using their computer without modifying any settings
29 /// a lot of work can be avoided. For dconf, the D-Bus service doesn’t
30 /// even need to be started in this case. For this reason, you should
31 /// only ever modify `GSettings` keys in response to explicit user action.
32 /// Particular care should be paid to ensure that modifications are not
33 /// made during startup — for example, when setting the initial value
34 /// of preferences widgets. The built-in [`SettingsExtManual::bind()`][crate::prelude::SettingsExtManual::bind()]
35 /// functionality is careful not to write settings in response to notify signals
36 /// as a result of modifications that it makes to widgets.
37 ///
38 /// When creating a `GSettings` instance, you have to specify a schema
39 /// that describes the keys in your settings and their types and default
40 /// values, as well as some other information.
41 ///
42 /// Normally, a schema has a fixed path that determines where the settings
43 /// are stored in the conceptual global tree of settings. However, schemas
44 /// can also be ‘[relocatable](#relocatable-schemas)’, i.e. not equipped with
45 /// a fixed path. This is
46 /// useful e.g. when the schema describes an ‘account’, and you want to be
47 /// able to store a arbitrary number of accounts.
48 ///
49 /// Paths must start with and end with a forward slash character (`/`)
50 /// and must not contain two sequential slash characters. Paths should
51 /// be chosen based on a domain name associated with the program or
52 /// library to which the settings belong. Examples of paths are
53 /// `/org/gtk/settings/file-chooser/` and `/ca/desrt/dconf-editor/`.
54 /// Paths should not start with `/apps/`, `/desktop/` or `/system/` as
55 /// they often did in GConf.
56 ///
57 /// Unlike other configuration systems (like GConf), GSettings does not
58 /// restrict keys to basic types like strings and numbers. GSettings stores
59 /// values as [`glib::Variant`][struct@crate::glib::Variant], and allows any [type@GLib.VariantType] for
60 /// keys. Key names are restricted to lowercase characters, numbers and `-`.
61 /// Furthermore, the names must begin with a lowercase character, must not end
62 /// with a `-`, and must not contain consecutive dashes.
63 ///
64 /// Similar to GConf, the default values in GSettings schemas can be
65 /// localized, but the localized values are stored in gettext catalogs
66 /// and looked up with the domain that is specified in the
67 /// `gettext-domain` attribute of the `<schemalist>` or `<schema>`
68 /// elements and the category that is specified in the `l10n` attribute of
69 /// the `<default>` element. The string which is translated includes all text in
70 /// the `<default>` element, including any surrounding quotation marks.
71 ///
72 /// The `l10n` attribute must be set to `messages` or `time`, and sets the
73 /// [locale category for
74 /// translation](https://www.gnu.org/software/gettext/manual/html_node/Aspects.html#index-locale-categories-1).
75 /// The `messages` category should be used by default; use `time` for
76 /// translatable date or time formats. A translation comment can be added as an
77 /// XML comment immediately above the `<default>` element — it is recommended to
78 /// add these comments to aid translators understand the meaning and
79 /// implications of the default value. An optional translation `context`
80 /// attribute can be set on the `<default>` element to disambiguate multiple
81 /// defaults which use the same string.
82 ///
83 /// For example:
84 /// ```xml
85 /// <!-- Translators: A list of words which are not allowed to be typed, in
86 /// GVariant serialization syntax.
87 /// See: https://developer.gnome.org/glib/stable/gvariant-text.html -->
88 /// <default l10n='messages' context='Banned words'>['bad', 'words']</default>
89 /// ```
90 ///
91 /// Translations of default values must remain syntactically valid serialized
92 /// [`glib::Variant`][struct@crate::glib::Variant]s (e.g. retaining any surrounding quotation marks) or
93 /// runtime errors will occur.
94 ///
95 /// GSettings uses schemas in a compact binary form that is created
96 /// by the [`glib-compile-schemas`](glib-compile-schemas.html)
97 /// utility. The input is a schema description in an XML format.
98 ///
99 /// A DTD for the gschema XML format can be found here:
100 /// [gschema.dtd](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/gschema.dtd)
101 ///
102 /// The [`glib-compile-schemas`](glib-compile-schemas.html) tool expects schema
103 /// files to have the extension `.gschema.xml`.
104 ///
105 /// At runtime, schemas are identified by their ID (as specified in the
106 /// `id` attribute of the `<schema>` element). The convention for schema
107 /// IDs is to use a dotted name, similar in style to a D-Bus bus name,
108 /// e.g. `org.gnome.SessionManager`. In particular, if the settings are
109 /// for a specific service that owns a D-Bus bus name, the D-Bus bus name
110 /// and schema ID should match. For schemas which deal with settings not
111 /// associated with one named application, the ID should not use
112 /// StudlyCaps, e.g. `org.gnome.font-rendering`.
113 ///
114 /// In addition to [`glib::Variant`][struct@crate::glib::Variant] types, keys can have types that have
115 /// enumerated types. These can be described by a `<choice>`,
116 /// `<enum>` or `<flags>` element, as seen in the
117 /// second example below. The underlying type of such a key
118 /// is string, but you can use [`SettingsExt::enum_()`][crate::prelude::SettingsExt::enum_()],
119 /// [`SettingsExt::set_enum()`][crate::prelude::SettingsExt::set_enum()], [`SettingsExt::flags()`][crate::prelude::SettingsExt::flags()],
120 /// [`SettingsExt::set_flags()`][crate::prelude::SettingsExt::set_flags()] access the numeric values corresponding to
121 /// the string value of enum and flags keys.
122 ///
123 /// An example for default value:
124 /// ```xml
125 /// <schemalist>
126 /// <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">
127 ///
128 /// <key name="greeting" type="s">
129 /// <default l10n="messages">"Hello, earthlings"</default>
130 /// <summary>A greeting</summary>
131 /// <description>
132 /// Greeting of the invading martians
133 /// </description>
134 /// </key>
135 ///
136 /// <key name="box" type="(ii)">
137 /// <default>(20,30)</default>
138 /// </key>
139 ///
140 /// <key name="empty-string" type="s">
141 /// <default>""</default>
142 /// <summary>Empty strings have to be provided in GVariant form</summary>
143 /// </key>
144 ///
145 /// </schema>
146 /// </schemalist>
147 /// ```
148 ///
149 /// An example for ranges, choices and enumerated types:
150 /// ```xml
151 /// <schemalist>
152 ///
153 /// <enum id="org.gtk.Test.myenum">
154 /// <value nick="first" value="1"/>
155 /// <value nick="second" value="2"/>
156 /// </enum>
157 ///
158 /// <flags id="org.gtk.Test.myflags">
159 /// <value nick="flag1" value="1"/>
160 /// <value nick="flag2" value="2"/>
161 /// <value nick="flag3" value="4"/>
162 /// </flags>
163 ///
164 /// <schema id="org.gtk.Test">
165 ///
166 /// <key name="key-with-range" type="i">
167 /// <range min="1" max="100"/>
168 /// <default>10</default>
169 /// </key>
170 ///
171 /// <key name="key-with-choices" type="s">
172 /// <choices>
173 /// <choice value='Elisabeth'/>
174 /// <choice value='Annabeth'/>
175 /// <choice value='Joe'/>
176 /// </choices>
177 /// <aliases>
178 /// <alias value='Anna' target='Annabeth'/>
179 /// <alias value='Beth' target='Elisabeth'/>
180 /// </aliases>
181 /// <default>'Joe'</default>
182 /// </key>
183 ///
184 /// <key name='enumerated-key' enum='org.gtk.Test.myenum'>
185 /// <default>'first'</default>
186 /// </key>
187 ///
188 /// <key name='flags-key' flags='org.gtk.Test.myflags'>
189 /// <default>["flag1","flag2"]</default>
190 /// </key>
191 /// </schema>
192 /// </schemalist>
193 /// ```
194 ///
195 /// ## Vendor overrides
196 ///
197 /// Default values are defined in the schemas that get installed by
198 /// an application. Sometimes, it is necessary for a vendor or distributor
199 /// to adjust these defaults. Since patching the XML source for the schema
200 /// is inconvenient and error-prone,
201 /// [`glib-compile-schemas`](glib-compile-schemas.html) reads so-called ‘vendor
202 /// override’ files. These are keyfiles in the same directory as the XML
203 /// schema sources which can override default values. The schema ID serves
204 /// as the group name in the key file, and the values are expected in
205 /// serialized [`glib::Variant`][struct@crate::glib::Variant] form, as in the following example:
206 /// ```text
207 /// [org.gtk.Example]
208 /// key1='string'
209 /// key2=1.5
210 /// ```
211 ///
212 /// `glib-compile-schemas` expects schema files to have the extension
213 /// `.gschema.override`.
214 ///
215 /// ## Binding
216 ///
217 /// A very convenient feature of GSettings lets you bind [`glib::Object`][crate::glib::Object]
218 /// properties directly to settings, using [`SettingsExtManual::bind()`][crate::prelude::SettingsExtManual::bind()]. Once a
219 /// [`glib::Object`][crate::glib::Object] property has been bound to a setting, changes on
220 /// either side are automatically propagated to the other side. GSettings handles
221 /// details like mapping between [`glib::Object`][crate::glib::Object] and [`glib::Variant`][struct@crate::glib::Variant]
222 /// types, and preventing infinite cycles.
223 ///
224 /// This makes it very easy to hook up a preferences dialog to the
225 /// underlying settings. To make this even more convenient, GSettings
226 /// looks for a boolean property with the name `sensitivity` and
227 /// automatically binds it to the writability of the bound setting.
228 /// If this ‘magic’ gets in the way, it can be suppressed with the
229 /// `G_SETTINGS_BIND_NO_SENSITIVITY` flag.
230 ///
231 /// ## Relocatable schemas
232 ///
233 /// A relocatable schema is one with no `path` attribute specified on its
234 /// `<schema>` element. By using [`with_path()`][Self::with_path()], a `GSettings`
235 /// object can be instantiated for a relocatable schema, assigning a path to the
236 /// instance. Paths passed to [`with_path()`][Self::with_path()] will typically be
237 /// constructed dynamically from a constant prefix plus some form of instance
238 /// identifier; but they must still be valid GSettings paths. Paths could also
239 /// be constant and used with a globally installed schema originating from a
240 /// dependency library.
241 ///
242 /// For example, a relocatable schema could be used to store geometry information
243 /// for different windows in an application. If the schema ID was
244 /// `org.foo.MyApp.Window`, it could be instantiated for paths
245 /// `/org/foo/MyApp/main/`, `/org/foo/MyApp/document-1/`,
246 /// `/org/foo/MyApp/document-2/`, etc. If any of the paths are well-known
247 /// they can be specified as `<child>` elements in the parent schema, e.g.:
248 /// ```xml
249 /// <schema id="org.foo.MyApp" path="/org/foo/MyApp/">
250 /// <child name="main" schema="org.foo.MyApp.Window"/>
251 /// </schema>
252 /// ```
253 ///
254 /// ## Build system integration
255 ///
256 /// ### Meson
257 ///
258 /// GSettings is natively supported by Meson's [GNOME module](https://mesonbuild.com/Gnome-module.html).
259 ///
260 /// You can install the schemas as any other data file:
261 ///
262 /// ```text
263 /// install_data(
264 /// 'org.foo.MyApp.gschema.xml',
265 /// install_dir: get_option('datadir') / 'glib-2.0/schemas',
266 /// )
267 /// ```
268 ///
269 /// You can use `gnome.post_install()` function to compile the schemas on
270 /// installation:
271 ///
272 /// ```text
273 /// gnome = import('gnome')
274 /// gnome.post_install(
275 /// glib_compile_schemas: true,
276 /// )
277 /// ```
278 ///
279 /// If an enumerated type defined in a C header file is to be used in a GSettings
280 /// schema, it can either be defined manually using an `<enum>` element in the
281 /// schema XML, or it can be extracted automatically from the C header. This
282 /// approach is preferred, as it ensures the two representations are always
283 /// synchronised. To do so, you will need to use the `gnome.mkenums()` function
284 /// with the following templates:
285 ///
286 /// ```text
287 /// schemas_enums = gnome.mkenums('org.foo.MyApp.enums.xml',
288 /// comments: '<!-- @comment@ -->',
289 /// fhead: '<schemalist>',
290 /// vhead: ' <@type@ id="org.foo.MyApp.@EnumName@">',
291 /// vprod: ' <value nick="@valuenick@" value="@valuenum@"/>',
292 /// vtail: ' </@type@>',
293 /// ftail: '</schemalist>',
294 /// sources: enum_sources,
295 /// install_header: true,
296 /// install_dir: get_option('datadir') / 'glib-2.0/schemas',
297 /// )
298 /// ```
299 ///
300 /// It is recommended to validate your schemas as part of the test suite for
301 /// your application:
302 ///
303 /// ```text
304 /// test('validate-schema',
305 /// find_program('glib-compile-schemas'),
306 /// args: ['--strict', '--dry-run', meson.current_source_dir()],
307 /// )
308 /// ```
309 ///
310 /// If your application allows running uninstalled, you should also use the
311 /// `gnome.compile_schemas()` function to compile the schemas in the current
312 /// build directory:
313 ///
314 /// ```text
315 /// gnome.compile_schemas()
316 /// ```
317 ///
318 /// ### Autotools
319 ///
320 /// GSettings comes with autotools integration to simplify compiling and
321 /// installing schemas. To add GSettings support to an application, add the
322 /// following to your `configure.ac`:
323 /// ```text
324 /// GLIB_GSETTINGS
325 /// ```
326 ///
327 /// In the appropriate `Makefile.am`, use the following snippet to compile and
328 /// install the named schema:
329 /// ```text
330 /// gsettings_SCHEMAS = org.foo.MyApp.gschema.xml
331 /// EXTRA_DIST = $(gsettings_SCHEMAS)
332 ///
333 /// @GSETTINGS_RULES@
334 /// ```
335 ///
336 /// If an enumerated type defined in a C header file is to be used in a GSettings
337 /// schema, it can either be defined manually using an `<enum>` element in the
338 /// schema XML, or it can be extracted automatically from the C header. This
339 /// approach is preferred, as it ensures the two representations are always
340 /// synchronised. To do so, add the following to the relevant `Makefile.am`:
341 /// ```text
342 /// gsettings_ENUM_NAMESPACE = org.foo.MyApp
343 /// gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h
344 /// ```
345 ///
346 /// `gsettings_ENUM_NAMESPACE` specifies the schema namespace for the enum files,
347 /// which are specified in `gsettings_ENUM_FILES`. This will generate a
348 /// `org.foo.MyApp.enums.xml` file containing the extracted enums, which will be
349 /// automatically included in the schema compilation, install and uninstall
350 /// rules. It should not be committed to version control or included in
351 /// `EXTRA_DIST`.
352 ///
353 /// ## Localization
354 ///
355 /// No changes are needed to the build system to mark a schema XML file for
356 /// translation. Assuming it sets the `gettext-domain` attribute, a schema may
357 /// be marked for translation by adding it to `POTFILES.in`, assuming gettext
358 /// 0.19 or newer is in use (the preferred method for translation):
359 /// ```text
360 /// data/org.foo.MyApp.gschema.xml
361 /// ```
362 ///
363 /// Alternatively, if intltool 0.50.1 is in use:
364 /// ```text
365 /// [type: gettext/gsettings]data/org.foo.MyApp.gschema.xml
366 /// ```
367 ///
368 /// GSettings will use gettext to look up translations for the `<summary>` and
369 /// `<description>` elements, and also any `<default>` elements which have a
370 /// `l10n` attribute set.
371 ///
372 /// Translations **must not** be included in the `.gschema.xml` file by the build
373 /// system, for example by using a rule to generate the XML file from a template.
374 ///
375 /// ## Properties
376 ///
377 ///
378 /// #### `backend`
379 /// The name of the context that the settings are stored in.
380 ///
381 /// Readable | Writeable | Construct Only
382 ///
383 ///
384 /// #### `delay-apply`
385 /// Whether the #GSettings object is in 'delay-apply' mode. See
386 /// g_settings_delay() for details.
387 ///
388 /// Readable
389 ///
390 ///
391 /// #### `has-unapplied`
392 /// If this property is [`true`], the #GSettings object has outstanding
393 /// changes that will be applied when g_settings_apply() is called.
394 ///
395 /// Readable
396 ///
397 ///
398 /// #### `path`
399 /// The path within the backend where the settings are stored.
400 ///
401 /// Readable | Writeable | Construct Only
402 ///
403 ///
404 /// #### `schema`
405 /// The name of the schema that describes the types of keys
406 /// for this #GSettings object.
407 ///
408 /// The type of this property is *not* #GSettingsSchema.
409 /// #GSettingsSchema has only existed since version 2.32 and
410 /// unfortunately this name was used in previous versions to refer to
411 /// the schema ID rather than the schema itself. Take care to use the
412 /// 'settings-schema' property if you wish to pass in a
413 /// #GSettingsSchema.
414 ///
415 /// Readable | Writeable | Construct Only
416 ///
417 ///
418 /// #### `schema-id`
419 /// The name of the schema that describes the types of keys
420 /// for this #GSettings object.
421 ///
422 /// Readable | Writeable | Construct Only
423 ///
424 ///
425 /// #### `settings-schema`
426 /// The #GSettingsSchema describing the types of keys for this
427 /// #GSettings object.
428 ///
429 /// Ideally, this property would be called 'schema'. #GSettingsSchema
430 /// has only existed since version 2.32, however, and before then the
431 /// 'schema' property was used to refer to the ID of the schema rather
432 /// than the schema itself. Take care.
433 ///
434 /// Readable | Writeable | Construct Only
435 ///
436 /// ## Signals
437 ///
438 ///
439 /// #### `change-event`
440 /// The "change-event" signal is emitted once per change event that
441 /// affects this settings object. You should connect to this signal
442 /// only if you are interested in viewing groups of changes before they
443 /// are split out into multiple emissions of the "changed" signal.
444 /// For most use cases it is more appropriate to use the "changed" signal.
445 ///
446 /// In the event that the change event applies to one or more specified
447 /// keys, @keys will be an array of #GQuark of length @n_keys. In the
448 /// event that the change event applies to the #GSettings object as a
449 /// whole (ie: potentially every key has been changed) then @keys will
450 /// be [`None`] and @n_keys will be 0.
451 ///
452 /// The default handler for this signal invokes the "changed" signal
453 /// for each affected key. If any other connected handler returns
454 /// [`true`] then this default functionality will be suppressed.
455 ///
456 ///
457 ///
458 ///
459 /// #### `changed`
460 /// The "changed" signal is emitted when a key has potentially changed.
461 /// You should call one of the g_settings_get() calls to check the new
462 /// value.
463 ///
464 /// This signal supports detailed connections. You can connect to the
465 /// detailed signal "changed::x" in order to only receive callbacks
466 /// when key "x" changes.
467 ///
468 /// Note that @settings only emits this signal if you have read @key at
469 /// least once while a signal handler was already connected for @key.
470 ///
471 /// Detailed
472 ///
473 ///
474 /// #### `writable-change-event`
475 /// The "writable-change-event" signal is emitted once per writability
476 /// change event that affects this settings object. You should connect
477 /// to this signal if you are interested in viewing groups of changes
478 /// before they are split out into multiple emissions of the
479 /// "writable-changed" signal. For most use cases it is more
480 /// appropriate to use the "writable-changed" signal.
481 ///
482 /// In the event that the writability change applies only to a single
483 /// key, @key will be set to the #GQuark for that key. In the event
484 /// that the writability change affects the entire settings object,
485 /// @key will be 0.
486 ///
487 /// The default handler for this signal invokes the "writable-changed"
488 /// and "changed" signals for each affected key. This is done because
489 /// changes in writability might also imply changes in value (if for
490 /// example, a new mandatory setting is introduced). If any other
491 /// connected handler returns [`true`] then this default functionality
492 /// will be suppressed.
493 ///
494 ///
495 ///
496 ///
497 /// #### `writable-changed`
498 /// The "writable-changed" signal is emitted when the writability of a
499 /// key has potentially changed. You should call
500 /// g_settings_is_writable() in order to determine the new status.
501 ///
502 /// This signal supports detailed connections. You can connect to the
503 /// detailed signal "writable-changed::x" in order to only receive
504 /// callbacks when the writability of "x" changes.
505 ///
506 /// Detailed
507 ///
508 /// # Implements
509 ///
510 /// [`SettingsExt`][trait@crate::prelude::SettingsExt], [`trait@glib::ObjectExt`], [`SettingsExtManual`][trait@crate::prelude::SettingsExtManual]
511 #[doc(alias = "GSettings")]
512 pub struct Settings(Object<ffi::GSettings, ffi::GSettingsClass>);
513
514 match fn {
515 type_ => || ffi::g_settings_get_type(),
516 }
517}
518
519impl Settings {
520 pub const NONE: Option<&'static Settings> = None;
521
522 /// Creates a new #GSettings object with the schema specified by
523 /// @schema_id.
524 ///
525 /// It is an error for the schema to not exist: schemas are an
526 /// essential part of a program, as they provide type information.
527 /// If schemas need to be dynamically loaded (for example, from an
528 /// optional runtime dependency), g_settings_schema_source_lookup()
529 /// can be used to test for their existence before loading them.
530 ///
531 /// Signals on the newly created #GSettings object will be dispatched
532 /// via the thread-default #GMainContext in effect at the time of the
533 /// call to g_settings_new(). The new #GSettings will hold a reference
534 /// on the context. See g_main_context_push_thread_default().
535 /// ## `schema_id`
536 /// the id of the schema
537 ///
538 /// # Returns
539 ///
540 /// a new #GSettings object
541 #[doc(alias = "g_settings_new")]
542 pub fn new(schema_id: &str) -> Settings {
543 unsafe { from_glib_full(ffi::g_settings_new(schema_id.to_glib_none().0)) }
544 }
545
546 /// Creates a new #GSettings object with a given schema, backend and
547 /// path.
548 ///
549 /// It should be extremely rare that you ever want to use this function.
550 /// It is made available for advanced use-cases (such as plugin systems
551 /// that want to provide access to schemas loaded from custom locations,
552 /// etc).
553 ///
554 /// At the most basic level, a #GSettings object is a pure composition of
555 /// 4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that
556 /// backend, and a #GMainContext to which signals are dispatched.
557 ///
558 /// This constructor therefore gives you full control over constructing
559 /// #GSettings instances. The first 3 parameters are given directly as
560 /// @schema, @backend and @path, and the main context is taken from the
561 /// thread-default (as per g_settings_new()).
562 ///
563 /// If @backend is [`None`] then the default backend is used.
564 ///
565 /// If @path is [`None`] then the path from the schema is used. It is an
566 /// error if @path is [`None`] and the schema has no path of its own or if
567 /// @path is non-[`None`] and not equal to the path that the schema does
568 /// have.
569 /// ## `schema`
570 /// a #GSettingsSchema
571 /// ## `backend`
572 /// a #GSettingsBackend
573 /// ## `path`
574 /// the path to use
575 ///
576 /// # Returns
577 ///
578 /// a new #GSettings object
579 #[doc(alias = "g_settings_new_full")]
580 pub fn new_full(
581 schema: &SettingsSchema,
582 backend: Option<&impl IsA<SettingsBackend>>,
583 path: Option<&str>,
584 ) -> Settings {
585 unsafe {
586 from_glib_full(ffi::g_settings_new_full(
587 schema.to_glib_none().0,
588 backend.map(|p| p.as_ref()).to_glib_none().0,
589 path.to_glib_none().0,
590 ))
591 }
592 }
593
594 /// Creates a new #GSettings object with the schema specified by
595 /// @schema_id and a given #GSettingsBackend.
596 ///
597 /// Creating a #GSettings object with a different backend allows accessing
598 /// settings from a database other than the usual one. For example, it may make
599 /// sense to pass a backend corresponding to the "defaults" settings database on
600 /// the system to get a settings object that modifies the system default
601 /// settings instead of the settings for this user.
602 /// ## `schema_id`
603 /// the id of the schema
604 /// ## `backend`
605 /// the #GSettingsBackend to use
606 ///
607 /// # Returns
608 ///
609 /// a new #GSettings object
610 #[doc(alias = "g_settings_new_with_backend")]
611 #[doc(alias = "new_with_backend")]
612 pub fn with_backend(schema_id: &str, backend: &impl IsA<SettingsBackend>) -> Settings {
613 unsafe {
614 from_glib_full(ffi::g_settings_new_with_backend(
615 schema_id.to_glib_none().0,
616 backend.as_ref().to_glib_none().0,
617 ))
618 }
619 }
620
621 /// Creates a new #GSettings object with the schema specified by
622 /// @schema_id and a given #GSettingsBackend and path.
623 ///
624 /// This is a mix of g_settings_new_with_backend() and
625 /// g_settings_new_with_path().
626 /// ## `schema_id`
627 /// the id of the schema
628 /// ## `backend`
629 /// the #GSettingsBackend to use
630 /// ## `path`
631 /// the path to use
632 ///
633 /// # Returns
634 ///
635 /// a new #GSettings object
636 #[doc(alias = "g_settings_new_with_backend_and_path")]
637 #[doc(alias = "new_with_backend_and_path")]
638 pub fn with_backend_and_path(
639 schema_id: &str,
640 backend: &impl IsA<SettingsBackend>,
641 path: &str,
642 ) -> Settings {
643 unsafe {
644 from_glib_full(ffi::g_settings_new_with_backend_and_path(
645 schema_id.to_glib_none().0,
646 backend.as_ref().to_glib_none().0,
647 path.to_glib_none().0,
648 ))
649 }
650 }
651
652 /// Creates a new #GSettings object with the relocatable schema specified
653 /// by @schema_id and a given path.
654 ///
655 /// You only need to do this if you want to directly create a settings
656 /// object with a schema that doesn't have a specified path of its own.
657 /// That's quite rare.
658 ///
659 /// It is a programmer error to call this function for a schema that
660 /// has an explicitly specified path.
661 ///
662 /// It is a programmer error if @path is not a valid path. A valid path
663 /// begins and ends with '/' and does not contain two consecutive '/'
664 /// characters.
665 /// ## `schema_id`
666 /// the id of the schema
667 /// ## `path`
668 /// the path to use
669 ///
670 /// # Returns
671 ///
672 /// a new #GSettings object
673 #[doc(alias = "g_settings_new_with_path")]
674 #[doc(alias = "new_with_path")]
675 pub fn with_path(schema_id: &str, path: &str) -> Settings {
676 unsafe {
677 from_glib_full(ffi::g_settings_new_with_path(
678 schema_id.to_glib_none().0,
679 path.to_glib_none().0,
680 ))
681 }
682 }
683
684 /// Ensures that all pending operations are complete for the default backend.
685 ///
686 /// Writes made to a #GSettings are handled asynchronously. For this
687 /// reason, it is very unlikely that the changes have it to disk by the
688 /// time g_settings_set() returns.
689 ///
690 /// This call will block until all of the writes have made it to the
691 /// backend. Since the mainloop is not running, no change notifications
692 /// will be dispatched during this call (but some may be queued by the
693 /// time the call is done).
694 #[doc(alias = "g_settings_sync")]
695 pub fn sync() {
696 unsafe {
697 ffi::g_settings_sync();
698 }
699 }
700
701 /// Removes an existing binding for @property on @object.
702 ///
703 /// Note that bindings are automatically removed when the
704 /// object is finalized, so it is rarely necessary to call this
705 /// function.
706 /// ## `object`
707 /// the object
708 /// ## `property`
709 /// the property whose binding is removed
710 #[doc(alias = "g_settings_unbind")]
711 pub fn unbind(object: &impl IsA<glib::Object>, property: &str) {
712 unsafe {
713 ffi::g_settings_unbind(object.as_ref().to_glib_none().0, property.to_glib_none().0);
714 }
715 }
716}
717
718mod sealed {
719 pub trait Sealed {}
720 impl<T: super::IsA<super::Settings>> Sealed for T {}
721}
722
723/// Trait containing all [`struct@Settings`] methods.
724///
725/// # Implementors
726///
727/// [`Settings`][struct@crate::Settings]
728pub trait SettingsExt: IsA<Settings> + sealed::Sealed + 'static {
729 /// Applies any changes that have been made to the settings. This
730 /// function does nothing unless @self is in 'delay-apply' mode;
731 /// see g_settings_delay(). In the normal case settings are always
732 /// applied immediately.
733 #[doc(alias = "g_settings_apply")]
734 fn apply(&self) {
735 unsafe {
736 ffi::g_settings_apply(self.as_ref().to_glib_none().0);
737 }
738 }
739
740 /// Version of g_settings_bind_with_mapping() using closures instead of callbacks
741 /// for easier binding in other languages.
742 /// ## `key`
743 /// the key to bind
744 /// ## `object`
745 /// a #GObject
746 /// ## `property`
747 /// the name of the property to bind
748 /// ## `flags`
749 /// flags for the binding
750 /// ## `get_mapping`
751 /// a function that gets called to convert values
752 /// from @self to @object, or [`None`] to use the default GIO mapping
753 /// ## `set_mapping`
754 /// a function that gets called to convert values
755 /// from @object to @self, or [`None`] to use the default GIO mapping
756 #[cfg(feature = "v2_82")]
757 #[cfg_attr(docsrs, doc(cfg(feature = "v2_82")))]
758 #[doc(alias = "g_settings_bind_with_mapping_closures")]
759 fn bind_with_mapping_closures(
760 &self,
761 key: &str,
762 object: &impl IsA<glib::Object>,
763 property: &str,
764 flags: SettingsBindFlags,
765 get_mapping: Option<&glib::Closure>,
766 set_mapping: Option<&glib::Closure>,
767 ) {
768 unsafe {
769 ffi::g_settings_bind_with_mapping_closures(
770 self.as_ref().to_glib_none().0,
771 key.to_glib_none().0,
772 object.as_ref().to_glib_none().0,
773 property.to_glib_none().0,
774 flags.into_glib(),
775 get_mapping.to_glib_none().0,
776 set_mapping.to_glib_none().0,
777 );
778 }
779 }
780
781 /// Create a binding between the writability of @key in the
782 /// @self object and the property @property of @object.
783 /// The property must be boolean; "sensitive" or "visible"
784 /// properties of widgets are the most likely candidates.
785 ///
786 /// Writable bindings are always uni-directional; changes of the
787 /// writability of the setting will be propagated to the object
788 /// property, not the other way.
789 ///
790 /// When the @inverted argument is [`true`], the binding inverts the
791 /// value as it passes from the setting to the object, i.e. @property
792 /// will be set to [`true`] if the key is not writable.
793 ///
794 /// Note that the lifecycle of the binding is tied to @object,
795 /// and that you can have only one binding per object property.
796 /// If you bind the same property twice on the same object, the second
797 /// binding overrides the first one.
798 /// ## `key`
799 /// the key to bind
800 /// ## `object`
801 /// a #GObject
802 /// ## `property`
803 /// the name of a boolean property to bind
804 /// ## `inverted`
805 /// whether to 'invert' the value
806 #[doc(alias = "g_settings_bind_writable")]
807 fn bind_writable(
808 &self,
809 key: &str,
810 object: &impl IsA<glib::Object>,
811 property: &str,
812 inverted: bool,
813 ) {
814 unsafe {
815 ffi::g_settings_bind_writable(
816 self.as_ref().to_glib_none().0,
817 key.to_glib_none().0,
818 object.as_ref().to_glib_none().0,
819 property.to_glib_none().0,
820 inverted.into_glib(),
821 );
822 }
823 }
824
825 /// Creates a #GAction corresponding to a given #GSettings key.
826 ///
827 /// The action has the same name as the key.
828 ///
829 /// The value of the key becomes the state of the action and the action
830 /// is enabled when the key is writable. Changing the state of the
831 /// action results in the key being written to. Changes to the value or
832 /// writability of the key cause appropriate change notifications to be
833 /// emitted for the action.
834 ///
835 /// For boolean-valued keys, action activations take no parameter and
836 /// result in the toggling of the value. For all other types,
837 /// activations take the new value for the key (which must have the
838 /// correct type).
839 /// ## `key`
840 /// the name of a key in @self
841 ///
842 /// # Returns
843 ///
844 /// a new #GAction
845 #[doc(alias = "g_settings_create_action")]
846 fn create_action(&self, key: &str) -> Action {
847 unsafe {
848 from_glib_full(ffi::g_settings_create_action(
849 self.as_ref().to_glib_none().0,
850 key.to_glib_none().0,
851 ))
852 }
853 }
854
855 /// Changes the #GSettings object into 'delay-apply' mode. In this
856 /// mode, changes to @self are not immediately propagated to the
857 /// backend, but kept locally until g_settings_apply() is called.
858 #[doc(alias = "g_settings_delay")]
859 fn delay(&self) {
860 unsafe {
861 ffi::g_settings_delay(self.as_ref().to_glib_none().0);
862 }
863 }
864
865 //#[doc(alias = "g_settings_get")]
866 //fn get(&self, key: &str, format: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
867 // unsafe { TODO: call ffi:g_settings_get() }
868 //}
869
870 /// Gets the value that is stored at @key in @self.
871 ///
872 /// A convenience variant of g_settings_get() for booleans.
873 ///
874 /// It is a programmer error to give a @key that isn't specified as
875 /// having a boolean type in the schema for @self.
876 /// ## `key`
877 /// the key to get the value for
878 ///
879 /// # Returns
880 ///
881 /// a boolean
882 #[doc(alias = "g_settings_get_boolean")]
883 #[doc(alias = "get_boolean")]
884 fn boolean(&self, key: &str) -> bool {
885 unsafe {
886 from_glib(ffi::g_settings_get_boolean(
887 self.as_ref().to_glib_none().0,
888 key.to_glib_none().0,
889 ))
890 }
891 }
892
893 /// Creates a child settings object which has a base path of
894 /// `base-path/@name`, where `base-path` is the base path of
895 /// @self.
896 ///
897 /// The schema for the child settings object must have been declared
898 /// in the schema of @self using a `<child>` element.
899 ///
900 /// The created child settings object will inherit the #GSettings:delay-apply
901 /// mode from @self.
902 /// ## `name`
903 /// the name of the child schema
904 ///
905 /// # Returns
906 ///
907 /// a 'child' settings object
908 #[doc(alias = "g_settings_get_child")]
909 #[doc(alias = "get_child")]
910 #[must_use]
911 fn child(&self, name: &str) -> Settings {
912 unsafe {
913 from_glib_full(ffi::g_settings_get_child(
914 self.as_ref().to_glib_none().0,
915 name.to_glib_none().0,
916 ))
917 }
918 }
919
920 /// Gets the "default value" of a key.
921 ///
922 /// This is the value that would be read if g_settings_reset() were to be
923 /// called on the key.
924 ///
925 /// Note that this may be a different value than returned by
926 /// g_settings_schema_key_get_default_value() if the system administrator
927 /// has provided a default value.
928 ///
929 /// Comparing the return values of g_settings_get_default_value() and
930 /// g_settings_get_value() is not sufficient for determining if a value
931 /// has been set because the user may have explicitly set the value to
932 /// something that happens to be equal to the default. The difference
933 /// here is that if the default changes in the future, the user's key
934 /// will still be set.
935 ///
936 /// This function may be useful for adding an indication to a UI of what
937 /// the default value was before the user set it.
938 ///
939 /// It is a programmer error to give a @key that isn't contained in the
940 /// schema for @self.
941 /// ## `key`
942 /// the key to get the default value for
943 ///
944 /// # Returns
945 ///
946 /// the default value
947 #[doc(alias = "g_settings_get_default_value")]
948 #[doc(alias = "get_default_value")]
949 fn default_value(&self, key: &str) -> Option<glib::Variant> {
950 unsafe {
951 from_glib_full(ffi::g_settings_get_default_value(
952 self.as_ref().to_glib_none().0,
953 key.to_glib_none().0,
954 ))
955 }
956 }
957
958 /// Gets the value that is stored at @key in @self.
959 ///
960 /// A convenience variant of g_settings_get() for doubles.
961 ///
962 /// It is a programmer error to give a @key that isn't specified as
963 /// having a 'double' type in the schema for @self.
964 /// ## `key`
965 /// the key to get the value for
966 ///
967 /// # Returns
968 ///
969 /// a double
970 #[doc(alias = "g_settings_get_double")]
971 #[doc(alias = "get_double")]
972 fn double(&self, key: &str) -> f64 {
973 unsafe { ffi::g_settings_get_double(self.as_ref().to_glib_none().0, key.to_glib_none().0) }
974 }
975
976 /// Gets the value that is stored in @self for @key and converts it
977 /// to the enum value that it represents.
978 ///
979 /// In order to use this function the type of the value must be a string
980 /// and it must be marked in the schema file as an enumerated type.
981 ///
982 /// It is a programmer error to give a @key that isn't contained in the
983 /// schema for @self or is not marked as an enumerated type.
984 ///
985 /// If the value stored in the configuration database is not a valid
986 /// value for the enumerated type then this function will return the
987 /// default value.
988 /// ## `key`
989 /// the key to get the value for
990 ///
991 /// # Returns
992 ///
993 /// the enum value
994 #[doc(alias = "g_settings_get_enum")]
995 #[doc(alias = "get_enum")]
996 fn enum_(&self, key: &str) -> i32 {
997 unsafe { ffi::g_settings_get_enum(self.as_ref().to_glib_none().0, key.to_glib_none().0) }
998 }
999
1000 /// Gets the value that is stored in @self for @key and converts it
1001 /// to the flags value that it represents.
1002 ///
1003 /// In order to use this function the type of the value must be an array
1004 /// of strings and it must be marked in the schema file as a flags type.
1005 ///
1006 /// It is a programmer error to give a @key that isn't contained in the
1007 /// schema for @self or is not marked as a flags type.
1008 ///
1009 /// If the value stored in the configuration database is not a valid
1010 /// value for the flags type then this function will return the default
1011 /// value.
1012 /// ## `key`
1013 /// the key to get the value for
1014 ///
1015 /// # Returns
1016 ///
1017 /// the flags value
1018 #[doc(alias = "g_settings_get_flags")]
1019 #[doc(alias = "get_flags")]
1020 fn flags(&self, key: &str) -> u32 {
1021 unsafe { ffi::g_settings_get_flags(self.as_ref().to_glib_none().0, key.to_glib_none().0) }
1022 }
1023
1024 /// Returns whether the #GSettings object has any unapplied
1025 /// changes. This can only be the case if it is in 'delayed-apply' mode.
1026 ///
1027 /// # Returns
1028 ///
1029 /// [`true`] if @self has unapplied changes
1030 #[doc(alias = "g_settings_get_has_unapplied")]
1031 #[doc(alias = "get_has_unapplied")]
1032 #[doc(alias = "has-unapplied")]
1033 fn has_unapplied(&self) -> bool {
1034 unsafe {
1035 from_glib(ffi::g_settings_get_has_unapplied(
1036 self.as_ref().to_glib_none().0,
1037 ))
1038 }
1039 }
1040
1041 /// Gets the value that is stored at @key in @self.
1042 ///
1043 /// A convenience variant of g_settings_get() for 32-bit integers.
1044 ///
1045 /// It is a programmer error to give a @key that isn't specified as
1046 /// having a int32 type in the schema for @self.
1047 /// ## `key`
1048 /// the key to get the value for
1049 ///
1050 /// # Returns
1051 ///
1052 /// an integer
1053 #[doc(alias = "g_settings_get_int")]
1054 #[doc(alias = "get_int")]
1055 fn int(&self, key: &str) -> i32 {
1056 unsafe { ffi::g_settings_get_int(self.as_ref().to_glib_none().0, key.to_glib_none().0) }
1057 }
1058
1059 /// Gets the value that is stored at @key in @self.
1060 ///
1061 /// A convenience variant of g_settings_get() for 64-bit integers.
1062 ///
1063 /// It is a programmer error to give a @key that isn't specified as
1064 /// having a int64 type in the schema for @self.
1065 /// ## `key`
1066 /// the key to get the value for
1067 ///
1068 /// # Returns
1069 ///
1070 /// a 64-bit integer
1071 #[doc(alias = "g_settings_get_int64")]
1072 #[doc(alias = "get_int64")]
1073 fn int64(&self, key: &str) -> i64 {
1074 unsafe { ffi::g_settings_get_int64(self.as_ref().to_glib_none().0, key.to_glib_none().0) }
1075 }
1076
1077 //#[doc(alias = "g_settings_get_mapped")]
1078 //#[doc(alias = "get_mapped")]
1079 //fn mapped(&self, key: &str, mapping: /*Unimplemented*/FnMut(&glib::Variant, /*Unimplemented*/Option<Basic: Pointer>) -> bool, user_data: /*Unimplemented*/Option<Basic: Pointer>) -> /*Unimplemented*/Option<Basic: Pointer> {
1080 // unsafe { TODO: call ffi:g_settings_get_mapped() }
1081 //}
1082
1083 /// Gets the value that is stored at @key in @self.
1084 ///
1085 /// A convenience variant of g_settings_get() for strings.
1086 ///
1087 /// It is a programmer error to give a @key that isn't specified as
1088 /// having a string type in the schema for @self.
1089 /// ## `key`
1090 /// the key to get the value for
1091 ///
1092 /// # Returns
1093 ///
1094 /// a newly-allocated string
1095 #[doc(alias = "g_settings_get_string")]
1096 #[doc(alias = "get_string")]
1097 fn string(&self, key: &str) -> glib::GString {
1098 unsafe {
1099 from_glib_full(ffi::g_settings_get_string(
1100 self.as_ref().to_glib_none().0,
1101 key.to_glib_none().0,
1102 ))
1103 }
1104 }
1105
1106 /// Gets the value that is stored at @key in @self.
1107 ///
1108 /// A convenience variant of g_settings_get() for 32-bit unsigned
1109 /// integers.
1110 ///
1111 /// It is a programmer error to give a @key that isn't specified as
1112 /// having a uint32 type in the schema for @self.
1113 /// ## `key`
1114 /// the key to get the value for
1115 ///
1116 /// # Returns
1117 ///
1118 /// an unsigned integer
1119 #[doc(alias = "g_settings_get_uint")]
1120 #[doc(alias = "get_uint")]
1121 fn uint(&self, key: &str) -> u32 {
1122 unsafe { ffi::g_settings_get_uint(self.as_ref().to_glib_none().0, key.to_glib_none().0) }
1123 }
1124
1125 /// Gets the value that is stored at @key in @self.
1126 ///
1127 /// A convenience variant of g_settings_get() for 64-bit unsigned
1128 /// integers.
1129 ///
1130 /// It is a programmer error to give a @key that isn't specified as
1131 /// having a uint64 type in the schema for @self.
1132 /// ## `key`
1133 /// the key to get the value for
1134 ///
1135 /// # Returns
1136 ///
1137 /// a 64-bit unsigned integer
1138 #[doc(alias = "g_settings_get_uint64")]
1139 #[doc(alias = "get_uint64")]
1140 fn uint64(&self, key: &str) -> u64 {
1141 unsafe { ffi::g_settings_get_uint64(self.as_ref().to_glib_none().0, key.to_glib_none().0) }
1142 }
1143
1144 /// Checks the "user value" of a key, if there is one.
1145 ///
1146 /// The user value of a key is the last value that was set by the user.
1147 ///
1148 /// After calling g_settings_reset() this function should always return
1149 /// [`None`] (assuming something is not wrong with the system
1150 /// configuration).
1151 ///
1152 /// It is possible that g_settings_get_value() will return a different
1153 /// value than this function. This can happen in the case that the user
1154 /// set a value for a key that was subsequently locked down by the system
1155 /// administrator -- this function will return the user's old value.
1156 ///
1157 /// This function may be useful for adding a "reset" option to a UI or
1158 /// for providing indication that a particular value has been changed.
1159 ///
1160 /// It is a programmer error to give a @key that isn't contained in the
1161 /// schema for @self.
1162 /// ## `key`
1163 /// the key to get the user value for
1164 ///
1165 /// # Returns
1166 ///
1167 /// the user's value, if set
1168 #[doc(alias = "g_settings_get_user_value")]
1169 #[doc(alias = "get_user_value")]
1170 fn user_value(&self, key: &str) -> Option<glib::Variant> {
1171 unsafe {
1172 from_glib_full(ffi::g_settings_get_user_value(
1173 self.as_ref().to_glib_none().0,
1174 key.to_glib_none().0,
1175 ))
1176 }
1177 }
1178
1179 /// Gets the value that is stored in @self for @key.
1180 ///
1181 /// It is a programmer error to give a @key that isn't contained in the
1182 /// schema for @self.
1183 /// ## `key`
1184 /// the key to get the value for
1185 ///
1186 /// # Returns
1187 ///
1188 /// a new #GVariant
1189 #[doc(alias = "g_settings_get_value")]
1190 #[doc(alias = "get_value")]
1191 fn value(&self, key: &str) -> glib::Variant {
1192 unsafe {
1193 from_glib_full(ffi::g_settings_get_value(
1194 self.as_ref().to_glib_none().0,
1195 key.to_glib_none().0,
1196 ))
1197 }
1198 }
1199
1200 /// Finds out if a key can be written or not
1201 /// ## `name`
1202 /// the name of a key
1203 ///
1204 /// # Returns
1205 ///
1206 /// [`true`] if the key @name is writable
1207 #[doc(alias = "g_settings_is_writable")]
1208 fn is_writable(&self, name: &str) -> bool {
1209 unsafe {
1210 from_glib(ffi::g_settings_is_writable(
1211 self.as_ref().to_glib_none().0,
1212 name.to_glib_none().0,
1213 ))
1214 }
1215 }
1216
1217 /// Gets the list of children on @self.
1218 ///
1219 /// The list is exactly the list of strings for which it is not an error
1220 /// to call g_settings_get_child().
1221 ///
1222 /// There is little reason to call this function from "normal" code, since
1223 /// you should already know what children are in your schema. This function
1224 /// may still be useful there for introspection reasons, however.
1225 ///
1226 /// You should free the return value with g_strfreev() when you are done
1227 /// with it.
1228 ///
1229 /// # Returns
1230 ///
1231 /// a list of the children
1232 /// on @self, in no defined order
1233 #[doc(alias = "g_settings_list_children")]
1234 fn list_children(&self) -> Vec<glib::GString> {
1235 unsafe {
1236 FromGlibPtrContainer::from_glib_full(ffi::g_settings_list_children(
1237 self.as_ref().to_glib_none().0,
1238 ))
1239 }
1240 }
1241
1242 /// Resets @key to its default value.
1243 ///
1244 /// This call resets the key, as much as possible, to its default value.
1245 /// That might be the value specified in the schema or the one set by the
1246 /// administrator.
1247 /// ## `key`
1248 /// the name of a key
1249 #[doc(alias = "g_settings_reset")]
1250 fn reset(&self, key: &str) {
1251 unsafe {
1252 ffi::g_settings_reset(self.as_ref().to_glib_none().0, key.to_glib_none().0);
1253 }
1254 }
1255
1256 /// Reverts all non-applied changes to the settings. This function
1257 /// does nothing unless @self is in 'delay-apply' mode; see
1258 /// g_settings_delay(). In the normal case settings are always applied
1259 /// immediately.
1260 ///
1261 /// Change notifications will be emitted for affected keys.
1262 #[doc(alias = "g_settings_revert")]
1263 fn revert(&self) {
1264 unsafe {
1265 ffi::g_settings_revert(self.as_ref().to_glib_none().0);
1266 }
1267 }
1268
1269 //#[doc(alias = "g_settings_set")]
1270 //fn set(&self, key: &str, format: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> bool {
1271 // unsafe { TODO: call ffi:g_settings_set() }
1272 //}
1273
1274 /// Sets @key in @self to @value.
1275 ///
1276 /// A convenience variant of g_settings_set() for booleans.
1277 ///
1278 /// It is a programmer error to give a @key that isn't specified as
1279 /// having a boolean type in the schema for @self.
1280 /// ## `key`
1281 /// the name of the key to set
1282 /// ## `value`
1283 /// the value to set it to
1284 ///
1285 /// # Returns
1286 ///
1287 /// [`true`] if setting the key succeeded,
1288 /// [`false`] if the key was not writable
1289 #[doc(alias = "g_settings_set_boolean")]
1290 fn set_boolean(&self, key: &str, value: bool) -> Result<(), glib::error::BoolError> {
1291 unsafe {
1292 glib::result_from_gboolean!(
1293 ffi::g_settings_set_boolean(
1294 self.as_ref().to_glib_none().0,
1295 key.to_glib_none().0,
1296 value.into_glib()
1297 ),
1298 "Can't set readonly key"
1299 )
1300 }
1301 }
1302
1303 /// Sets @key in @self to @value.
1304 ///
1305 /// A convenience variant of g_settings_set() for doubles.
1306 ///
1307 /// It is a programmer error to give a @key that isn't specified as
1308 /// having a 'double' type in the schema for @self.
1309 /// ## `key`
1310 /// the name of the key to set
1311 /// ## `value`
1312 /// the value to set it to
1313 ///
1314 /// # Returns
1315 ///
1316 /// [`true`] if setting the key succeeded,
1317 /// [`false`] if the key was not writable
1318 #[doc(alias = "g_settings_set_double")]
1319 fn set_double(&self, key: &str, value: f64) -> Result<(), glib::error::BoolError> {
1320 unsafe {
1321 glib::result_from_gboolean!(
1322 ffi::g_settings_set_double(
1323 self.as_ref().to_glib_none().0,
1324 key.to_glib_none().0,
1325 value
1326 ),
1327 "Can't set readonly key"
1328 )
1329 }
1330 }
1331
1332 /// Looks up the enumerated type nick for @value and writes it to @key,
1333 /// within @self.
1334 ///
1335 /// It is a programmer error to give a @key that isn't contained in the
1336 /// schema for @self or is not marked as an enumerated type, or for
1337 /// @value not to be a valid value for the named type.
1338 ///
1339 /// After performing the write, accessing @key directly with
1340 /// g_settings_get_string() will return the 'nick' associated with
1341 /// @value.
1342 /// ## `key`
1343 /// a key, within @self
1344 /// ## `value`
1345 /// an enumerated value
1346 ///
1347 /// # Returns
1348 ///
1349 /// [`true`], if the set succeeds
1350 #[doc(alias = "g_settings_set_enum")]
1351 fn set_enum(&self, key: &str, value: i32) -> Result<(), glib::error::BoolError> {
1352 unsafe {
1353 glib::result_from_gboolean!(
1354 ffi::g_settings_set_enum(
1355 self.as_ref().to_glib_none().0,
1356 key.to_glib_none().0,
1357 value
1358 ),
1359 "Can't set readonly key"
1360 )
1361 }
1362 }
1363
1364 /// Looks up the flags type nicks for the bits specified by @value, puts
1365 /// them in an array of strings and writes the array to @key, within
1366 /// @self.
1367 ///
1368 /// It is a programmer error to give a @key that isn't contained in the
1369 /// schema for @self or is not marked as a flags type, or for @value
1370 /// to contain any bits that are not value for the named type.
1371 ///
1372 /// After performing the write, accessing @key directly with
1373 /// g_settings_get_strv() will return an array of 'nicks'; one for each
1374 /// bit in @value.
1375 /// ## `key`
1376 /// a key, within @self
1377 /// ## `value`
1378 /// a flags value
1379 ///
1380 /// # Returns
1381 ///
1382 /// [`true`], if the set succeeds
1383 #[doc(alias = "g_settings_set_flags")]
1384 fn set_flags(&self, key: &str, value: u32) -> Result<(), glib::error::BoolError> {
1385 unsafe {
1386 glib::result_from_gboolean!(
1387 ffi::g_settings_set_flags(
1388 self.as_ref().to_glib_none().0,
1389 key.to_glib_none().0,
1390 value
1391 ),
1392 "Can't set readonly key"
1393 )
1394 }
1395 }
1396
1397 /// Sets @key in @self to @value.
1398 ///
1399 /// A convenience variant of g_settings_set() for 32-bit integers.
1400 ///
1401 /// It is a programmer error to give a @key that isn't specified as
1402 /// having a int32 type in the schema for @self.
1403 /// ## `key`
1404 /// the name of the key to set
1405 /// ## `value`
1406 /// the value to set it to
1407 ///
1408 /// # Returns
1409 ///
1410 /// [`true`] if setting the key succeeded,
1411 /// [`false`] if the key was not writable
1412 #[doc(alias = "g_settings_set_int")]
1413 fn set_int(&self, key: &str, value: i32) -> Result<(), glib::error::BoolError> {
1414 unsafe {
1415 glib::result_from_gboolean!(
1416 ffi::g_settings_set_int(
1417 self.as_ref().to_glib_none().0,
1418 key.to_glib_none().0,
1419 value
1420 ),
1421 "Can't set readonly key"
1422 )
1423 }
1424 }
1425
1426 /// Sets @key in @self to @value.
1427 ///
1428 /// A convenience variant of g_settings_set() for 64-bit integers.
1429 ///
1430 /// It is a programmer error to give a @key that isn't specified as
1431 /// having a int64 type in the schema for @self.
1432 /// ## `key`
1433 /// the name of the key to set
1434 /// ## `value`
1435 /// the value to set it to
1436 ///
1437 /// # Returns
1438 ///
1439 /// [`true`] if setting the key succeeded,
1440 /// [`false`] if the key was not writable
1441 #[doc(alias = "g_settings_set_int64")]
1442 fn set_int64(&self, key: &str, value: i64) -> Result<(), glib::error::BoolError> {
1443 unsafe {
1444 glib::result_from_gboolean!(
1445 ffi::g_settings_set_int64(
1446 self.as_ref().to_glib_none().0,
1447 key.to_glib_none().0,
1448 value
1449 ),
1450 "Can't set readonly key"
1451 )
1452 }
1453 }
1454
1455 /// Sets @key in @self to @value.
1456 ///
1457 /// A convenience variant of g_settings_set() for strings.
1458 ///
1459 /// It is a programmer error to give a @key that isn't specified as
1460 /// having a string type in the schema for @self.
1461 /// ## `key`
1462 /// the name of the key to set
1463 /// ## `value`
1464 /// the value to set it to
1465 ///
1466 /// # Returns
1467 ///
1468 /// [`true`] if setting the key succeeded,
1469 /// [`false`] if the key was not writable
1470 #[doc(alias = "g_settings_set_string")]
1471 fn set_string(&self, key: &str, value: &str) -> Result<(), glib::error::BoolError> {
1472 unsafe {
1473 glib::result_from_gboolean!(
1474 ffi::g_settings_set_string(
1475 self.as_ref().to_glib_none().0,
1476 key.to_glib_none().0,
1477 value.to_glib_none().0
1478 ),
1479 "Can't set readonly key"
1480 )
1481 }
1482 }
1483
1484 /// Sets @key in @self to @value.
1485 ///
1486 /// A convenience variant of g_settings_set() for 32-bit unsigned
1487 /// integers.
1488 ///
1489 /// It is a programmer error to give a @key that isn't specified as
1490 /// having a uint32 type in the schema for @self.
1491 /// ## `key`
1492 /// the name of the key to set
1493 /// ## `value`
1494 /// the value to set it to
1495 ///
1496 /// # Returns
1497 ///
1498 /// [`true`] if setting the key succeeded,
1499 /// [`false`] if the key was not writable
1500 #[doc(alias = "g_settings_set_uint")]
1501 fn set_uint(&self, key: &str, value: u32) -> Result<(), glib::error::BoolError> {
1502 unsafe {
1503 glib::result_from_gboolean!(
1504 ffi::g_settings_set_uint(
1505 self.as_ref().to_glib_none().0,
1506 key.to_glib_none().0,
1507 value
1508 ),
1509 "Can't set readonly key"
1510 )
1511 }
1512 }
1513
1514 /// Sets @key in @self to @value.
1515 ///
1516 /// A convenience variant of g_settings_set() for 64-bit unsigned
1517 /// integers.
1518 ///
1519 /// It is a programmer error to give a @key that isn't specified as
1520 /// having a uint64 type in the schema for @self.
1521 /// ## `key`
1522 /// the name of the key to set
1523 /// ## `value`
1524 /// the value to set it to
1525 ///
1526 /// # Returns
1527 ///
1528 /// [`true`] if setting the key succeeded,
1529 /// [`false`] if the key was not writable
1530 #[doc(alias = "g_settings_set_uint64")]
1531 fn set_uint64(&self, key: &str, value: u64) -> Result<(), glib::error::BoolError> {
1532 unsafe {
1533 glib::result_from_gboolean!(
1534 ffi::g_settings_set_uint64(
1535 self.as_ref().to_glib_none().0,
1536 key.to_glib_none().0,
1537 value
1538 ),
1539 "Can't set readonly key"
1540 )
1541 }
1542 }
1543
1544 /// Sets @key in @self to @value.
1545 ///
1546 /// It is a programmer error to give a @key that isn't contained in the
1547 /// schema for @self or for @value to have the incorrect type, per
1548 /// the schema.
1549 ///
1550 /// If @value is floating then this function consumes the reference.
1551 /// ## `key`
1552 /// the name of the key to set
1553 /// ## `value`
1554 /// a #GVariant of the correct type
1555 ///
1556 /// # Returns
1557 ///
1558 /// [`true`] if setting the key succeeded,
1559 /// [`false`] if the key was not writable
1560 #[doc(alias = "g_settings_set_value")]
1561 fn set_value(&self, key: &str, value: &glib::Variant) -> Result<(), glib::error::BoolError> {
1562 unsafe {
1563 glib::result_from_gboolean!(
1564 ffi::g_settings_set_value(
1565 self.as_ref().to_glib_none().0,
1566 key.to_glib_none().0,
1567 value.to_glib_none().0
1568 ),
1569 "Can't set readonly key"
1570 )
1571 }
1572 }
1573
1574 /// The name of the context that the settings are stored in.
1575 fn backend(&self) -> Option<SettingsBackend> {
1576 ObjectExt::property(self.as_ref(), "backend")
1577 }
1578
1579 /// Whether the #GSettings object is in 'delay-apply' mode. See
1580 /// g_settings_delay() for details.
1581 #[doc(alias = "delay-apply")]
1582 fn is_delay_apply(&self) -> bool {
1583 ObjectExt::property(self.as_ref(), "delay-apply")
1584 }
1585
1586 /// The path within the backend where the settings are stored.
1587 fn path(&self) -> Option<glib::GString> {
1588 ObjectExt::property(self.as_ref(), "path")
1589 }
1590
1591 /// The name of the schema that describes the types of keys
1592 /// for this #GSettings object.
1593 #[doc(alias = "schema-id")]
1594 fn schema_id(&self) -> Option<glib::GString> {
1595 ObjectExt::property(self.as_ref(), "schema-id")
1596 }
1597
1598 /// The #GSettingsSchema describing the types of keys for this
1599 /// #GSettings object.
1600 ///
1601 /// Ideally, this property would be called 'schema'. #GSettingsSchema
1602 /// has only existed since version 2.32, however, and before then the
1603 /// 'schema' property was used to refer to the ID of the schema rather
1604 /// than the schema itself. Take care.
1605 #[doc(alias = "settings-schema")]
1606 fn settings_schema(&self) -> Option<SettingsSchema> {
1607 ObjectExt::property(self.as_ref(), "settings-schema")
1608 }
1609
1610 //#[doc(alias = "change-event")]
1611 //fn connect_change_event<Unsupported or ignored types>(&self, f: F) -> SignalHandlerId {
1612 // Unimplemented keys: *.CArray TypeId { ns_id: 2, id: 5 }
1613 //}
1614
1615 /// The "changed" signal is emitted when a key has potentially changed.
1616 /// You should call one of the g_settings_get() calls to check the new
1617 /// value.
1618 ///
1619 /// This signal supports detailed connections. You can connect to the
1620 /// detailed signal "changed::x" in order to only receive callbacks
1621 /// when key "x" changes.
1622 ///
1623 /// Note that @settings only emits this signal if you have read @key at
1624 /// least once while a signal handler was already connected for @key.
1625 /// ## `key`
1626 /// the name of the key that changed
1627 #[doc(alias = "changed")]
1628 fn connect_changed<F: Fn(&Self, &str) + 'static>(
1629 &self,
1630 detail: Option<&str>,
1631 f: F,
1632 ) -> SignalHandlerId {
1633 unsafe extern "C" fn changed_trampoline<P: IsA<Settings>, F: Fn(&P, &str) + 'static>(
1634 this: *mut ffi::GSettings,
1635 key: *mut std::ffi::c_char,
1636 f: glib::ffi::gpointer,
1637 ) {
1638 let f: &F = &*(f as *const F);
1639 f(
1640 Settings::from_glib_borrow(this).unsafe_cast_ref(),
1641 &glib::GString::from_glib_borrow(key),
1642 )
1643 }
1644 unsafe {
1645 let f: Box_<F> = Box_::new(f);
1646 let detailed_signal_name = detail.map(|name| format!("changed::{name}\0"));
1647 let signal_name: &[u8] = detailed_signal_name
1648 .as_ref()
1649 .map_or(&b"changed\0"[..], |n| n.as_bytes());
1650 connect_raw(
1651 self.as_ptr() as *mut _,
1652 signal_name.as_ptr() as *const _,
1653 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1654 changed_trampoline::<Self, F> as *const (),
1655 )),
1656 Box_::into_raw(f),
1657 )
1658 }
1659 }
1660
1661 /// The "writable-change-event" signal is emitted once per writability
1662 /// change event that affects this settings object. You should connect
1663 /// to this signal if you are interested in viewing groups of changes
1664 /// before they are split out into multiple emissions of the
1665 /// "writable-changed" signal. For most use cases it is more
1666 /// appropriate to use the "writable-changed" signal.
1667 ///
1668 /// In the event that the writability change applies only to a single
1669 /// key, @key will be set to the #GQuark for that key. In the event
1670 /// that the writability change affects the entire settings object,
1671 /// @key will be 0.
1672 ///
1673 /// The default handler for this signal invokes the "writable-changed"
1674 /// and "changed" signals for each affected key. This is done because
1675 /// changes in writability might also imply changes in value (if for
1676 /// example, a new mandatory setting is introduced). If any other
1677 /// connected handler returns [`true`] then this default functionality
1678 /// will be suppressed.
1679 /// ## `key`
1680 /// the quark of the key, or 0
1681 ///
1682 /// # Returns
1683 ///
1684 /// [`true`] to stop other handlers from being invoked for the
1685 /// event. FALSE to propagate the event further.
1686 #[doc(alias = "writable-change-event")]
1687 fn connect_writable_change_event<F: Fn(&Self, u32) -> glib::Propagation + 'static>(
1688 &self,
1689 f: F,
1690 ) -> SignalHandlerId {
1691 unsafe extern "C" fn writable_change_event_trampoline<
1692 P: IsA<Settings>,
1693 F: Fn(&P, u32) -> glib::Propagation + 'static,
1694 >(
1695 this: *mut ffi::GSettings,
1696 key: std::ffi::c_uint,
1697 f: glib::ffi::gpointer,
1698 ) -> glib::ffi::gboolean {
1699 let f: &F = &*(f as *const F);
1700 f(Settings::from_glib_borrow(this).unsafe_cast_ref(), key).into_glib()
1701 }
1702 unsafe {
1703 let f: Box_<F> = Box_::new(f);
1704 connect_raw(
1705 self.as_ptr() as *mut _,
1706 b"writable-change-event\0".as_ptr() as *const _,
1707 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1708 writable_change_event_trampoline::<Self, F> as *const (),
1709 )),
1710 Box_::into_raw(f),
1711 )
1712 }
1713 }
1714
1715 /// The "writable-changed" signal is emitted when the writability of a
1716 /// key has potentially changed. You should call
1717 /// g_settings_is_writable() in order to determine the new status.
1718 ///
1719 /// This signal supports detailed connections. You can connect to the
1720 /// detailed signal "writable-changed::x" in order to only receive
1721 /// callbacks when the writability of "x" changes.
1722 /// ## `key`
1723 /// the key
1724 #[doc(alias = "writable-changed")]
1725 fn connect_writable_changed<F: Fn(&Self, &str) + 'static>(
1726 &self,
1727 detail: Option<&str>,
1728 f: F,
1729 ) -> SignalHandlerId {
1730 unsafe extern "C" fn writable_changed_trampoline<
1731 P: IsA<Settings>,
1732 F: Fn(&P, &str) + 'static,
1733 >(
1734 this: *mut ffi::GSettings,
1735 key: *mut std::ffi::c_char,
1736 f: glib::ffi::gpointer,
1737 ) {
1738 let f: &F = &*(f as *const F);
1739 f(
1740 Settings::from_glib_borrow(this).unsafe_cast_ref(),
1741 &glib::GString::from_glib_borrow(key),
1742 )
1743 }
1744 unsafe {
1745 let f: Box_<F> = Box_::new(f);
1746 let detailed_signal_name = detail.map(|name| format!("writable-changed::{name}\0"));
1747 let signal_name: &[u8] = detailed_signal_name
1748 .as_ref()
1749 .map_or(&b"writable-changed\0"[..], |n| n.as_bytes());
1750 connect_raw(
1751 self.as_ptr() as *mut _,
1752 signal_name.as_ptr() as *const _,
1753 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1754 writable_changed_trampoline::<Self, F> as *const (),
1755 )),
1756 Box_::into_raw(f),
1757 )
1758 }
1759 }
1760
1761 #[doc(alias = "delay-apply")]
1762 fn connect_delay_apply_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1763 unsafe extern "C" fn notify_delay_apply_trampoline<
1764 P: IsA<Settings>,
1765 F: Fn(&P) + 'static,
1766 >(
1767 this: *mut ffi::GSettings,
1768 _param_spec: glib::ffi::gpointer,
1769 f: glib::ffi::gpointer,
1770 ) {
1771 let f: &F = &*(f as *const F);
1772 f(Settings::from_glib_borrow(this).unsafe_cast_ref())
1773 }
1774 unsafe {
1775 let f: Box_<F> = Box_::new(f);
1776 connect_raw(
1777 self.as_ptr() as *mut _,
1778 b"notify::delay-apply\0".as_ptr() as *const _,
1779 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1780 notify_delay_apply_trampoline::<Self, F> as *const (),
1781 )),
1782 Box_::into_raw(f),
1783 )
1784 }
1785 }
1786
1787 #[doc(alias = "has-unapplied")]
1788 fn connect_has_unapplied_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1789 unsafe extern "C" fn notify_has_unapplied_trampoline<
1790 P: IsA<Settings>,
1791 F: Fn(&P) + 'static,
1792 >(
1793 this: *mut ffi::GSettings,
1794 _param_spec: glib::ffi::gpointer,
1795 f: glib::ffi::gpointer,
1796 ) {
1797 let f: &F = &*(f as *const F);
1798 f(Settings::from_glib_borrow(this).unsafe_cast_ref())
1799 }
1800 unsafe {
1801 let f: Box_<F> = Box_::new(f);
1802 connect_raw(
1803 self.as_ptr() as *mut _,
1804 b"notify::has-unapplied\0".as_ptr() as *const _,
1805 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1806 notify_has_unapplied_trampoline::<Self, F> as *const (),
1807 )),
1808 Box_::into_raw(f),
1809 )
1810 }
1811 }
1812}
1813
1814impl<O: IsA<Settings>> SettingsExt for O {}