gdk4/auto/

content_formats.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::ffi;
use glib::translate::*;

glib::wrapper! {
    /// The [`ContentFormats`][crate::ContentFormats] structure is used to advertise and negotiate the
    /// format of content.
    ///
    /// You will encounter [`ContentFormats`][crate::ContentFormats] when interacting with objects
    /// controlling operations that pass data between different widgets, window
    /// or application, like [`Drag`][crate::Drag], [`Drop`][crate::Drop],
    /// [`Clipboard`][crate::Clipboard] or [`ContentProvider`][crate::ContentProvider].
    ///
    /// GDK supports content in 2 forms: `GType` and mime type.
    /// Using `GTypes` is meant only for in-process content transfers. Mime types
    /// are meant to be used for data passing both in-process and out-of-process.
    /// The details of how data is passed is described in the documentation of
    /// the actual implementations. To transform between the two forms,
    /// [`ContentSerializer`][crate::ContentSerializer] and [`ContentDeserializer`][crate::ContentDeserializer] are used.
    ///
    /// A [`ContentFormats`][crate::ContentFormats] describes a set of possible formats content can be
    /// exchanged in. It is assumed that this set is ordered. `GTypes` are more
    /// important than mime types. Order between different `GTypes` or mime types
    /// is the order they were added in, most important first. Functions that
    /// care about order, such as [`union()`][Self::union()], will describe
    /// in their documentation how they interpret that order, though in general the
    /// order of the first argument is considered the primary order of the result,
    /// followed by the order of further arguments.
    ///
    /// For debugging purposes, the function [`to_str()`][Self::to_str()]
    /// exists. It will print a comma-separated list of formats from most important
    /// to least important.
    ///
    /// [`ContentFormats`][crate::ContentFormats] is an immutable struct. After creation, you cannot change
    /// the types it represents. Instead, new [`ContentFormats`][crate::ContentFormats] have to be created.
    /// The [`ContentFormatsBuilder`][crate::ContentFormatsBuilder] structure is meant to help in this
    /// endeavor.
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct ContentFormats(Shared<ffi::GdkContentFormats>);

    match fn {
        ref => |ptr| ffi::gdk_content_formats_ref(ptr),
        unref => |ptr| ffi::gdk_content_formats_unref(ptr),
        type_ => || ffi::gdk_content_formats_get_type(),
    }
}

impl ContentFormats {
    /// Creates a new [`ContentFormats`][crate::ContentFormats] from an array of mime types.
    ///
    /// The mime types must be valid and different from each other or the
    /// behavior of the return value is undefined. If you cannot guarantee
    /// this, use [`ContentFormatsBuilder`][crate::ContentFormatsBuilder] instead.
    /// ## `mime_types`
    /// Pointer to an
    ///   array of mime types
    ///
    /// # Returns
    ///
    /// the new [`ContentFormats`][crate::ContentFormats].
    #[doc(alias = "gdk_content_formats_new")]
    pub fn new(mime_types: &[&str]) -> ContentFormats {
        assert_initialized_main_thread!();
        let n_mime_types = mime_types.len() as _;
        unsafe {
            from_glib_full(ffi::gdk_content_formats_new(
                mime_types.to_glib_none().0,
                n_mime_types,
            ))
        }
    }

    /// Creates a new [`ContentFormats`][crate::ContentFormats] for a given `GType`.
    /// ## `type_`
    /// a `GType`
    ///
    /// # Returns
    ///
    /// a new [`ContentFormats`][crate::ContentFormats]
    #[doc(alias = "gdk_content_formats_new_for_gtype")]
    #[doc(alias = "new_for_gtype")]
    pub fn for_type(type_: glib::types::Type) -> ContentFormats {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gdk_content_formats_new_for_gtype(type_.into_glib())) }
    }

    /// Checks if a given `GType` is part of the given @self.
    /// ## `type_`
    /// the `GType` to search for
    ///
    /// # Returns
    ///
    /// [`true`] if the `GType` was found
    #[doc(alias = "gdk_content_formats_contain_gtype")]
    #[doc(alias = "contain_gtype")]
    pub fn contains_type(&self, type_: glib::types::Type) -> bool {
        unsafe {
            from_glib(ffi::gdk_content_formats_contain_gtype(
                self.to_glib_none().0,
                type_.into_glib(),
            ))
        }
    }

    /// Checks if a given mime type is part of the given @self.
    /// ## `mime_type`
    /// the mime type to search for
    ///
    /// # Returns
    ///
    /// [`true`] if the mime_type was found
    #[doc(alias = "gdk_content_formats_contain_mime_type")]
    pub fn contain_mime_type(&self, mime_type: &str) -> bool {
        unsafe {
            from_glib(ffi::gdk_content_formats_contain_mime_type(
                self.to_glib_none().0,
                mime_type.to_glib_none().0,
            ))
        }
    }

    /// Gets the mime types included in @self.
    ///
    /// Note that @self may not contain any mime types, in particular
    /// when they are empty. In that case [`None`] will be returned.
    ///
    /// # Returns
    ///
    ///
    ///   [`None`]-terminated array of interned strings of mime types included
    ///   in @self
    #[doc(alias = "gdk_content_formats_get_mime_types")]
    #[doc(alias = "get_mime_types")]
    pub fn mime_types(&self) -> Vec<glib::GString> {
        unsafe {
            let mut n_mime_types = std::mem::MaybeUninit::uninit();
            let ret = FromGlibContainer::from_glib_none_num(
                ffi::gdk_content_formats_get_mime_types(
                    self.to_glib_none().0,
                    n_mime_types.as_mut_ptr(),
                ),
                n_mime_types.assume_init() as _,
            );
            ret
        }
    }

    /// Returns whether the content formats contain any formats.
    ///
    /// # Returns
    ///
    /// true if @self contains no mime types and no GTypes
    #[cfg(feature = "v4_18")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_18")))]
    #[doc(alias = "gdk_content_formats_is_empty")]
    pub fn is_empty(&self) -> bool {
        unsafe { from_glib(ffi::gdk_content_formats_is_empty(self.to_glib_none().0)) }
    }

    /// Checks if @self and @second have any matching formats.
    /// ## `second`
    /// the [`ContentFormats`][crate::ContentFormats] to intersect with
    ///
    /// # Returns
    ///
    /// [`true`] if a matching format was found.
    #[doc(alias = "gdk_content_formats_match")]
    #[doc(alias = "match")]
    pub fn match_(&self, second: &ContentFormats) -> bool {
        unsafe {
            from_glib(ffi::gdk_content_formats_match(
                self.to_glib_none().0,
                second.to_glib_none().0,
            ))
        }
    }

    /// Finds the first `GType` from @self that is also contained
    /// in @second.
    ///
    /// If no matching `GType` is found, `G_TYPE_INVALID` is returned.
    /// ## `second`
    /// the [`ContentFormats`][crate::ContentFormats] to intersect with
    ///
    /// # Returns
    ///
    /// The first common `GType` or `G_TYPE_INVALID` if none.
    #[doc(alias = "gdk_content_formats_match_gtype")]
    #[doc(alias = "match_gtype")]
    pub fn match_type(&self, second: &ContentFormats) -> glib::types::Type {
        unsafe {
            from_glib(ffi::gdk_content_formats_match_gtype(
                self.to_glib_none().0,
                second.to_glib_none().0,
            ))
        }
    }

    /// Finds the first mime type from @self that is also contained
    /// in @second.
    ///
    /// If no matching mime type is found, [`None`] is returned.
    /// ## `second`
    /// the [`ContentFormats`][crate::ContentFormats] to intersect with
    ///
    /// # Returns
    ///
    /// The first common mime type or [`None`] if none
    #[doc(alias = "gdk_content_formats_match_mime_type")]
    pub fn match_mime_type(&self, second: &ContentFormats) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::gdk_content_formats_match_mime_type(
                self.to_glib_none().0,
                second.to_glib_none().0,
            ))
        }
    }

    /// Prints the given @self into a human-readable string.
    ///
    /// The resulting string can be parsed with [`parse()`][Self::parse()].
    ///
    /// This is a small wrapper around `Gdk::ContentFormats::print()`
    /// to help when debugging.
    ///
    /// # Returns
    ///
    /// a new string
    #[doc(alias = "gdk_content_formats_to_string")]
    #[doc(alias = "to_string")]
    pub fn to_str(&self) -> glib::GString {
        unsafe { from_glib_full(ffi::gdk_content_formats_to_string(self.to_glib_none().0)) }
    }

    /// Append all missing types from @second to @self, in the order
    /// they had in @second.
    /// ## `second`
    /// the [`ContentFormats`][crate::ContentFormats] to merge from
    ///
    /// # Returns
    ///
    /// a new [`ContentFormats`][crate::ContentFormats]
    #[doc(alias = "gdk_content_formats_union")]
    #[must_use]
    pub fn union(self, second: &ContentFormats) -> ContentFormats {
        unsafe {
            from_glib_full(ffi::gdk_content_formats_union(
                self.into_glib_ptr(),
                second.to_glib_none().0,
            ))
        }
    }

    /// Add GTypes for mime types in @self for which deserializers are
    /// registered.
    ///
    /// # Returns
    ///
    /// a new [`ContentFormats`][crate::ContentFormats]
    #[doc(alias = "gdk_content_formats_union_deserialize_gtypes")]
    #[doc(alias = "union_deserialize_gtypes")]
    #[must_use]
    pub fn union_deserialize_types(self) -> ContentFormats {
        unsafe {
            from_glib_full(ffi::gdk_content_formats_union_deserialize_gtypes(
                self.into_glib_ptr(),
            ))
        }
    }

    /// Add mime types for GTypes in @self for which deserializers are
    /// registered.
    ///
    /// # Returns
    ///
    /// a new [`ContentFormats`][crate::ContentFormats]
    #[doc(alias = "gdk_content_formats_union_deserialize_mime_types")]
    #[must_use]
    pub fn union_deserialize_mime_types(self) -> ContentFormats {
        unsafe {
            from_glib_full(ffi::gdk_content_formats_union_deserialize_mime_types(
                self.into_glib_ptr(),
            ))
        }
    }

    /// Add GTypes for the mime types in @self for which serializers are
    /// registered.
    ///
    /// # Returns
    ///
    /// a new [`ContentFormats`][crate::ContentFormats]
    #[doc(alias = "gdk_content_formats_union_serialize_gtypes")]
    #[doc(alias = "union_serialize_gtypes")]
    #[must_use]
    pub fn union_serialize_types(self) -> ContentFormats {
        unsafe {
            from_glib_full(ffi::gdk_content_formats_union_serialize_gtypes(
                self.into_glib_ptr(),
            ))
        }
    }

    /// Add mime types for GTypes in @self for which serializers are
    /// registered.
    ///
    /// # Returns
    ///
    /// a new [`ContentFormats`][crate::ContentFormats]
    #[doc(alias = "gdk_content_formats_union_serialize_mime_types")]
    #[must_use]
    pub fn union_serialize_mime_types(self) -> ContentFormats {
        unsafe {
            from_glib_full(ffi::gdk_content_formats_union_serialize_mime_types(
                self.into_glib_ptr(),
            ))
        }
    }

    /// Parses the given @string into [`ContentFormats`][crate::ContentFormats] and
    /// returns the formats.
    ///
    /// Strings printed via [`to_str()`][Self::to_str()]
    /// can be read in again successfully using this function.
    ///
    /// If @string does not describe valid content formats, [`None`]
    /// is returned.
    /// ## `string`
    /// the string to parse
    ///
    /// # Returns
    ///
    /// the content formats if @string is valid
    #[cfg(feature = "v4_4")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_4")))]
    #[doc(alias = "gdk_content_formats_parse")]
    pub fn parse(string: &str) -> Result<ContentFormats, glib::BoolError> {
        assert_initialized_main_thread!();
        unsafe {
            Option::<_>::from_glib_full(ffi::gdk_content_formats_parse(string.to_glib_none().0))
                .ok_or_else(|| glib::bool_error!("Can't parse ContentFormats"))
        }
    }
}

impl std::fmt::Display for ContentFormats {
    #[inline]
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        f.write_str(&self.to_str())
    }
}