Clipboard

class Clipboard(**properties: Any)

Superclasses: Object

The GdkClipboard object represents data shared between applications or inside an application.

To get a GdkClipboard object, use get_clipboard or get_primary_clipboard. You can find out about the data that is currently available in a clipboard using get_formats.

To make text or image data available in a clipboard, use set_text or set_texture. For other data, you can use set_content, which takes a ContentProvider object.

To read textual or image data from a clipboard, use read_text_async or read_texture_async. For other data, use read_async, which provides a GInputStream object.

Methods

class Clipboard
get_content() → ContentProvider | None

Returns the GdkContentProvider currently set on clipboard.

If the clipboard is empty or its contents are not owned by the current process, None will be returned.

get_display() → Display

Gets the GdkDisplay that the clipboard was created for.

get_formats() → ContentFormats

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

is_local() → bool

Returns if the clipboard is local.

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

Note that get_content may return None even on a local clipboard. In this case the clipboard is empty.

read_async(mime_types: Sequence[str], io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Asynchronously requests an input stream to read the clipboard’s contents from.

When the operation is finished callback will be called. You must then call 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:

  • mime_types – a None-terminated array of mime types to choose from

  • io_priority – the I/O priority of the request

  • cancellable – optional GCancellable object

  • callback – callback to call when the request is satisfied

  • user_data – the data to pass to callback function

read_finish(result: AsyncResult) → tuple[InputStream | None, str]

Finishes an asynchronous clipboard read.

See read_async.

Parameters:

result – a GAsyncResult

read_text_async(cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Asynchronously request the clipboard contents converted to a string.

When the operation is finished callback will be called. You must then call read_text_finish to get the result.

This is a simple wrapper around read_value_async. Use that function or read_async directly if you need more control over the operation.

Parameters:

  • cancellable – optional GCancellable object

  • callback – callback to call when the request is satisfied

  • user_data – the data to pass to callback function

read_text_finish(result: AsyncResult) → str | None

Finishes an asynchronous clipboard read.

See read_text_async.

Parameters:

result – a GAsyncResult

read_texture_async(cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Asynchronously request the clipboard contents converted to a GdkPixbuf.

When the operation is finished callback will be called. You must then call read_texture_finish to get the result.

This is a simple wrapper around read_value_async. Use that function or read_async directly if you need more control over the operation.

Parameters:

  • cancellable – optional GCancellable object, None to ignore.

  • callback – callback to call when the request is satisfied

  • user_data – the data to pass to callback function

read_texture_finish(result: AsyncResult) → Texture | None

Finishes an asynchronous clipboard read.

See read_texture_async.

Parameters:

result – a GAsyncResult

read_value_async(type: type, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Asynchronously request the clipboard contents converted to the given type.

When the operation is finished callback will be called. You must then call 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 content_deserialize_async to convert the clipboard’s data.

Parameters:

  • type – a GType to read

  • io_priority – the I/O priority of the request

  • cancellable – optional GCancellable object

  • callback – callback to call when the request is satisfied

  • user_data – the data to pass to callback function

read_value_finish(result: AsyncResult) → Any

Finishes an asynchronous clipboard read.

See read_value_async.

Parameters:

result – a GAsyncResult

set(value: Any) → None

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

Values should be passed the same way they are passed to other value collecting APIs, such as set or signal_emit.

gdk_clipboard_set (clipboard, GTK_TYPE_STRING, "Hello World");

gdk_clipboard_set (clipboard, GDK_TYPE_TEXTURE, some_texture);
Parameters:

value

set_content(provider: ContentProvider | None = None) → bool

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:

provider – the new contents of clipboard or None to clear the clipboard

store_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Asynchronously instructs the clipboard to store its contents remotely.

If the clipboard is not local, this function does nothing but report success.

The callback must call store_finish.

The purpose of this call is to preserve clipboard contents beyond the lifetime of an application, so this function is typically called on exit. Depending on the platform, the functionality may not be available unless a “clipboard manager” is running.

This function is called automatically when a GtkApplication is shut down, so you likely don’t need to call it.

Parameters:

  • io_priority – the I/O priority of the request

  • cancellable – optional GCancellable object

  • callback – callback to call when the request is satisfied

  • user_data – the data to pass to callback function

store_finish(result: AsyncResult) → bool

Finishes an asynchronous clipboard store.

See store_async.

Parameters:

result – a GAsyncResult

Properties

class Clipboard
props.content: ContentProvider

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

props.display: Display

The GdkDisplay that the clipboard belongs to.

props.formats: ContentFormats

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

props.local: bool

True if the contents of the clipboard are owned by this process.

Signals

class Clipboard.signals
changed() → None

Emitted when the clipboard changes ownership.