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