Gdk.ContentFormats¶

record (struct)

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 Drag, Drop, Clipboard or 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 and 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 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 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 ContentFormatsBuilder structure is meant to help in this endeavor.

Constructors¶

new¶

@classmethod
def new(cls, mime_types: list[str] | None = ...) -> 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 ContentFormatsBuilder instead.

Parameters:

mime_types — Pointer to an array of mime types

new_for_gtype¶

@classmethod
def new_for_gtype(cls, type: type | GObject.Type) -> ContentFormats

Creates a new GdkContentFormats for a given GType.

Parameters:

type — a GType

Methods¶

contain_gtype¶

def contain_gtype(self, type: type | GObject.Type) -> bool

Checks if a given GType is part of the given formats.

Parameters:

type — the GType to search for

contain_mime_type¶

def contain_mime_type(self, mime_type: str) -> bool

Checks if a given mime type is part of the given formats.

Parameters:

mime_type — the mime type to search for

get_gtypes¶

def get_gtypes(self) -> list[type | GObject.Type] | None

Gets the GTypes included in formats.

Note that formats may not contain any GTypes, in particular when they are empty. In that case None will be returned.

get_mime_types¶

def get_mime_types(self) -> 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 None will be returned.

is_empty¶

def is_empty(self) -> bool

Returns whether the content formats contain any formats.

match_¶

def match_(self, second: ContentFormats) -> bool

Checks if first and second have any matching formats.

Parameters:

second — the GdkContentFormats to intersect with

match_gtype¶

def match_gtype(self, second: ContentFormats) -> type | GObject.Type

Finds the first GType from first that is also contained in second.

If no matching GType is found, G_TYPE_INVALID is returned.

Parameters:

second — the GdkContentFormats to intersect with

match_mime_type¶

def match_mime_type(self, second: ContentFormats) -> str | None

Finds the first mime type from first that is also contained in second.

If no matching mime type is found, None is returned.

Parameters:

second — the GdkContentFormats to intersect with

print¶

def print(self, string: GLib.String) -> None

Prints the given formats into a string for human consumption.

The result of this function can later be parsed with ContentFormats.parse.

Parameters:

string — a GString to print into

ref¶

def ref(self) -> ContentFormats

Increases the reference count of a GdkContentFormats by one.

to_string¶

def to_string(self) -> str

Prints the given formats into a human-readable string.

The resulting string can be parsed with ContentFormats.parse.

This is a small wrapper around ContentFormats.print to help when debugging.

union¶

def union(self, second: ContentFormats) -> ContentFormats

Append all missing types from second to first, in the order they had in second.

Parameters:

second — the GdkContentFormats to merge from

union_deserialize_gtypes¶

def union_deserialize_gtypes(self) -> ContentFormats

Add GTypes for mime types in formats for which deserializers are registered.

union_deserialize_mime_types¶

def union_deserialize_mime_types(self) -> ContentFormats

Add mime types for GTypes in formats for which deserializers are registered.

union_serialize_gtypes¶

def union_serialize_gtypes(self) -> ContentFormats

Add GTypes for the mime types in formats for which serializers are registered.

union_serialize_mime_types¶

def union_serialize_mime_types(self) -> ContentFormats

Add mime types for GTypes in formats for which serializers are registered.

unref¶

def unref(self) -> None

Decreases the reference count of a GdkContentFormats by one.

If the resulting reference count is zero, frees the formats.

Static functions¶

parse¶

@staticmethod
def parse(string: str) -> ContentFormats | None

Parses the given string into GdkContentFormats and returns the formats.

Strings printed via ContentFormats.to_string can be read in again successfully using this function.

If string does not describe valid content formats, None is returned.

Parameters:

string — the string to parse