gdk4/auto/
content_formats.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::translate::*;
7
8glib::wrapper! {
9    /// The [`ContentFormats`][crate::ContentFormats] structure is used to advertise and negotiate the
10    /// format of content.
11    ///
12    /// You will encounter [`ContentFormats`][crate::ContentFormats] when interacting with objects
13    /// controlling operations that pass data between different widgets, window
14    /// or application, like [`Drag`][crate::Drag], [`Drop`][crate::Drop],
15    /// [`Clipboard`][crate::Clipboard] or [`ContentProvider`][crate::ContentProvider].
16    ///
17    /// GDK supports content in 2 forms: `GType` and mime type.
18    /// Using `GTypes` is meant only for in-process content transfers. Mime types
19    /// are meant to be used for data passing both in-process and out-of-process.
20    /// The details of how data is passed is described in the documentation of
21    /// the actual implementations. To transform between the two forms,
22    /// [`ContentSerializer`][crate::ContentSerializer] and [`ContentDeserializer`][crate::ContentDeserializer] are used.
23    ///
24    /// A [`ContentFormats`][crate::ContentFormats] describes a set of possible formats content can be
25    /// exchanged in. It is assumed that this set is ordered. `GTypes` are more
26    /// important than mime types. Order between different `GTypes` or mime types
27    /// is the order they were added in, most important first. Functions that
28    /// care about order, such as [`union()`][Self::union()], will describe
29    /// in their documentation how they interpret that order, though in general the
30    /// order of the first argument is considered the primary order of the result,
31    /// followed by the order of further arguments.
32    ///
33    /// For debugging purposes, the function [`to_str()`][Self::to_str()]
34    /// exists. It will print a comma-separated list of formats from most important
35    /// to least important.
36    ///
37    /// [`ContentFormats`][crate::ContentFormats] is an immutable struct. After creation, you cannot change
38    /// the types it represents. Instead, new [`ContentFormats`][crate::ContentFormats] have to be created.
39    /// The [`ContentFormatsBuilder`][crate::ContentFormatsBuilder] structure is meant to help in this
40    /// endeavor.
41    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
42    pub struct ContentFormats(Shared<ffi::GdkContentFormats>);
43
44    match fn {
45        ref => |ptr| ffi::gdk_content_formats_ref(ptr),
46        unref => |ptr| ffi::gdk_content_formats_unref(ptr),
47        type_ => || ffi::gdk_content_formats_get_type(),
48    }
49}
50
51impl ContentFormats {
52    /// Creates a new [`ContentFormats`][crate::ContentFormats] from an array of mime types.
53    ///
54    /// The mime types must be valid and different from each other or the
55    /// behavior of the return value is undefined. If you cannot guarantee
56    /// this, use [`ContentFormatsBuilder`][crate::ContentFormatsBuilder] instead.
57    /// ## `mime_types`
58    /// Pointer to an
59    ///   array of mime types
60    ///
61    /// # Returns
62    ///
63    /// the new [`ContentFormats`][crate::ContentFormats].
64    #[doc(alias = "gdk_content_formats_new")]
65    pub fn new(mime_types: &[&str]) -> ContentFormats {
66        assert_initialized_main_thread!();
67        let n_mime_types = mime_types.len() as _;
68        unsafe {
69            from_glib_full(ffi::gdk_content_formats_new(
70                mime_types.to_glib_none().0,
71                n_mime_types,
72            ))
73        }
74    }
75
76    /// Creates a new [`ContentFormats`][crate::ContentFormats] for a given `GType`.
77    /// ## `type_`
78    /// a `GType`
79    ///
80    /// # Returns
81    ///
82    /// a new [`ContentFormats`][crate::ContentFormats]
83    #[doc(alias = "gdk_content_formats_new_for_gtype")]
84    #[doc(alias = "new_for_gtype")]
85    pub fn for_type(type_: glib::types::Type) -> ContentFormats {
86        assert_initialized_main_thread!();
87        unsafe { from_glib_full(ffi::gdk_content_formats_new_for_gtype(type_.into_glib())) }
88    }
89
90    /// Checks if a given `GType` is part of the given @self.
91    /// ## `type_`
92    /// the `GType` to search for
93    ///
94    /// # Returns
95    ///
96    /// [`true`] if the `GType` was found
97    #[doc(alias = "gdk_content_formats_contain_gtype")]
98    #[doc(alias = "contain_gtype")]
99    pub fn contains_type(&self, type_: glib::types::Type) -> bool {
100        unsafe {
101            from_glib(ffi::gdk_content_formats_contain_gtype(
102                self.to_glib_none().0,
103                type_.into_glib(),
104            ))
105        }
106    }
107
108    /// Checks if a given mime type is part of the given @self.
109    /// ## `mime_type`
110    /// the mime type to search for
111    ///
112    /// # Returns
113    ///
114    /// [`true`] if the mime_type was found
115    #[doc(alias = "gdk_content_formats_contain_mime_type")]
116    pub fn contain_mime_type(&self, mime_type: &str) -> bool {
117        unsafe {
118            from_glib(ffi::gdk_content_formats_contain_mime_type(
119                self.to_glib_none().0,
120                mime_type.to_glib_none().0,
121            ))
122        }
123    }
124
125    /// Gets the mime types included in @self.
126    ///
127    /// Note that @self may not contain any mime types, in particular
128    /// when they are empty. In that case [`None`] will be returned.
129    ///
130    /// # Returns
131    ///
132    ///
133    ///   [`None`]-terminated array of interned strings of mime types included
134    ///   in @self
135    #[doc(alias = "gdk_content_formats_get_mime_types")]
136    #[doc(alias = "get_mime_types")]
137    pub fn mime_types(&self) -> Vec<glib::GString> {
138        unsafe {
139            let mut n_mime_types = std::mem::MaybeUninit::uninit();
140            let ret = FromGlibContainer::from_glib_none_num(
141                ffi::gdk_content_formats_get_mime_types(
142                    self.to_glib_none().0,
143                    n_mime_types.as_mut_ptr(),
144                ),
145                n_mime_types.assume_init() as _,
146            );
147            ret
148        }
149    }
150
151    /// Returns whether the content formats contain any formats.
152    ///
153    /// # Returns
154    ///
155    /// true if @self contains no mime types and no GTypes
156    #[cfg(feature = "v4_18")]
157    #[cfg_attr(docsrs, doc(cfg(feature = "v4_18")))]
158    #[doc(alias = "gdk_content_formats_is_empty")]
159    pub fn is_empty(&self) -> bool {
160        unsafe { from_glib(ffi::gdk_content_formats_is_empty(self.to_glib_none().0)) }
161    }
162
163    /// Checks if @self and @second have any matching formats.
164    /// ## `second`
165    /// the [`ContentFormats`][crate::ContentFormats] to intersect with
166    ///
167    /// # Returns
168    ///
169    /// [`true`] if a matching format was found.
170    #[doc(alias = "gdk_content_formats_match")]
171    #[doc(alias = "match")]
172    pub fn match_(&self, second: &ContentFormats) -> bool {
173        unsafe {
174            from_glib(ffi::gdk_content_formats_match(
175                self.to_glib_none().0,
176                second.to_glib_none().0,
177            ))
178        }
179    }
180
181    /// Finds the first `GType` from @self that is also contained
182    /// in @second.
183    ///
184    /// If no matching `GType` is found, `G_TYPE_INVALID` is returned.
185    /// ## `second`
186    /// the [`ContentFormats`][crate::ContentFormats] to intersect with
187    ///
188    /// # Returns
189    ///
190    /// The first common `GType` or `G_TYPE_INVALID` if none.
191    #[doc(alias = "gdk_content_formats_match_gtype")]
192    #[doc(alias = "match_gtype")]
193    pub fn match_type(&self, second: &ContentFormats) -> glib::types::Type {
194        unsafe {
195            from_glib(ffi::gdk_content_formats_match_gtype(
196                self.to_glib_none().0,
197                second.to_glib_none().0,
198            ))
199        }
200    }
201
202    /// Finds the first mime type from @self that is also contained
203    /// in @second.
204    ///
205    /// If no matching mime type is found, [`None`] is returned.
206    /// ## `second`
207    /// the [`ContentFormats`][crate::ContentFormats] to intersect with
208    ///
209    /// # Returns
210    ///
211    /// The first common mime type or [`None`] if none
212    #[doc(alias = "gdk_content_formats_match_mime_type")]
213    pub fn match_mime_type(&self, second: &ContentFormats) -> Option<glib::GString> {
214        unsafe {
215            from_glib_none(ffi::gdk_content_formats_match_mime_type(
216                self.to_glib_none().0,
217                second.to_glib_none().0,
218            ))
219        }
220    }
221
222    /// Prints the given @self into a human-readable string.
223    ///
224    /// The resulting string can be parsed with [`parse()`][Self::parse()].
225    ///
226    /// This is a small wrapper around `Gdk::ContentFormats::print()`
227    /// to help when debugging.
228    ///
229    /// # Returns
230    ///
231    /// a new string
232    #[doc(alias = "gdk_content_formats_to_string")]
233    #[doc(alias = "to_string")]
234    pub fn to_str(&self) -> glib::GString {
235        unsafe { from_glib_full(ffi::gdk_content_formats_to_string(self.to_glib_none().0)) }
236    }
237
238    /// Append all missing types from @second to @self, in the order
239    /// they had in @second.
240    /// ## `second`
241    /// the [`ContentFormats`][crate::ContentFormats] to merge from
242    ///
243    /// # Returns
244    ///
245    /// a new [`ContentFormats`][crate::ContentFormats]
246    #[doc(alias = "gdk_content_formats_union")]
247    #[must_use]
248    pub fn union(self, second: &ContentFormats) -> ContentFormats {
249        unsafe {
250            from_glib_full(ffi::gdk_content_formats_union(
251                self.into_glib_ptr(),
252                second.to_glib_none().0,
253            ))
254        }
255    }
256
257    /// Add GTypes for mime types in @self for which deserializers are
258    /// registered.
259    ///
260    /// # Returns
261    ///
262    /// a new [`ContentFormats`][crate::ContentFormats]
263    #[doc(alias = "gdk_content_formats_union_deserialize_gtypes")]
264    #[doc(alias = "union_deserialize_gtypes")]
265    #[must_use]
266    pub fn union_deserialize_types(self) -> ContentFormats {
267        unsafe {
268            from_glib_full(ffi::gdk_content_formats_union_deserialize_gtypes(
269                self.into_glib_ptr(),
270            ))
271        }
272    }
273
274    /// Add mime types for GTypes in @self for which deserializers are
275    /// registered.
276    ///
277    /// # Returns
278    ///
279    /// a new [`ContentFormats`][crate::ContentFormats]
280    #[doc(alias = "gdk_content_formats_union_deserialize_mime_types")]
281    #[must_use]
282    pub fn union_deserialize_mime_types(self) -> ContentFormats {
283        unsafe {
284            from_glib_full(ffi::gdk_content_formats_union_deserialize_mime_types(
285                self.into_glib_ptr(),
286            ))
287        }
288    }
289
290    /// Add GTypes for the mime types in @self for which serializers are
291    /// registered.
292    ///
293    /// # Returns
294    ///
295    /// a new [`ContentFormats`][crate::ContentFormats]
296    #[doc(alias = "gdk_content_formats_union_serialize_gtypes")]
297    #[doc(alias = "union_serialize_gtypes")]
298    #[must_use]
299    pub fn union_serialize_types(self) -> ContentFormats {
300        unsafe {
301            from_glib_full(ffi::gdk_content_formats_union_serialize_gtypes(
302                self.into_glib_ptr(),
303            ))
304        }
305    }
306
307    /// Add mime types for GTypes in @self for which serializers are
308    /// registered.
309    ///
310    /// # Returns
311    ///
312    /// a new [`ContentFormats`][crate::ContentFormats]
313    #[doc(alias = "gdk_content_formats_union_serialize_mime_types")]
314    #[must_use]
315    pub fn union_serialize_mime_types(self) -> ContentFormats {
316        unsafe {
317            from_glib_full(ffi::gdk_content_formats_union_serialize_mime_types(
318                self.into_glib_ptr(),
319            ))
320        }
321    }
322
323    /// Parses the given @string into [`ContentFormats`][crate::ContentFormats] and
324    /// returns the formats.
325    ///
326    /// Strings printed via [`to_str()`][Self::to_str()]
327    /// can be read in again successfully using this function.
328    ///
329    /// If @string does not describe valid content formats, [`None`]
330    /// is returned.
331    /// ## `string`
332    /// the string to parse
333    ///
334    /// # Returns
335    ///
336    /// the content formats if @string is valid
337    #[cfg(feature = "v4_4")]
338    #[cfg_attr(docsrs, doc(cfg(feature = "v4_4")))]
339    #[doc(alias = "gdk_content_formats_parse")]
340    pub fn parse(string: &str) -> Result<ContentFormats, glib::BoolError> {
341        assert_initialized_main_thread!();
342        unsafe {
343            Option::<_>::from_glib_full(ffi::gdk_content_formats_parse(string.to_glib_none().0))
344                .ok_or_else(|| glib::bool_error!("Can't parse ContentFormats"))
345        }
346    }
347}
348
349impl std::fmt::Display for ContentFormats {
350    #[inline]
351    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
352        f.write_str(&self.to_str())
353    }
354}