gio/auto/
icon.rs

Help
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
94/// Trait containing all [`struct@Icon`] methods.
95///
96/// # Implementors
97///
98/// [`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]
99pub trait IconExt: IsA<Icon> + 'static {
100    #[doc(alias = "g_icon_equal")]
101    fn equal(&self, icon2: Option<&impl IsA<Icon>>) -> bool {
102        unsafe {
103            from_glib(ffi::g_icon_equal(
104                self.as_ref().to_glib_none().0,
105                icon2.map(|p| p.as_ref()).to_glib_none().0,
106            ))
107        }
108    }
109
110    #[doc(alias = "g_icon_hash")]
111    fn hash(&self) -> u32 {
112        unsafe {
113            ffi::g_icon_hash(
114                ToGlibPtr::<*mut ffi::GIcon>::to_glib_none(self.as_ref()).0
115                    as glib::ffi::gconstpointer,
116            )
117        }
118    }
119
120    /// Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved
121    /// back by calling g_icon_deserialize() on the returned value.
122    /// As serialization will avoid using raw icon data when possible, it only
123    /// makes sense to transfer the #GVariant between processes on the same machine,
124    /// (as opposed to over the network), and within the same file system namespace.
125    ///
126    /// # Returns
127    ///
128    /// a #GVariant, or [`None`] when serialization fails. The #GVariant will not be floating.
129    #[doc(alias = "g_icon_serialize")]
130    fn serialize(&self) -> Option<glib::Variant> {
131        unsafe { from_glib_full(ffi::g_icon_serialize(self.as_ref().to_glib_none().0)) }
132    }
133
134    /// Generates a textual representation of @self that can be used for
135    /// serialization such as when passing @self to a different process or
136    /// saving it to persistent storage. Use g_icon_new_for_string() to
137    /// get @self back from the returned string.
138    ///
139    /// The encoding of the returned string is proprietary to #GIcon except
140    /// in the following two cases
141    ///
142    /// - If @self is a #GFileIcon, the returned string is a native path
143    ///   (such as `/path/to/my icon.png`) without escaping
144    ///   if the #GFile for @self is a native file.  If the file is not
145    ///   native, the returned string is the result of g_file_get_uri()
146    ///   (such as `sftp://path/to/my`20icon``).
147    ///
148    /// - If @self is a #GThemedIcon with exactly one name and no fallbacks,
149    ///   the encoding is simply the name (such as `network-server`).
150    ///
151    /// # Returns
152    ///
153    /// An allocated NUL-terminated UTF8 string or
154    /// [`None`] if @self can't be serialized. Use g_free() to free.
155    #[doc(alias = "g_icon_to_string")]
156    fn to_string(&self) -> Option<glib::GString> {
157        unsafe { from_glib_full(ffi::g_icon_to_string(self.as_ref().to_glib_none().0)) }
158    }
159}
160
161impl<O: IsA<Icon>> IconExt for O {}
gio/auto/icon.rs

gio/auto/
icon.rs
