:right-sidebar: True ContentFormats =================================================================== .. currentmodule:: gi.repository.Gdk .. class:: ContentFormats(**kwargs) :no-contents-entry: The ``GdkContentFormats`` structure is used to advertise and negotiate the format of content. You will encounter ``GdkContentFormats`` when interacting with objects controlling operations that pass data between different widgets, window or application, like :obj:`~gi.repository.Gdk.Drag`\, :obj:`~gi.repository.Gdk.Drop`\, :obj:`~gi.repository.Gdk.Clipboard` or :obj:`~gi.repository.Gdk.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, :obj:`~gi.repository.Gdk.ContentSerializer` and :obj:`~gi.repository.Gdk.ContentDeserializer` are used. A ``GdkContentFormats`` 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 :obj:`~gi.repository.Gdk.ContentFormats.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 :obj:`~gi.repository.Gdk.ContentFormats.to_string` exists. It will print a comma-separated list of formats from most important to least important. ``GdkContentFormats`` is an immutable struct. After creation, you cannot change the types it represents. Instead, new ``GdkContentFormats`` have to be created. The :obj:`~gi.repository.Gdk.ContentFormatsBuilder` structure is meant to help in this endeavor. Constructors ------------ .. rst-class:: interim-class .. class:: ContentFormats :no-index: .. classmethod:: new(mime_types: list[str] | None = None) -> ~gi.repository.Gdk.ContentFormats Creates a new ``GdkContentFormats`` 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 :obj:`~gi.repository.Gdk.ContentFormatsBuilder` instead. :param mime_types: Pointer to an array of mime types .. classmethod:: new_for_gtype(type: ~gobject.GType) -> ~gi.repository.Gdk.ContentFormats Creates a new ``GdkContentFormats`` for a given ``GType``\. :param type: a ``GType`` Methods ------- .. rst-class:: interim-class .. class:: ContentFormats :no-index: .. method:: contain_gtype(type: ~gobject.GType) -> bool Checks if a given ``GType`` is part of the given ``formats``\. :param type: the ``GType`` to search for .. method:: contain_mime_type(mime_type: str) -> bool Checks if a given mime type is part of the given ``formats``\. :param mime_type: the mime type to search for .. method:: get_gtypes() -> list[~gobject.GType] | None Gets the ``GType``\s included in ``formats``\. Note that ``formats`` may not contain any ``GType``\s, in particular when they are empty. In that case :const:`None` will be returned. .. method:: get_mime_types() -> list[str] | None Gets the mime types included in ``formats``\. Note that ``formats`` may not contain any mime types, in particular when they are empty. In that case :const:`None` will be returned. .. method:: match(second: ~gi.repository.Gdk.ContentFormats) -> bool Checks if ``first`` and ``second`` have any matching formats. :param second: the ``GdkContentFormats`` to intersect with .. method:: match_gtype(second: ~gi.repository.Gdk.ContentFormats) -> ~gobject.GType Finds the first ``GType`` from ``first`` that is also contained in ``second``\. If no matching ``GType`` is found, ``Invalid`` is returned. :param second: the ``GdkContentFormats`` to intersect with .. method:: match_mime_type(second: ~gi.repository.Gdk.ContentFormats) -> str | None Finds the first mime type from ``first`` that is also contained in ``second``\. If no matching mime type is found, :const:`None` is returned. :param second: the ``GdkContentFormats`` to intersect with .. classmethod:: parse() -> ~gi.repository.Gdk.ContentFormats | None Parses the given ``string`` into ``GdkContentFormats`` and returns the formats. Strings printed via :obj:`~gi.repository.Gdk.ContentFormats.to_string` can be read in again successfully using this function. If ``string`` does not describe valid content formats, :const:`None` is returned. .. versionadded:: 4.4 .. method:: print_(string: ~gi.repository.GLib.String) -> None :param string: .. method:: to_string() -> str Prints the given ``formats`` into a human-readable string. The resulting string can be parsed with :obj:`~gi.repository.Gdk.ContentFormats.parse`\. This is a small wrapper around :obj:`~gi.repository.Gdk.ContentFormats.print` to help when debugging. .. method:: union(second: ~gi.repository.Gdk.ContentFormats) -> ~gi.repository.Gdk.ContentFormats Append all missing types from ``second`` to ``first``\, in the order they had in ``second``\. :param second: the ``GdkContentFormats`` to merge from .. method:: union_deserialize_gtypes() -> ~gi.repository.Gdk.ContentFormats Add GTypes for mime types in ``formats`` for which deserializers are registered. .. method:: union_deserialize_mime_types() -> ~gi.repository.Gdk.ContentFormats Add mime types for GTypes in ``formats`` for which deserializers are registered. .. method:: union_serialize_gtypes() -> ~gi.repository.Gdk.ContentFormats Add GTypes for the mime types in ``formats`` for which serializers are registered. .. method:: union_serialize_mime_types() -> ~gi.repository.Gdk.ContentFormats Add mime types for GTypes in ``formats`` for which serializers are registered.