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}