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.

async read_async(self, mime_types: list[str], io_priority: int) → tuple[InputStream | None, str]#

This is the awaitable version of read_async().

Parameters:

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

  • io_priority – the I/O priority of the request

read_async(mime_types: list[str], io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

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

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

async read_text_async(self) → str | None#

This is the awaitable version of read_text_async().

read_text_async(cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

Asynchronously request the clipboard contents converted to a string.

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

async read_texture_async(self) → Texture | None#

This is the awaitable version of read_texture_async().

read_texture_async(cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

Asynchronously request the clipboard contents converted to a GdkPixbuf.

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

async read_value_async(self, type: GType, io_priority: int) → Value#

This is the awaitable version of read_value_async().

Parameters:

  • type – a GType to read

  • io_priority – the I/O priority of the request

read_value_async(type: GType, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

Asynchronously request the clipboard contents converted to the given type.

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) → Value#

Finishes an asynchronous clipboard read.

See read_value_async.

Parameters:

result – a GAsyncResult

set(value: Value) → 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

async store_async(self, io_priority: int) → bool#

This is the awaitable version of store_async().

Parameters:

io_priority – the I/O priority of the request

store_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

Asynchronously instructs the clipboard to store its contents remotely.

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

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 type of the None singleton.

props.display: Display#

The type of the None singleton.

props.formats: ContentFormats#

The type of the None singleton.

props.local: bool#

The type of the None singleton.

Signals#

class Clipboard.signals
changed() → None#

The type of the None singleton.