Clipboard Portal - Copy and Paste

[Mikenux]

• This portal is not intended to acquire clipboard content or replace the system default clipboard. This is for clipboard copy and paste actions only.
• This portal is inspired by https://developer.android.com/develop/ui/views/touch-and-input/copy-paste.

---

Goals

• Copy content to the system clipboard in a controlled and reviewable manner.
• Paste content of the system clipboard in a controllable way.

Requirements

System Clipboard

The clipboard must be a visual clipboard that supports:

• The preview of the copied text.
• The display of file names and a symbolic icon of the relevant file type.
• The censorship of clips that an app has tagged as sensitive. The ability to reveal censored information must be present.
• Methods, restrictions and permissions in the sections below.

It should ideally support:

• Its positioning near where user input was triggered when a clip is copied or needs to be pasted.
• The preview of the clip content as much as possible. A preview replaces a symbolic icon when available for a file type.
• The conversion of files to text, i.e. pasting the filename, in case the app supports text but not a file.
• Keeping multiple clips.

Finally, the clipboard might have the option to delete censored clips once they have been pasted.

Apps

Apps must be able to send content to the clipboard according to the following specification:

• Files. Any file sent to the clipboard must use the "file://" URI scheme.
• Text. The plain text is sent as is.
• URIs. Any URI must be sent with its URI scheme. Without a URI scheme, the URI is interpreted as plain text.

Portal

• App Focus (see "Restrictions" section below; issue: Restrict some portals to focused applications #42).
• See other sections below.

Methods and Options

Ready To Copy

ReadyToCopy. Tells the portal that one or more clips have been selected and are ready to copy. Using this method is mandatory before using the "Copy" method. This method is specifically designed for touch input so that the clipboard is presented with a copy action.

When the "ReadyToCopy" method is used, the portal returns the following result to the app after the user triggers the copy action (see the "Permissions" section for details):

• can_copy. "yes" if the app can use the "Copy" method, "no" otherwise.

Copy

Copy. This method allows an app to send one or multiple clips to the clipboard. It can only be used after using the "ReadyToCopy" method. The app indicates what it sends using the convention described in the "Apps" subsection of the "Requirements" section. If the copied data is a file, the app must have access to it.

• sensitive. This option tells the portal that a clip must be censored. It is added for each clip to copy. Censoring involves replacing textual information with dots, for example. For files, the filename and preview are censored (a symbolic icon may replace it); the file type is not.

When one or more clips are copied, the following happens:

• The portal checks if the clips sent are valid clips. A valid clip is plain text or contains a valid formatted URI scheme for files and other URIs (see "Apps" subsection above). If a clip is invalid, the portal prohibits the app from sending and pasting clips forever and reports this to the user.
• If a clip is a file, the portal checks if the app has access to it. If so, the portal continues. Otherwise, the portal permanently prohibits sending and pasting clips for this app and returns an error to the user indicating that the app tried to copy files to which it does not have access.
• If everything is correct, the portal sends the clips to the clipboard. It also tells the system to display the visual clipboard to show the user visual feedback that the clips were successfully copied.
• If a clip is censored, the clipboard displays briefly the uncensored information to the user and then censors it. Appropriate delays depend on the clipboard implementation, with the goal being that the user sees enough information to know that the correct content has been copied.

Pastable Clip Types

PastableClipTypes. Method for defining the types of clips that can be pasted into a specific app space (e.g. window) or field (e.g. text input field). This helps filter clipboard content that can be pasted when presented visually to the user or to tell the app what types of clips the clipboard has.
-clip_types. Types of clips that can be pasted. Values ​​are either "text" for text input, "uri" for a text input field expecting a URI, a list of file types with their subtypes, or "all" for all values ​​mentioned. Leaving this field empty means that the application does not support clip pasting. For files, wildcards are not allowed for types (e.g. image, video), but allowed for subtypes (e.g. jpeg, mp4).

When the "PastableClipTypes" method is used, the portal checks whether a wildcard is used for types. If a wildcard is used for a type, the portal prohibits the app from copying and pasting clips forever and indicates to the user that the app has made an unauthorized request. If not, the portal returns one of the following responses to the app:

• available. The clipboard contains clips matching the reported clip types.
• unavailable. The clipboard does not contain any clips matching the reported clip types.

The above responses allow an app to communicate to the user whether pasting is available or not, for example by graying out (or not) a paste option (icon, menu item).

Finally, the app can receive the "available" and "unavailable" responses when clipboard clip types change.

Paste

Paste. Method to tell the portal to retrieve a clip from the clipboard and give it to the calling app.

When the app requests to paste a clip, the portal checks if the clip to paste is a clip type defined when using the "PastableClipTypes" method. If this is the case, pasting the clip works according to the permission set (see the "Permissions" section). If not, the portal tells the user that the app attempted to paste and there is no compatible clip.

Restrictions

An app can use the "copy", "paste", and "PastableClipTypes" methods only when it has the focus. This is not possible when it does not have the focus or when it is running in the background (i.e. without a window).

If the paste action is meant to be triggered with the mouse wheel, it is disabled when scrolling with the mouse wheel.

Permissions

When the "Copy" or "Paste" method is called for the first time, regardless of the app, the portal displays a general dialog box that communicates the following to the user:

• This allows to define how the clipboard should work for all apps.
• Copying and pasting can be triggered using corresponding shortcuts (keyboard, mouse, touch shortcuts). How to trigger these shortcuts is shown. For touch input, how to access the visual clipboard is presented.

This dialog also presents permissions for the paste action that the user can choose:

• Quick Paste. This option allows to directly paste a clip when the paste action is triggered with the shortcuts mentioned in the dialog. This limits the clipboard to holding one clip at a time. Concretely, this allows the user to have a smooth copy and paste experience.
• Confirm Pasting / Select clip. This option always presents the visual clipboard, so the user can preview the clips before pasting one. The permission is "Confirm Pasting" if the clipboard can only hold one clip, and "Select Clip" if it can hold multiple clips.

When the copy or paste action is triggered by the app and not by the user with the shortcuts, the portal acts differently:

• For the copy action, a dialog box asking to confirm the copy with a preview or information about the clip content is displayed.
• For the paste action, the visual clipboard is displayed to allow the user to select the clip to paste, even if the clipboard only supports one clip.

Notes:

• For the "Quick Paste" permission, a desktop environment can display its visual clipboard after a clip has been copied and continue to display it until a clip is pasted at least once.
• When permission is set, the dialog is no longer presented when the "copy" or "paste" methods are called by an app.

Censored Clips

See "Questions" section.

Questions

• Is something missing or wrong?
• Accessibility. How is a user using text-to-speech supposed to know what content has been copied if they is not using earphones or headset to privatize the audio output?
• There is the Wayland "text-input" protocol (https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/unstable/text-input/text-input-unstable-v3.xml?ref_type=heads).
  • Should a similar Wayland protocol be used instead of the "ReadyToCopy" and "PastableClipTypes" methods? Have an "Accessibility" protocol where apps indicate which UI element has the focus and which item (e.g. text) is selected?
  • Could some of the mentioned protocol content be helpful in indicating pastable clip types?
  • Can a request be allowed by keyboard, mouse or touch input on an element of the app interface?
• Are there reasons to override the restrictions? If yes, which ones and why?
• For censored clips, should the visual clipboard always be presented when pasting, even if the permission is set to "Quick Paste"?
• For censored clips, how should the censored content be revealed if the clipboard is shown when pasting? Automatically or on demand? Should this be a clipboard option?