## Clipboards Clipboards — Share data between applications for Copy-and-Paste |

## Functions

GdkDisplay * | gdk_clipboard_get_display ()
GdkContentFormats * | gdk_clipboard_get_formats ()
gboolean | gdk_clipboard_is_local ()
GdkContentProvider * | gdk_clipboard_get_content ()
void | gdk_clipboard_store_async ()
gboolean | gdk_clipboard_store_finish ()
void | gdk_clipboard_read_async ()
GInputStream * | gdk_clipboard_read_finish ()
void | gdk_clipboard_read_value_async ()
const GValue * | gdk_clipboard_read_value_finish ()
void | gdk_clipboard_read_texture_async ()
GdkTexture * | gdk_clipboard_read_texture_finish ()
void | gdk_clipboard_read_text_async ()
char * | gdk_clipboard_read_text_finish ()
gboolean | gdk_clipboard_set_content ()
void | gdk_clipboard_set ()
void | gdk_clipboard_set_valist ()
void | gdk_clipboard_set_value ()
void | gdk_clipboard_set_text ()
void | gdk_clipboard_set_texture ()

## Properties

GdkContentProvider * | content | Read
GdkDisplay * | display | Read / Write / Construct Only
GdkContentFormats * | formats | Read
gboolean | local | Read

## Signals

void | changed | Run Last

## Types and Values

| GdkClipboard

## Object Hierarchy

        GObject
        ╰── GdkClipboard

## Includes

    #include <gdk/gdk.h>

## Description

The GdkClipboard object represents a clipboard of data shared between different applications or between different parts of the same application.

To get a GdkClipboard object, use `gdk_display_get_clipboard()` or `gdk_display_get_primary_clipboard()`. You can find out about the data that is currently available in a clipboard using `gdk_clipboard_get_formats()`.

To make text or image data available in a clipboard, use `gdk_clipboard_set_text()` or `gdk_clipboard_set_texture()`. For other data, you can use `gdk_clipboard_set_content()`, which takes a GdkContentProvider object.

To read textual or image data from a clipboard, use `gdk_clipboard_read_text_async()` or `gdk_clipboard_read_texture_async()`. For other data, use `gdk_clipboard_read_async()`, which provides a GInputStream object.

## Functions

### gdk_clipboard_get_display ()

    GdkDisplay *
    gdk_clipboard_get_display (GdkClipboard *clipboard);

Gets the GdkDisplay that the clipboard was created for.

#### Parameters

clipboard | a GdkClipboard |

#### Returns

a GdkDisplay.

[transfer none]

### gdk_clipboard_get_formats ()

    GdkContentFormats *
    gdk_clipboard_get_formats (GdkClipboard *clipboard);

Gets the formats that the clipboard can provide its current contents in.

#### Parameters

clipboard | a GdkClipboard |

#### Returns

The formats of the clipboard.

[transfer none]

### gdk_clipboard_is_local ()

    gboolean
    gdk_clipboard_is_local (GdkClipboard *clipboard);

Returns if the clipboard is local. A clipboard is considered local if it was last claimed by the running application.

Note that `gdk_clipboard_get_content()` may return `NULL` even on a local clipboard. In this case the clipboard is empty.

#### Parameters

clipboard | a GdkClipboard |

#### Returns

`TRUE` if the clipboard is local

### gdk_clipboard_get_content ()

    GdkContentProvider *
    gdk_clipboard_get_content (GdkClipboard *clipboard);

Returns the GdkContentProvider currently set on `clipboard` . If the `clipboard` is empty or its contents are not owned by the current process, `NULL` will be returned.

#### Parameters

clipboard | a GdkClipboard |

#### Returns

The content of a clipboard or `NULL` if the clipboard does not maintain any content.

[transfer none][nullable]

### gdk_clipboard_store_async ()

    void
    gdk_clipboard_store_async (GdkClipboard *clipboard,
                               int io_priority,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

Asynchronously instructs the `clipboard` to store its contents remotely to preserve them for later usage. If the clipboard is not local, this function does nothing but report success.

This function is called automatically when `gtk_main()` or GtkApplication exit, so you likely don't need to call it.

#### Parameters

clipboard | a GdkClipboard |
io_priority | the I/O priority of the request. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
callback | callback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

### gdk_clipboard_store_finish ()

    gboolean
    gdk_clipboard_store_finish (GdkClipboard *clipboard,
                                GAsyncResult *result,
                                GError **error);

Finishes an asynchronous clipboard store started with `gdk_clipboard_store_async()`.

#### Parameters

clipboard | a GdkClipboard |
result | a GAsyncResult |
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

`TRUE` if storing was successful.

### gdk_clipboard_read_async ()

    void
    gdk_clipboard_read_async (GdkClipboard *clipboard,
                              const char **mime_types,
                              int io_priority,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback,
                              gpointer user_data);

Asynchronously requests an input stream to read the `clipboard` 's contents from. When the operation is finished `callback` will be called. You can then call `gdk_clipboard_read_finish()` to get the result of the operation.

The clipboard will choose the most suitable mime type from the given list to fulfill the request, preferring the ones listed first.

#### Parameters

clipboard | a GdkClipboard |
mime_types | a `NULL`-terminated array of mime types to choose from |
io_priority | the I/O priority of the request. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
callback | callback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

### gdk_clipboard_read_finish ()

    GInputStream *
    gdk_clipboard_read_finish (GdkClipboard *clipboard,
                               GAsyncResult *result,
                               const char **out_mime_type,
                               GError **error);

Finishes an asynchronous clipboard read started with `gdk_clipboard_read_async()`.

#### Parameters

clipboard | a GdkClipboard |
result | a GAsyncResult |
out_mime_type | pointer to store the chosen mime type in or `NULL`. | [out][allow-none][transfer none]
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

a GInputStream or `NULL` on error.

[transfer full]

### gdk_clipboard_read_value_async ()

    void
    gdk_clipboard_read_value_async (GdkClipboard *clipboard,
                                    GType type,
                                    int io_priority,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Asynchronously request the `clipboard` contents converted to the given `type` . When the operation is finished `callback` will be called. You can then call `gdk_clipboard_read_value_finish()` to get the resulting GValue.

For local clipboard contents that are available in the given GType, the value will be copied directly. Otherwise, GDK will try to use `gdk_content_deserialize_async()` to convert the clipboard's data.

#### Parameters

clipboard | a GdkClipboard |
type | a GType to read |
io_priority | the I/O priority of the request. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
callback | callback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

### gdk_clipboard_read_value_finish ()

    const GValue *
    gdk_clipboard_read_value_finish (GdkClipboard *clipboard,
                                     GAsyncResult *result,
                                     GError **error);

Finishes an asynchronous clipboard read started with `gdk_clipboard_read_value_async()`.

#### Parameters

clipboard | a GdkClipboard |
result | a GAsyncResult |
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

a GValue containing the result.

[transfer none]

### gdk_clipboard_read_texture_async ()

    void
    gdk_clipboard_read_texture_async (GdkClipboard *clipboard,
                                      GCancellable *cancellable,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

Asynchronously request the `clipboard` contents converted to a GdkPixbuf. When the operation is finished `callback` will be called. You can then call `gdk_clipboard_read_texture_finish()` to get the result.

This is a simple wrapper around `gdk_clipboard_read_value_async()`. Use that function or `gdk_clipboard_read_async()` directly if you need more control over the operation.

#### Parameters

clipboard | a GdkClipboard |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
callback | callback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

### gdk_clipboard_read_texture_finish ()

    GdkTexture *
    gdk_clipboard_read_texture_finish (GdkClipboard *clipboard,
                                       GAsyncResult *result,
                                       GError **error);

Finishes an asynchronous clipboard read started with `gdk_clipboard_read_texture_async()`.

#### Parameters

clipboard | a GdkClipboard |
result | a GAsyncResult |
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

a new GdkTexture or `NULL` on error.

[transfer full][nullable]

### gdk_clipboard_read_text_async ()

    void
    gdk_clipboard_read_text_async (GdkClipboard *clipboard,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

Asynchronously request the `clipboard` contents converted to a string. When the operation is finished `callback` will be called. You can then call `gdk_clipboard_read_text_finish()` to get the result.

This is a simple wrapper around `gdk_clipboard_read_value_async()`. Use that function or `gdk_clipboard_read_async()` directly if you need more control over the operation.

#### Parameters

clipboard | a GdkClipboard |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
callback | callback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

### gdk_clipboard_read_text_finish ()

    char *
    gdk_clipboard_read_text_finish (GdkClipboard *clipboard,
                                    GAsyncResult *result,
                                    GError **error);

Finishes an asynchronous clipboard read started with `gdk_clipboard_read_text_async()`.

#### Parameters

clipboard | a GdkClipboard |
result | a GAsyncResult |
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

a new string or `NULL` on error.

[transfer full][nullable]

### gdk_clipboard_set_content ()

    gboolean
    gdk_clipboard_set_content (GdkClipboard *clipboard,
                               GdkContentProvider *provider);

Sets a new content provider on `clipboard` . The clipboard will claim the GdkDisplay's resources and advertise these new contents to other applications.

In the rare case of a failure, this function will return `FALSE`. The clipboard will then continue reporting its old contents and ignore `provider` .

If the contents are read by either an external application or the `clipboard` 's read functions, `clipboard` will select the best format to transfer the contents and then request that format from `provider` .

#### Parameters

clipboard | a GdkClipboard |
provider | the new contents of `clipboard` or `NULL` to clear the clipboard. | [transfer none][allow-none]

#### Returns

`TRUE` if setting the clipboard succeeded

### gdk_clipboard_set ()

    void
    gdk_clipboard_set (GdkClipboard *clipboard,
                       GType type,
                       ...);

Sets the clipboard to contain the value collected from the given varargs.

#### Parameters

clipboard | a GdkClipboard |
type | type of value to set |
... | value contents conforming to `type` |

### gdk_clipboard_set_valist ()

    void
    gdk_clipboard_set_valist (GdkClipboard *clipboard,
                              GType type,
                              va_list args);

Sets the clipboard to contain the value collected from the given `args` .

[skip]

#### Parameters

clipboard | a GdkClipboard |
type | type of value to set |
args | varargs containing the value of `type` |

### gdk_clipboard_set_value ()

    void
    gdk_clipboard_set_value (GdkClipboard *clipboard,
                             const GValue *value);

Sets the `clipboard` to contain the given `value` .

[rename-to gdk_clipboard_set]

#### Parameters

clipboard | a GdkClipboard |
value | a GValue to set |

### gdk_clipboard_set_text ()

    void
    gdk_clipboard_set_text (GdkClipboard *clipboard,
                            const char *text);

Puts the given `text` into the clipboard.

[skip]

#### Parameters

clipboard | a GdkClipboard |
text | Text to put into the clipboard |

### gdk_clipboard_set_texture ()

    void
    gdk_clipboard_set_texture (GdkClipboard *clipboard,
                               GdkTexture *texture);

Puts the given `texture` into the clipboard.

[skip]

#### Parameters

clipboard | a GdkClipboard |
texture | a GdkTexture to put into the clipboard |

## Types and Values

### GdkClipboard

    typedef struct _GdkClipboard GdkClipboard;

The GdkClipboard struct contains only private fields and should not be accessed directly.

## Property Details

### The `“content”` property

      “content”                  GdkContentProvider *

The GdkContentProvider or `NULL` if the clipboard is empty or contents are provided otherwise.

Owner: GdkClipboard

Flags: Read

### The `“display”` property

      “display”                  GdkDisplay *

The GdkDisplay that the clipboard belongs to.

Owner: GdkClipboard

Flags: Read / Write / Construct Only

### The `“formats”` property

      “formats”                  GdkContentFormats *

The possible formats that the clipboard can provide its data in.

Owner: GdkClipboard

Flags: Read

### The `“local”` property

      “local”                    gboolean

`TRUE` if the contents of the clipboard are owned by this process.

Owner: GdkClipboard

Flags: Read

Default value: TRUE

## Signal Details

### The `“changed”` signal

    void
    user_function (GdkClipboard *clipboard,
                   gpointer      user_data)

The ::changed signal is emitted when the clipboard changes ownership.

#### Parameters

clipboard | the object on which the signal was emitted |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

## See Also

GdkContentProvider, GdkContentFormats