gstreamer/auto/

preset.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// from gst-gir-files (https://gitlab.freedesktop.org/gstreamer/gir-files-rs.git)
// DO NOT EDIT

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

glib::wrapper! {
    /// This interface offers methods to query and manipulate parameter preset sets.
    /// A preset is a bunch of property settings, together with meta data and a name.
    /// The name of a preset serves as key for subsequent method calls to manipulate
    /// single presets.
    /// All instances of one type will share the list of presets. The list is created
    /// on demand, if presets are not used, the list is not created.
    ///
    /// The interface comes with a default implementation that serves most plugins.
    /// Wrapper plugins will override most methods to implement support for the
    /// native preset format of those wrapped plugins.
    /// One method that is useful to be overridden is [`PresetExt::property_names()`][crate::prelude::PresetExt::property_names()].
    /// With that one can control which properties are saved and in which order.
    /// When implementing support for read-only presets, one should set the vmethods
    /// for [`PresetExt::save_preset()`][crate::prelude::PresetExt::save_preset()] and [`PresetExt::delete_preset()`][crate::prelude::PresetExt::delete_preset()] to [`None`].
    /// Applications can use [`PresetExt::is_editable()`][crate::prelude::PresetExt::is_editable()] to check for that.
    ///
    /// The default implementation supports presets located in a system directory,
    /// application specific directory and in the users home directory. When getting
    /// a list of presets individual presets are read and overlaid in 1) system,
    /// 2) application and 3) user order. Whenever an earlier entry is newer, the
    /// later entries will be updated. Since 1.8 you can also provide extra paths
    /// where to find presets through the GST_PRESET_PATH environment variable.
    /// Presets found in those paths will be considered as "app presets".
    ///
    /// # Implements
    ///
    /// [`PresetExt`][trait@crate::prelude::PresetExt]
    #[doc(alias = "GstPreset")]
    pub struct Preset(Interface<ffi::GstPreset, ffi::GstPresetInterface>);

    match fn {
        type_ => || ffi::gst_preset_get_type(),
    }
}

impl Preset {
    pub const NONE: Option<&'static Preset> = None;

    /// Gets the directory for application specific presets if set by the
    /// application.
    ///
    /// # Returns
    ///
    /// the directory or [`None`], don't free or modify
    /// the string
    #[doc(alias = "gst_preset_get_app_dir")]
    #[doc(alias = "get_app_dir")]
    pub fn app_dir() -> Option<std::path::PathBuf> {
        assert_initialized_main_thread!();
        unsafe { from_glib_none(ffi::gst_preset_get_app_dir()) }
    }

    /// Sets an extra directory as an absolute path that should be considered when
    /// looking for presets. Any presets in the application dir will shadow the
    /// system presets.
    /// ## `app_dir`
    /// the application specific preset dir
    ///
    /// # Returns
    ///
    /// [`true`] for success, [`false`] if the dir already has been set
    #[doc(alias = "gst_preset_set_app_dir")]
    pub fn set_app_dir(app_dir: impl AsRef<std::path::Path>) -> Result<(), glib::error::BoolError> {
        assert_initialized_main_thread!();
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_preset_set_app_dir(app_dir.as_ref().to_glib_none().0),
                "Failed to set app preset directory"
            )
        }
    }
}

unsafe impl Send for Preset {}
unsafe impl Sync for Preset {}

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::Preset>> Sealed for T {}
}

/// Trait containing all [`struct@Preset`] methods.
///
/// # Implementors
///
/// [`Preset`][struct@crate::Preset]
pub trait PresetExt: IsA<Preset> + sealed::Sealed + 'static {
    /// Delete the given preset.
    /// ## `name`
    /// preset name to remove
    ///
    /// # Returns
    ///
    /// [`true`] for success, [`false`] if e.g. there is no preset with that `name`
    #[doc(alias = "gst_preset_delete_preset")]
    fn delete_preset(&self, name: &str) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_preset_delete_preset(
                    self.as_ref().to_glib_none().0,
                    name.to_glib_none().0
                ),
                "Failed to delete preset"
            )
        }
    }

    /// Gets the `value` for an existing meta data `tag`. Meta data `tag` names can be
    /// something like e.g. "comment". Returned values need to be released when done.
    /// ## `name`
    /// preset name
    /// ## `tag`
    /// meta data item name
    ///
    /// # Returns
    ///
    /// [`true`] for success, [`false`] if e.g. there is no preset with that `name`
    /// or no value for the given `tag`
    ///
    /// ## `value`
    /// value
    #[doc(alias = "gst_preset_get_meta")]
    #[doc(alias = "get_meta")]
    fn meta(&self, name: &str, tag: &str) -> Option<glib::GString> {
        unsafe {
            let mut value = std::ptr::null_mut();
            let ret = from_glib(ffi::gst_preset_get_meta(
                self.as_ref().to_glib_none().0,
                name.to_glib_none().0,
                tag.to_glib_none().0,
                &mut value,
            ));
            if ret {
                Some(from_glib_full(value))
            } else {
                None
            }
        }
    }

    /// Get a copy of preset names as a [`None`] terminated string array.
    ///
    /// # Returns
    ///
    ///
    ///  list with names, use `g_strfreev()` after usage.
    #[doc(alias = "gst_preset_get_preset_names")]
    #[doc(alias = "get_preset_names")]
    fn preset_names(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::gst_preset_get_preset_names(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Get a the names of the GObject properties that can be used for presets.
    ///
    /// # Returns
    ///
    /// an
    ///  array of property names which should be freed with `g_strfreev()` after use.
    #[doc(alias = "gst_preset_get_property_names")]
    #[doc(alias = "get_property_names")]
    fn property_names(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::gst_preset_get_property_names(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Check if one can add new presets, change existing ones and remove presets.
    ///
    /// # Returns
    ///
    /// [`true`] if presets are editable or [`false`] if they are static
    #[doc(alias = "gst_preset_is_editable")]
    fn is_editable(&self) -> bool {
        unsafe { from_glib(ffi::gst_preset_is_editable(self.as_ref().to_glib_none().0)) }
    }

    /// Load the given preset.
    /// ## `name`
    /// preset name to load
    ///
    /// # Returns
    ///
    /// [`true`] for success, [`false`] if e.g. there is no preset with that `name`
    #[doc(alias = "gst_preset_load_preset")]
    fn load_preset(&self, name: &str) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_preset_load_preset(self.as_ref().to_glib_none().0, name.to_glib_none().0),
                "Failed to load preset"
            )
        }
    }

    /// Renames a preset. If there is already a preset by the `new_name` it will be
    /// overwritten.
    /// ## `old_name`
    /// current preset name
    /// ## `new_name`
    /// new preset name
    ///
    /// # Returns
    ///
    /// [`true`] for success, [`false`] if e.g. there is no preset with `old_name`
    #[doc(alias = "gst_preset_rename_preset")]
    fn rename_preset(&self, old_name: &str, new_name: &str) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_preset_rename_preset(
                    self.as_ref().to_glib_none().0,
                    old_name.to_glib_none().0,
                    new_name.to_glib_none().0
                ),
                "Failed to rename preset"
            )
        }
    }

    /// Save the current object settings as a preset under the given name. If there
    /// is already a preset by this `name` it will be overwritten.
    /// ## `name`
    /// preset name to save
    ///
    /// # Returns
    ///
    /// [`true`] for success, [`false`]
    #[doc(alias = "gst_preset_save_preset")]
    fn save_preset(&self, name: &str) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_preset_save_preset(self.as_ref().to_glib_none().0, name.to_glib_none().0),
                "Failed to save preset"
            )
        }
    }

    /// Sets a new `value` for an existing meta data item or adds a new item. Meta
    /// data `tag` names can be something like e.g. "comment". Supplying [`None`] for the
    /// `value` will unset an existing value.
    /// ## `name`
    /// preset name
    /// ## `tag`
    /// meta data item name
    /// ## `value`
    /// new value
    ///
    /// # Returns
    ///
    /// [`true`] for success, [`false`] if e.g. there is no preset with that `name`
    #[doc(alias = "gst_preset_set_meta")]
    fn set_meta(
        &self,
        name: &str,
        tag: &str,
        value: Option<&str>,
    ) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_preset_set_meta(
                    self.as_ref().to_glib_none().0,
                    name.to_glib_none().0,
                    tag.to_glib_none().0,
                    value.to_glib_none().0
                ),
                "Failed to set preset meta"
            )
        }
    }
}

impl<O: IsA<Preset>> PresetExt for O {}