// 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::SettingsSchemaKey;
use glib::translate::*;

glib::wrapper! {
    /// The [`SettingsSchemaSource`][crate::SettingsSchemaSource] and [`SettingsSchema`][crate::SettingsSchema] 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
    /// [`list_keys()`][Self::list_keys()].
    /// ## `name`
    /// the name of a key
    ///
    /// # Returns
    ///
    /// the [`SettingsSchemaKey`][crate::SettingsSchemaKey] 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,
            ))
        }
    }
}