## Content Formats Content Formats — Advertising and negotiating of content exchange formats |

## Functions

const char * | gdk_intern_mime_type ()
GdkContentFormats * | gdk_content_formats_new ()
GdkContentFormats * | gdk_content_formats_new_for_gtype ()
GdkContentFormats * | gdk_content_formats_ref ()
void | gdk_content_formats_unref ()
void | gdk_content_formats_print ()
char * | gdk_content_formats_to_string ()
const GType * | gdk_content_formats_get_gtypes ()
const char * const * | gdk_content_formats_get_mime_types ()
GdkContentFormats * | gdk_content_formats_union ()
gboolean | gdk_content_formats_match ()
GType | gdk_content_formats_match_gtype ()
const char * | gdk_content_formats_match_mime_type ()
gboolean | gdk_content_formats_contain_gtype ()
gboolean | gdk_content_formats_contain_mime_type ()
GdkContentFormats * | gdk_content_formats_union_serialize_gtypes ()
GdkContentFormats * | gdk_content_formats_union_deserialize_gtypes ()
GdkContentFormats * | gdk_content_formats_union_serialize_mime_types ()
GdkContentFormats * | gdk_content_formats_union_deserialize_mime_types ()
GdkContentFormatsBuilder * | gdk_content_formats_builder_new ()
GdkContentFormats * | gdk_content_formats_builder_free_to_formats ()
void | gdk_content_formats_builder_add_formats ()
void | gdk_content_formats_builder_add_gtype ()
void | gdk_content_formats_builder_add_mime_type ()
GdkContentFormatsBuilder * | gdk_content_formats_builder_ref ()
void | gdk_content_formats_builder_unref ()
GdkContentFormats * | gdk_content_formats_builder_to_formats ()

## Types and Values

| GdkContentFormats
| GdkContentFormatsBuilder

## 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.

### 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

builder | a GdkContentFormatsBuilder |

#### 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

builder | a GdkContentFormatsBuilder |

#### 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

builder | a GdkContentFormatsBuilder |

### 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

builder | a GdkContentFormatsBuilder |

#### 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.

## See Also

GdkDrag, GdkDrop, GdkClipboard, GdkContentProvider