Clipboard🔗

Portal for accessing the clipboard

The Clipboard portal allows sessions to access the clipboard.

This portal does not create its own sessions. Instead, it extends sessions created by other portals with clipboard access. Currently, the Remote Desktop and Input Capture portals support clipboard integration.

This documentation describes version 1 of this interface.

Setting up clipboard access🔗

To use the clipboard, call RequestClipboard() on a session created by a compatible portal before the session is started. Whether clipboard access was granted is reported in the clipboard_enabled result of the session’s Start() response.

Note that other portals may place restrictions on when it is possible to interact with the clipboard. For input capture sessions, clipboard access is only available while the session is active.

Clipboard data transfer🔗

The clipboard uses a MIME type-based ownership and transfer model:

An owner advertises available formats by calling SetSelection() with a list of MIME types.
The SelectionOwnerChanged signal notifies all participants when the clipboard owner changes, including the list of available MIME types.
To read clipboard content, call SelectionRead() with the desired MIME type. A file descriptor for reading the data is returned.
When another participant requests data from this session’s clipboard, the SelectionTransfer signal is emitted with a MIME type and a serial number. The session must call SelectionWrite() with that serial to obtain a file descriptor for writing the data, and call SelectionWriteDone() when the transfer is complete or has failed.

Files can be transferred through the clipboard using the application/vnd.portal.filetransfer MIME type. See File Transfer for details.

Properties🔗

org.freedesktop.portal.Clipboard:version🔗

version readable u

Methods🔗

org.freedesktop.portal.Clipboard.RequestClipboard🔗

RequestClipboard (
  IN session_handle o,
  IN options a{sv}
)

Requests clipboard access for the given portal session. This request must be made before the session starts. The session must be started, before using any other method in this interface which take a session. Note that other interfaces might place restriction on when it’s possible to interact with the clipboard.

This portal does NOT create its own session. Instead, it offers existing sessions created from other portals the option to integrate with the clipboard.

For whether this interface is supported for a given session, refer to that portal’s documentation. See Remote Desktop to integrate clipboard with the remote desktop session. See Input Capture to integrate clipboard with the input capture session.

session_handle: Object path for the Session object
options: Vardict with optional further information

org.freedesktop.portal.Clipboard.SetSelection🔗

SetSelection (
  IN session_handle o,
  IN options a{sv}
)

Sets the owner of the clipboard formats in mime_types in options to the session, i.e. this session has data for the advertised clipboard formats.

See File Transfer to transfer files using the application/vnd.portal.filetransfer mimetype.

May only be called if clipboard access was given after starting the session.

Supported keys in the options vardict include:

mime_types (as)

A list of mime types that the session has clipboard content for.

session_handle: Object path for the Session object
options: Vardict with optional further information

org.freedesktop.portal.Clipboard.SelectionWrite🔗

SelectionWrite (
  IN session_handle o,
  IN serial u,
  OUT fd h
)

Answer to org.freedesktop.portal.Clipboard::SelectionTransfer signal. Transfers the clipboard content for the given serial to the method callee via a file descriptor. It is the Callee that creates the file descriptor.

May only be called if clipboard access was given after starting the session.

session_handle: Object path for the Session object
serial: The serial of the request where this answer is directed towards
fd: A UnixFD handle to the contents of the selection being written to

org.freedesktop.portal.Clipboard.SelectionWriteDone🔗

SelectionWriteDone (
  IN session_handle o,
  IN serial u,
  IN success b
)

Notifies that the transfer of the clipboard data has either completed successfully, or failed.

May only be called if clipboard access was given after starting the session.

session_handle: Object path for the Session object
serial: The serial of the request where this answer is directed to
success: A boolean which indicates whether the transfer of the clipboard data was successful (true) or not (false)

org.freedesktop.portal.Clipboard.SelectionRead🔗

SelectionRead (
  IN session_handle o,
  IN mime_type s,
  OUT fd h
)

Transfer the clipboard content given the specified mime type to the method caller via a file descriptor.

The creation of the file descriptor is the responsibility of the callee.

May only be called if clipboard access was given after starting the session.

session_handle: Object path for the Session object
mime_type: The MIME type string of the requested format
fd: A UnixFD handle to the contents of the selection being read

Signals🔗

org.freedesktop.portal.Clipboard::SelectionOwnerChanged🔗

SelectionOwnerChanged (
  session_handle o,
  options a{sv}
)

Notifies the session that the clipboard selection has changed.

Caller will only be notified if clipboard access was given after starting the session.

Supported keys in the options vardict include:

mime_types (as)

A list of MIME types for which the new clipboard selection has content
session_is_owner (b)

A boolean for whether the session is the owner of the clipboard selection (‘true’) or not (‘false’)

session_handle: Object path for the Session object
options: Vardict with optional further information

org.freedesktop.portal.Clipboard::SelectionTransfer🔗

SelectionTransfer (
  session_handle o,
  mime_type s,
  serial u
)

Notifies the session of a request for clipboard content of the given mime type. The callee provides a serial to track the request, which any org.freedesktop.portal.Clipboard.SelectionWrite responses must use.

Once the caller is done handling the org.freedesktop.portal.Clipboard::SelectionTransfer request, they must call org.freedesktop.portal.Clipboard.SelectionWriteDone with the corresponding request’s serial and whether the request completed successfully. If the request is not handled, the caller should respond by setting success to ‘false’.

Caller will only be notified if clipboard access was given after starting the session.

session_handle: Object path for the Session object
mime_type: The mime-type string of the requested format
serial: The serial used to track this transfer, to which the answer of this request must use