Gdk.Clipboard¶

class — extends GObject.Object

Represents data shared between applications or inside an application.

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

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

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

Methods¶

get_content¶

def get_content(self) -> 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¶

def get_display(self) -> Display

Gets the GdkDisplay that the clipboard was created for.

get_formats¶

def get_formats(self) -> ContentFormats

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

is_local¶

def is_local(self) -> bool

Returns if the clipboard is local.

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

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

read_async¶

def read_async(self, mime_types: list[str], io_priority: int, cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | 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

read_finish¶

def read_finish(self, result: Gio.AsyncResult) -> tuple[Gio.InputStream | None, str]

Finishes an asynchronous clipboard read.

See Clipboard.read_async.

Parameters:

result — a GAsyncResult

read_text_async¶

def read_text_async(self, cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | None = ...) -> None

Asynchronously request the clipboard contents converted to a string.

This is a simple wrapper around Clipboard.read_value_async. Use that function or Clipboard.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

read_text_finish¶

def read_text_finish(self, result: Gio.AsyncResult) -> str | None

Finishes an asynchronous clipboard read.

See Clipboard.read_text_async.

Parameters:

result — a GAsyncResult

read_texture_async¶

def read_texture_async(self, cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | None = ...) -> None

Asynchronously request the clipboard contents converted to a GdkPixbuf.

This is a simple wrapper around Clipboard.read_value_async. Use that function or Clipboard.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

read_texture_finish¶

def read_texture_finish(self, result: Gio.AsyncResult) -> Texture | None

Finishes an asynchronous clipboard read.

See Clipboard.read_texture_async.

Parameters:

result — a GAsyncResult

read_value_async¶

def read_value_async(self, type: type | GObject.Type, io_priority: int, cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | 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

read_value_finish¶

def read_value_finish(self, result: Gio.AsyncResult) -> GObject.Value

Finishes an asynchronous clipboard read.

See Clipboard.read_value_async.

Parameters:

result — a GAsyncResult

set_content¶

def set_content(self, provider: ContentProvider | 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

set¶

def set(self, value: GObject.Value) -> None

Sets the clipboard to contain the given value.

Parameters:

value — a GValue to set

store_async¶

def store_async(self, io_priority: int, cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | 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

store_finish¶

def store_finish(self, result: Gio.AsyncResult) -> bool

Finishes an asynchronous clipboard store.

See Clipboard.store_async.

Parameters:

result — a GAsyncResult

Properties¶

content¶

content: ContentProvider  # read-only

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

display¶

display: Display  # read/write

The GdkDisplay that the clipboard belongs to.

formats¶

formats: ContentFormats  # read-only

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

local¶

local: bool  # read-only

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

Signals¶

changed¶

def on_changed(self) -> None: ...

Emitted when the clipboard changes ownership.