gio/auto/

icon.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;
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// `GIcon` is a very minimal interface for icons. It provides functions
    /// for checking the equality of two icons, hashing of icons and
    /// serializing an icon to and from strings.
    ///
    /// `GIcon` does not provide the actual pixmap for the icon as this is out
    /// of GIO's scope, however implementations of `GIcon` may contain the name
    /// of an icon (see [`ThemedIcon`][crate::ThemedIcon]), or the path to an icon
    /// (see [`LoadableIcon`][crate::LoadableIcon]).
    ///
    /// To obtain a hash of a `GIcon`, see `Gio::Icon::hash()`.
    ///
    /// To check if two `GIcon`s are equal, see `Gio::Icon::equal()`.
    ///
    /// For serializing a `GIcon`, use [`IconExt::serialize()`][crate::prelude::IconExt::serialize()] and
    /// [`deserialize()`][Self::deserialize()].
    ///
    /// If you want to consume `GIcon` (for example, in a toolkit) you must
    /// be prepared to handle at least the three following cases:
    /// [`LoadableIcon`][crate::LoadableIcon], [`ThemedIcon`][crate::ThemedIcon] and [`EmblemedIcon`][crate::EmblemedIcon].
    /// It may also make sense to have fast-paths for other cases (like handling
    /// [`GdkPixbuf`](https://docs.gtk.org/gdk-pixbuf/class.Pixbuf.html) directly,
    /// for example) but all compliant `GIcon` implementations outside of GIO must
    /// implement [`LoadableIcon`][crate::LoadableIcon].
    ///
    /// If your application or library provides one or more `GIcon`
    /// implementations you need to ensure that your new implementation also
    /// implements [`LoadableIcon`][crate::LoadableIcon].  Additionally, you must provide an
    /// implementation of [`IconExt::serialize()`][crate::prelude::IconExt::serialize()] that gives a result that is
    /// understood by [`deserialize()`][Self::deserialize()], yielding one of the built-in
    /// icon types.
    ///
    /// # Implements
    ///
    /// [`IconExt`][trait@crate::prelude::IconExt]
    #[doc(alias = "GIcon")]
    pub struct Icon(Interface<ffi::GIcon, ffi::GIconIface>);

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

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

    /// Deserializes a #GIcon previously serialized using g_icon_serialize().
    /// ## `value`
    /// a #GVariant created with g_icon_serialize()
    ///
    /// # Returns
    ///
    /// a #GIcon, or [`None`] when deserialization fails.
    #[doc(alias = "g_icon_deserialize")]
    pub fn deserialize(value: &glib::Variant) -> Option<Icon> {
        unsafe { from_glib_full(ffi::g_icon_deserialize(value.to_glib_none().0)) }
    }

    /// Generate a #GIcon instance from @str. This function can fail if
    /// @str is not valid - see g_icon_to_string() for discussion.
    ///
    /// If your application or library provides one or more #GIcon
    /// implementations you need to ensure that each #GType is registered
    /// with the type system prior to calling g_icon_new_for_string().
    /// ## `str`
    /// A string obtained via g_icon_to_string().
    ///
    /// # Returns
    ///
    /// An object implementing the #GIcon
    ///          interface or [`None`] if @error is set.
    #[doc(alias = "g_icon_new_for_string")]
    #[doc(alias = "new_for_string")]
    pub fn for_string(str: &str) -> Result<Icon, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_icon_new_for_string(str.to_glib_none().0, &mut error);
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }
}

/// Trait containing all [`struct@Icon`] methods.
///
/// # Implementors
///
/// [`BytesIcon`][struct@crate::BytesIcon], [`Emblem`][struct@crate::Emblem], [`EmblemedIcon`][struct@crate::EmblemedIcon], [`FileIcon`][struct@crate::FileIcon], [`Icon`][struct@crate::Icon], [`LoadableIcon`][struct@crate::LoadableIcon], [`ThemedIcon`][struct@crate::ThemedIcon]
pub trait IconExt: IsA<Icon> + 'static {
    #[doc(alias = "g_icon_equal")]
    fn equal(&self, icon2: Option<&impl IsA<Icon>>) -> bool {
        unsafe {
            from_glib(ffi::g_icon_equal(
                self.as_ref().to_glib_none().0,
                icon2.map(|p| p.as_ref()).to_glib_none().0,
            ))
        }
    }

    #[doc(alias = "g_icon_hash")]
    fn hash(&self) -> u32 {
        unsafe {
            ffi::g_icon_hash(
                ToGlibPtr::<*mut ffi::GIcon>::to_glib_none(self.as_ref()).0
                    as glib::ffi::gconstpointer,
            )
        }
    }

    /// Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved
    /// back by calling g_icon_deserialize() on the returned value.
    /// As serialization will avoid using raw icon data when possible, it only
    /// makes sense to transfer the #GVariant between processes on the same machine,
    /// (as opposed to over the network), and within the same file system namespace.
    ///
    /// # Returns
    ///
    /// a #GVariant, or [`None`] when serialization fails. The #GVariant will not be floating.
    #[doc(alias = "g_icon_serialize")]
    fn serialize(&self) -> Option<glib::Variant> {
        unsafe { from_glib_full(ffi::g_icon_serialize(self.as_ref().to_glib_none().0)) }
    }

    /// Generates a textual representation of @self that can be used for
    /// serialization such as when passing @self to a different process or
    /// saving it to persistent storage. Use g_icon_new_for_string() to
    /// get @self back from the returned string.
    ///
    /// The encoding of the returned string is proprietary to #GIcon except
    /// in the following two cases
    ///
    /// - If @self is a #GFileIcon, the returned string is a native path
    ///   (such as `/path/to/my icon.png`) without escaping
    ///   if the #GFile for @self is a native file.  If the file is not
    ///   native, the returned string is the result of g_file_get_uri()
    ///   (such as `sftp://path/to/my`20icon``).
    ///
    /// - If @self is a #GThemedIcon with exactly one name and no fallbacks,
    ///   the encoding is simply the name (such as `network-server`).
    ///
    /// # Returns
    ///
    /// An allocated NUL-terminated UTF8 string or
    /// [`None`] if @self can't be serialized. Use g_free() to free.
    #[doc(alias = "g_icon_to_string")]
    fn to_string(&self) -> Option<glib::GString> {
        unsafe { from_glib_full(ffi::g_icon_to_string(self.as_ref().to_glib_none().0)) }
    }
}

impl<O: IsA<Icon>> IconExt for O {}