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}