Content Formats

Content Formats — Advertising and negotiating of content exchange formats

Object Hierarchy

    GBoxed
    ╰── GdkContentFormats

Includes

#include <gdk/gdk.h>

Description

This section describes the GdkContentFormats structure that is used to advertise and negotiate the format of content passed between different widgets, windows or applications using for example the clipboard or drag'n'drop.

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.

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 gdk_content_formats_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 gdk_content_formats_to_string() exists. It will print a comma-seperated formats 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 GdkContentFormatsBuilder structure is meant to help in this endeavor.

Functions

gdk_intern_mime_type ()

const char *
gdk_intern_mime_type (const char *string);

Canonicalizes the given mime type and interns the result.

If string is not a valid mime type, NULL is returned instead. See RFC 2048 for the syntax if mime types.

Parameters

string

string of a potential mime type.

[transfer none]

Returns

An interned string for the canonicalized mime type or NULL if the string wasn't a valid mime type


gdk_content_formats_new ()

GdkContentFormats *
gdk_content_formats_new (const char **mime_types,
                         guint n_mime_types);

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 GdkContentFormatsBuilder instead.

Parameters

mime_types

Pointer to an array of mime types.

[array length=n_mime_types][allow-none]

n_mime_types

number of entries in mime_types .

 

Returns

the new GdkContentFormats.

[transfer full]


gdk_content_formats_new_for_gtype ()

GdkContentFormats *
gdk_content_formats_new_for_gtype (GType type);

Creates a new GdkContentFormats for a given GType.

Parameters

type

a $GType

 

Returns

a new GdkContentFormats


gdk_content_formats_ref ()

GdkContentFormats *
gdk_content_formats_ref (GdkContentFormats *formats);

Increases the reference count of a GdkContentFormats by one.

Parameters

formats

a GdkContentFormats

 

Returns

the passed in GdkContentFormats.


gdk_content_formats_unref ()

void
gdk_content_formats_unref (GdkContentFormats *formats);

Decreases the reference count of a GdkContentFormats by one. If the resulting reference count is zero, frees the formats.

Parameters

formats

a GdkContentFormats

 

gdk_content_formats_print ()

void
gdk_content_formats_print (GdkContentFormats *formats,
                           GString *string);

Prints the given formats into a string for human consumption. This is meant for debugging and logging.

The form of the representation may change at any time and is not guaranteed to stay identical.

Parameters

formats

a GdkContentFormats

 

string

a GString to print into

 

gdk_content_formats_to_string ()

char *
gdk_content_formats_to_string (GdkContentFormats *formats);

Prints the given formats into a human-readable string. This is a small wrapper around gdk_content_formats_print() to help when debugging.

Parameters

formats

a GdkContentFormats

 

Returns

a new string.

[transfer full]


gdk_content_formats_get_gtypes ()

const GType *
gdk_content_formats_get_gtypes (const GdkContentFormats *formats,
                                gsize *n_gtypes);

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

Parameters

formats

a GdkContentFormats

 

n_gtypes

optional pointer to take the number of GTypes contained in the return value.

[out][optional]

Returns

G_TYPE_INVALID-terminated array of types included in formats or NULL if none.

[transfer none][nullable][array length=n_gtypes]


gdk_content_formats_get_mime_types ()

const char * const *
gdk_content_formats_get_mime_types (const GdkContentFormats *formats,
                                    gsize *n_mime_types);

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 NULL will be returned.

Parameters

formats

a GdkContentFormats

 

n_mime_types

optional pointer to take the number of mime types contained in the return value.

[out][allow-none]

Returns

NULL-terminated array of interned strings of mime types included in formats or NULL if none.

[transfer none][nullable]


gdk_content_formats_union ()

GdkContentFormats *
gdk_content_formats_union (GdkContentFormats *first,
                           const GdkContentFormats *second);

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

Parameters

first

the GdkContentFormats to merge into.

[transfer full]

second

the GdkContentFormats to merge from.

[transfer none]

Returns

a new GdkContentFormats


gdk_content_formats_match ()

gboolean
gdk_content_formats_match (const GdkContentFormats *first,
                           const GdkContentFormats *second);

Checks if first and second have any matching formats.

Parameters

first

the primary GdkContentFormats to intersect

 

second

the GdkContentFormats to intersect with

 

Returns

TRUE if a matching format was found.


gdk_content_formats_match_gtype ()

GType
gdk_content_formats_match_gtype (const GdkContentFormats *first,
                                 const GdkContentFormats *second);

Finds the first GType from first that is also contained in second . If no matching GType is found, G_TYPE_INVALID is returned.

Parameters

first

the primary GdkContentFormats to intersect

 

second

the GdkContentFormats to intersect with

 

Returns

The first common GType or G_TYPE_INVALID if none.


gdk_content_formats_match_mime_type ()

const char *
gdk_content_formats_match_mime_type (const GdkContentFormats *first,
                                     const GdkContentFormats *second);

Finds the first mime type from first that is also contained in second . If no matching mime type is found, NULL is returned.

Parameters

first

the primary GdkContentFormats to intersect

 

second

the GdkContentFormats to intersect with

 

Returns

The first common mime type or NULL if none.

[nullable]


gdk_content_formats_contain_gtype ()

gboolean
gdk_content_formats_contain_gtype (const GdkContentFormats *formats,
                                   GType type);

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

Parameters

formats

a GdkContentFormats

 

type

the GType to search for

 

Returns

TRUE if the GType was found


gdk_content_formats_contain_mime_type ()

gboolean
gdk_content_formats_contain_mime_type (const GdkContentFormats *formats,
                                       const char *mime_type);

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

Parameters

formats

a GdkContentFormats

 

mime_type

the mime type to search for

 

Returns

TRUE if the mime_type was found


gdk_content_formats_union_serialize_gtypes ()

GdkContentFormats *
gdk_content_formats_union_serialize_gtypes
                               (GdkContentFormats *formats);

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

Return: a new GdkContentFormats

Parameters

formats

a GdkContentFormats.

[transfer full]

gdk_content_formats_union_deserialize_gtypes ()

GdkContentFormats *
gdk_content_formats_union_deserialize_gtypes
                               (GdkContentFormats *formats);

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

Return: a new GdkContentFormats

Parameters

formats

a GdkContentFormats.

[transfer full]

gdk_content_formats_union_serialize_mime_types ()

GdkContentFormats *
gdk_content_formats_union_serialize_mime_types
                               (GdkContentFormats *formats);

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

Return: a new GdkContentFormats

Parameters

formats

a GdkContentFormats.

[transfer full]

gdk_content_formats_union_deserialize_mime_types ()

GdkContentFormats *
gdk_content_formats_union_deserialize_mime_types
                               (GdkContentFormats *formats);

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

Return: a new GdkContentFormats

Parameters

formats

a GdkContentFormats.

[transfer full]

gdk_content_formats_builder_new ()

GdkContentFormatsBuilder *
gdk_content_formats_builder_new (void);

Create a new GdkContentFormatsBuilder object. The resulting builder would create an empty GdkContentFormats. Use addition functions to add types to it.

Returns

a new GdkContentFormatsBuilder


gdk_content_formats_builder_free_to_formats ()

GdkContentFormats *
gdk_content_formats_builder_free_to_formats
                               (GdkContentFormatsBuilder *builder);

Creates a new GdkContentFormats from the current state of the given builder , and frees the builder instance.

[skip]

Parameters

Returns

the newly created GdkContentFormats with all the formats added to builder .

[transfer full]


gdk_content_formats_builder_add_formats ()

void
gdk_content_formats_builder_add_formats
                               (GdkContentFormatsBuilder *builder,
                                const GdkContentFormats *formats);

Appends all formats from formats to builder , skipping those that already exist.

Parameters

builder

a GdkContentFormatsBuilder

 

formats

the formats to add

 

gdk_content_formats_builder_add_gtype ()

void
gdk_content_formats_builder_add_gtype (GdkContentFormatsBuilder *builder,
                                       GType type);

Appends gtype to builder if it has not already been added.

Parameters

builder

a GdkContentFormatsBuilder

 

type

a GType

 

gdk_content_formats_builder_add_mime_type ()

void
gdk_content_formats_builder_add_mime_type
                               (GdkContentFormatsBuilder *builder,
                                const char *mime_type);

Appends mime_type to builder if it has not already been added.

Parameters

builder

a GdkContentFormatsBuilder

 

mime_type

a mime type

 

gdk_content_formats_builder_ref ()

GdkContentFormatsBuilder *
gdk_content_formats_builder_ref (GdkContentFormatsBuilder *builder);

Acquires a reference on the given builder .

This function is intended primarily for bindings. GdkContentFormatsBuilder objects should not be kept around.

Parameters

Returns

the given GdkContentFormatsBuilder with its reference count increased.

[transfer none]


gdk_content_formats_builder_unref ()

void
gdk_content_formats_builder_unref (GdkContentFormatsBuilder *builder);

Releases a reference on the given builder .

Parameters


gdk_content_formats_builder_to_formats ()

GdkContentFormats *
gdk_content_formats_builder_to_formats
                               (GdkContentFormatsBuilder *builder);

Creates a new GdkContentFormats from the given builder .

The given GdkContentFormatsBuilder is reset once this function returns; you cannot call this function multiple times on the same builder instance.

This function is intended primarily for bindings. C code should use gdk_content_formats_builder_free_to_formats().

Parameters

Returns

the newly created GdkContentFormats with all the formats added to builder .

[transfer full]

Types and Values

GdkContentFormats

typedef struct _GdkContentFormats GdkContentFormats;

A GdkContentFormats struct is a reference counted struct and should be treated as opaque.


GdkContentFormatsBuilder

typedef struct _GdkContentFormatsBuilder GdkContentFormatsBuilder;

A GdkContentFormatsBuilder struct is an opaque struct. It is meant to not be kept around and only be used to create new GdkContentFormats objects.