gio/auto/
icon.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
5use crate::ffi;
6use glib::{prelude::*, translate::*};
7
8glib::wrapper! {
9    /// `GIcon` is a very minimal interface for icons. It provides functions
10    /// for checking the equality of two icons, hashing of icons and
11    /// serializing an icon to and from strings.
12    ///
13    /// `GIcon` does not provide the actual pixmap for the icon as this is out
14    /// of GIO's scope, however implementations of `GIcon` may contain the name
15    /// of an icon (see [`ThemedIcon`][crate::ThemedIcon]), or the path to an icon
16    /// (see [`LoadableIcon`][crate::LoadableIcon]).
17    ///
18    /// To obtain a hash of a `GIcon`, see `Gio::Icon::hash()`.
19    ///
20    /// To check if two `GIcon`s are equal, see `Gio::Icon::equal()`.
21    ///
22    /// For serializing a `GIcon`, use [`IconExt::serialize()`][crate::prelude::IconExt::serialize()] and
23    /// [`deserialize()`][Self::deserialize()].
24    ///
25    /// If you want to consume `GIcon` (for example, in a toolkit) you must
26    /// be prepared to handle at least the three following cases:
27    /// [`LoadableIcon`][crate::LoadableIcon], [`ThemedIcon`][crate::ThemedIcon] and [`EmblemedIcon`][crate::EmblemedIcon].
28    /// It may also make sense to have fast-paths for other cases (like handling
29    /// [`GdkPixbuf`](https://docs.gtk.org/gdk-pixbuf/class.Pixbuf.html) directly,
30    /// for example) but all compliant `GIcon` implementations outside of GIO must
31    /// implement [`LoadableIcon`][crate::LoadableIcon].
32    ///
33    /// If your application or library provides one or more `GIcon`
34    /// implementations you need to ensure that your new implementation also
35    /// implements [`LoadableIcon`][crate::LoadableIcon].  Additionally, you must provide an
36    /// implementation of [`IconExt::serialize()`][crate::prelude::IconExt::serialize()] that gives a result that is
37    /// understood by [`deserialize()`][Self::deserialize()], yielding one of the built-in
38    /// icon types.
39    ///
40    /// # Implements
41    ///
42    /// [`IconExt`][trait@crate::prelude::IconExt]
43    #[doc(alias = "GIcon")]
44    pub struct Icon(Interface<ffi::GIcon, ffi::GIconIface>);
45
46    match fn {
47        type_ => || ffi::g_icon_get_type(),
48    }
49}
50
51impl Icon {
52    pub const NONE: Option<&'static Icon> = None;
53
54    /// Deserializes a #GIcon previously serialized using g_icon_serialize().
55    /// ## `value`
56    /// a #GVariant created with g_icon_serialize()
57    ///
58    /// # Returns
59    ///
60    /// a #GIcon, or [`None`] when deserialization fails.
61    #[doc(alias = "g_icon_deserialize")]
62    pub fn deserialize(value: &glib::Variant) -> Option<Icon> {
63        unsafe { from_glib_full(ffi::g_icon_deserialize(value.to_glib_none().0)) }
64    }
65
66    /// Generate a #GIcon instance from @str. This function can fail if
67    /// @str is not valid - see g_icon_to_string() for discussion.
68    ///
69    /// If your application or library provides one or more #GIcon
70    /// implementations you need to ensure that each #GType is registered
71    /// with the type system prior to calling g_icon_new_for_string().
72    /// ## `str`
73    /// A string obtained via g_icon_to_string().
74    ///
75    /// # Returns
76    ///
77    /// An object implementing the #GIcon
78    ///          interface or [`None`] if @error is set.
79    #[doc(alias = "g_icon_new_for_string")]
80    #[doc(alias = "new_for_string")]
81    pub fn for_string(str: &str) -> Result<Icon, glib::Error> {
82        unsafe {
83            let mut error = std::ptr::null_mut();
84            let ret = ffi::g_icon_new_for_string(str.to_glib_none().0, &mut error);
85            if error.is_null() {
86                Ok(from_glib_full(ret))
87            } else {
88                Err(from_glib_full(error))
89            }
90        }
91    }
92}
93
94mod sealed {
95    pub trait Sealed {}
96    impl<T: super::IsA<super::Icon>> Sealed for T {}
97}
98
99/// Trait containing all [`struct@Icon`] methods.
100///
101/// # Implementors
102///
103/// [`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]
104pub trait IconExt: IsA<Icon> + sealed::Sealed + 'static {
105    #[doc(alias = "g_icon_equal")]
106    fn equal(&self, icon2: Option<&impl IsA<Icon>>) -> bool {
107        unsafe {
108            from_glib(ffi::g_icon_equal(
109                self.as_ref().to_glib_none().0,
110                icon2.map(|p| p.as_ref()).to_glib_none().0,
111            ))
112        }
113    }
114
115    #[doc(alias = "g_icon_hash")]
116    fn hash(&self) -> u32 {
117        unsafe {
118            ffi::g_icon_hash(
119                ToGlibPtr::<*mut ffi::GIcon>::to_glib_none(self.as_ref()).0
120                    as glib::ffi::gconstpointer,
121            )
122        }
123    }
124
125    /// Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved
126    /// back by calling g_icon_deserialize() on the returned value.
127    /// As serialization will avoid using raw icon data when possible, it only
128    /// makes sense to transfer the #GVariant between processes on the same machine,
129    /// (as opposed to over the network), and within the same file system namespace.
130    ///
131    /// # Returns
132    ///
133    /// a #GVariant, or [`None`] when serialization fails. The #GVariant will not be floating.
134    #[doc(alias = "g_icon_serialize")]
135    fn serialize(&self) -> Option<glib::Variant> {
136        unsafe { from_glib_full(ffi::g_icon_serialize(self.as_ref().to_glib_none().0)) }
137    }
138
139    /// Generates a textual representation of @self that can be used for
140    /// serialization such as when passing @self to a different process or
141    /// saving it to persistent storage. Use g_icon_new_for_string() to
142    /// get @self back from the returned string.
143    ///
144    /// The encoding of the returned string is proprietary to #GIcon except
145    /// in the following two cases
146    ///
147    /// - If @self is a #GFileIcon, the returned string is a native path
148    ///   (such as `/path/to/my icon.png`) without escaping
149    ///   if the #GFile for @self is a native file.  If the file is not
150    ///   native, the returned string is the result of g_file_get_uri()
151    ///   (such as `sftp://path/to/my`20icon``).
152    ///
153    /// - If @self is a #GThemedIcon with exactly one name and no fallbacks,
154    ///   the encoding is simply the name (such as `network-server`).
155    ///
156    /// # Returns
157    ///
158    /// An allocated NUL-terminated UTF8 string or
159    /// [`None`] if @self can't be serialized. Use g_free() to free.
160    #[doc(alias = "g_icon_to_string")]
161    fn to_string(&self) -> Option<glib::GString> {
162        unsafe { from_glib_full(ffi::g_icon_to_string(self.as_ref().to_glib_none().0)) }
163    }
164}
165
166impl<O: IsA<Icon>> IconExt for O {}