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 {}