gio/auto/

settings_schema.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{ffi, SettingsSchemaKey};
use glib::translate::*;

glib::wrapper! {
    /// The [`SettingsSchemaSource`][crate::SettingsSchemaSource] and `GSettingsSchema` APIs provide a
    /// mechanism for advanced control over the loading of schemas and a
    /// mechanism for introspecting their content.
    ///
    /// Plugin loading systems that wish to provide plugins a way to access
    /// settings face the problem of how to make the schemas for these
    /// settings visible to GSettings.  Typically, a plugin will want to ship
    /// the schema along with itself and it won't be installed into the
    /// standard system directories for schemas.
    ///
    /// [`SettingsSchemaSource`][crate::SettingsSchemaSource] provides a mechanism for dealing with this
    /// by allowing the creation of a new ‘schema source’ from which schemas can
    /// be acquired.  This schema source can then become part of the metadata
    /// associated with the plugin and queried whenever the plugin requires
    /// access to some settings.
    ///
    /// Consider the following example:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// typedef struct
    /// {
    ///    …
    ///    GSettingsSchemaSource *schema_source;
    ///    …
    /// } Plugin;
    ///
    /// Plugin *
    /// initialise_plugin (const gchar *dir)
    /// {
    ///   Plugin *plugin;
    ///
    ///   …
    ///
    ///   plugin->schema_source =
    ///     g_settings_schema_source_new_from_directory (dir,
    ///       g_settings_schema_source_get_default (), FALSE, NULL);
    ///
    ///   …
    ///
    ///   return plugin;
    /// }
    ///
    /// …
    ///
    /// GSettings *
    /// plugin_get_settings (Plugin      *plugin,
    ///                      const gchar *schema_id)
    /// {
    ///   GSettingsSchema *schema;
    ///
    ///   if (schema_id == NULL)
    ///     schema_id = plugin->identifier;
    ///
    ///   schema = g_settings_schema_source_lookup (plugin->schema_source,
    ///                                             schema_id, FALSE);
    ///
    ///   if (schema == NULL)
    ///     {
    ///       … disable the plugin or abort, etc …
    ///     }
    ///
    ///   return g_settings_new_full (schema, NULL, NULL);
    /// }
    /// ```
    ///
    /// The code above shows how hooks should be added to the code that
    /// initialises (or enables) the plugin to create the schema source and
    /// how an API can be added to the plugin system to provide a convenient
    /// way for the plugin to access its settings, using the schemas that it
    /// ships.
    ///
    /// From the standpoint of the plugin, it would need to ensure that it
    /// ships a gschemas.compiled file as part of itself, and then simply do
    /// the following:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// {
    ///   GSettings *settings;
    ///   gint some_value;
    ///
    ///   settings = plugin_get_settings (self, NULL);
    ///   some_value = g_settings_get_int (settings, "some-value");
    ///   …
    /// }
    /// ```
    ///
    /// It's also possible that the plugin system expects the schema source
    /// files (ie: `.gschema.xml` files) instead of a `gschemas.compiled` file.
    /// In that case, the plugin loading system must compile the schemas for
    /// itself before attempting to create the settings source.
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct SettingsSchema(Shared<ffi::GSettingsSchema>);

    match fn {
        ref => |ptr| ffi::g_settings_schema_ref(ptr),
        unref => |ptr| ffi::g_settings_schema_unref(ptr),
        type_ => || ffi::g_settings_schema_get_type(),
    }
}

impl SettingsSchema {
    /// Get the ID of @self.
    ///
    /// # Returns
    ///
    /// the ID
    #[doc(alias = "g_settings_schema_get_id")]
    #[doc(alias = "get_id")]
    pub fn id(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::g_settings_schema_get_id(self.to_glib_none().0)) }
    }

    /// Gets the key named @name from @self.
    ///
    /// It is a programmer error to request a key that does not exist.  See
    /// g_settings_schema_list_keys().
    /// ## `name`
    /// the name of a key
    ///
    /// # Returns
    ///
    /// the #GSettingsSchemaKey for @name
    #[doc(alias = "g_settings_schema_get_key")]
    #[doc(alias = "get_key")]
    pub fn key(&self, name: &str) -> SettingsSchemaKey {
        unsafe {
            from_glib_full(ffi::g_settings_schema_get_key(
                self.to_glib_none().0,
                name.to_glib_none().0,
            ))
        }
    }

    /// Gets the path associated with @self, or [`None`].
    ///
    /// Schemas may be single-instance or relocatable.  Single-instance
    /// schemas correspond to exactly one set of keys in the backend
    /// database: those located at the path returned by this function.
    ///
    /// Relocatable schemas can be referenced by other schemas and can
    /// therefore describe multiple sets of keys at different locations.  For
    /// relocatable schemas, this function will return [`None`].
    ///
    /// # Returns
    ///
    /// the path of the schema, or [`None`]
    #[doc(alias = "g_settings_schema_get_path")]
    #[doc(alias = "get_path")]
    pub fn path(&self) -> Option<glib::GString> {
        unsafe { from_glib_none(ffi::g_settings_schema_get_path(self.to_glib_none().0)) }
    }

    /// Checks if @self has a key named @name.
    /// ## `name`
    /// the name of a key
    ///
    /// # Returns
    ///
    /// [`true`] if such a key exists
    #[doc(alias = "g_settings_schema_has_key")]
    pub fn has_key(&self, name: &str) -> bool {
        unsafe {
            from_glib(ffi::g_settings_schema_has_key(
                self.to_glib_none().0,
                name.to_glib_none().0,
            ))
        }
    }

    /// Gets the list of children in @self.
    ///
    /// You should free the return value with g_strfreev() when you are done
    /// with it.
    ///
    /// # Returns
    ///
    /// a list of
    ///    the children on @settings, in no defined order
    #[doc(alias = "g_settings_schema_list_children")]
    pub fn list_children(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::g_settings_schema_list_children(
                self.to_glib_none().0,
            ))
        }
    }

    /// Introspects the list of keys on @self.
    ///
    /// You should probably not be calling this function from "normal" code
    /// (since you should already know what keys are in your schema).  This
    /// function is intended for introspection reasons.
    ///
    /// # Returns
    ///
    /// a list
    ///   of the keys on @self, in no defined order
    #[doc(alias = "g_settings_schema_list_keys")]
    pub fn list_keys(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::g_settings_schema_list_keys(
                self.to_glib_none().0,
            ))
        }
    }
}