clipboard data transfer api

[timon-schelling]

Add ActiveEventLoop::clipboard and ActiveEventLoop::set_clipboard for
interacting with the system clipboard through the data transfer API, implemented on Wayland, X11, macOS and Windows.

• Tested on all platforms changed
• Added an entry to the changelog module if knowledge of this change could be valuable to users
• Updated documentation to reflect any user-facing changes, including notes of platform-specific behavior
• Created or updated an example program if it would help users understand this functionality

Follow-up of #4571

Addition to public API consists of two new methods on ActiveEventLoop, both defaulting to NotSupported:

fn clipboard(&self) -> Result<Option<DataTransferId>, RequestError>;
fn set_clipboard(&self, send_data: Box<dyn DataTransferSend>) -> Result<(), RequestError>;

Works like the DnD API. clipboard() gives you a DataTransferId, or None if
the clipboard is empty. Pass it to data_transfer() for the types and
fetch_data_transfer() for the data, which arrives as DataTransferReceived.
set_clipboard() takes a DataTransferSend, encoded lazily when another app
asks for a type, and dropped when someone else takes over the clipboard.

Tested with new clipboard example: press C to copy, V to paste, logs the advertised types etc.
Tested with plaintext and images on Wayland (hyprland, niri and kwin), Xwayland, macOS 16 and Windows 11.
Also tested in Graphite's desktop app (Integration PR).

Changes to be aware of that are not strictly required for the feature but I think desirable:

• dnd modules renamed to data_transfer, and DndState to
  DataTransferState.
• Fixes pre-existing bug on Wayland where a completed fetch did not set dispatched_events.
• Fixes drag icon surface on Wayland not being destroyed when drag ends.
• Fixes pre-existing bug on Wayland where fetch_data_transfer() failed when called on DragDroped (only fetching on DragEntered was guaranteed, witch is inconsistent with other platforms).
• On Windows flushes OLE clipboard on shutdown to make sure other applications can still read the data (not an expert on win32 common behavior but I found at least qt doing the same and Microsoft docs also suggest this).
• On Windows moved OLE initialization into a function that calls the underlying ole2.h API function at most once per thread.
• On macOS resolve file-reference URLs when converting to file paths.

Should be done in followup (intentionally not included here):

• Implement Linux extension trait that allows for access to the Primary clipboard.

Thanks to @0HyperCube for implementing the X11 backend!

[ogoffart]

Thanks a lot for working on this.

One problem with the API is that this doesn't support multiple clipboard like the middle-click paste vs ctrl+c/v.

I'm thinking the clipboard and set_clipboard functions should take an enum telling what keyboard we want.

[timon-schelling]

Thanks a lot for working on this.

One problem with the API is that this doesn't support multiple clipboard like the middle-click paste vs ctrl+c/v.

I'm thinking the clipboard and set_clipboard functions should take an enum telling what keyboard we want.

Thank for the review.
Assuming you mean clipboard not keyboard.

Isn't the primary selection just a Linux thing?
I assumed that it should only be accessible via platform extension trait and that it should not really influence the main API design?

If it should be part of the general API I would also suggest taking an enum with Clipboard::Selection and Clipboard::Primary.

[ogoffart]

Yes, I meant clipboard.
Yes, it is a linux thing.
Selection and Primary are the same thing.
But yes, an enum such as Clipboard::Selection and Clipboard::Clipboard. (i'm not very good at naming things)

[timon-schelling]

Yes, I meant clipboard.
Yes, it is a linux thing.
Selection and Primary are the same thing.
But yes, an enum such as Clipboard::Selection and Clipboard::Clipboard. (i'm not very good at naming things)

An you would prefer that being part of the cross platform api (would be easier to implement I guess)?
And not a ActiveEventLoopClipboardPrimaryExt:: clipboard_primary?

If it should be a cross platform thing what should platforms that don't have the primary selection do? Return unsupported?

[kchibisov]

I think one other point is that this API should be brought to every platform that is supported by other clipboard crates, so x11/wayland/windows/macOS at least, so users who rely on special crates for clipboard can just replace them with winit clipboard...

And yeah, on linux we'd need an extra trait for set_primary_clipboard etc,

[timon-schelling]

I'm working on/thinking about the mac implementation, and I could also work on x11 (my testing would be limited to Xwayland) but not sure when I would be able to work on Windows, likely better if someone else with more Windows knowledge works on that.

Personally I would prefer every platform being in it's own (stacked) PR but if maintainers prefer this being one giant PR sure.

And I will add a trait for primary selection, definitely the shape I prefer.

[timon-schelling]

appkit implementation is now in shape I'm happy with, less complicated than initially anticipated. I'm not making good progress with x11 though and haven't looked much into the windows side.

[0HyperCube]

Hi, I'm collaborating with Timon into adding the X11 backend. I have a mostly working implementation at timon-schelling#1.

X11 requires an event to get the possible TARGETS for pasting such as STRING, text/html, etc. The result is delivered as a separate event some time later. This makes it impossible to integrate with the current API where the types are immediately available when pasting. Using the XFixes extension it is possible to listen for when the selection changes to request the updated TARGETS. Would it be fine to add a dependency on the XFixes extension for this purpose?

To avoid XFixes, it would be possible to poll to see where the selection changes. Alternatively the API could be adjusted so that users do not know the available types when issuing the paste request (although this would likely be annoying).

I have not currently added support for the MULITPLE target. It is not supported by xclip and I'm not confident I understand how it works without a reference implementation. Is it desired to support this? For pasting multiple types, I currently have implemented a queue system. I think it is fine to ignore it as well behaving clients should not request it since support is not advertised.

Also when the program ends and it owned the clipboard, it is not possible to paste. I think it is possible to send the data to a clipboard manager when closing. Is support for this desired?

Unfortunately the X11 implementation is already quite long and complex. A lot of this is due to support for the INCR mechanism and because X11 is really quite annoying and verbose to deal with. Any advice on simplifying it would be welcome. Thanks for your time looking into this.

[kchibisov]

X11 requires an event to get the possible TARGETS for pasting such as STRING, text/html, etc. The result is delivered as a separate event some time later. This makes it impossible to integrate with the current API where the types are immediately available when pasting. Using the XFixes extension it is possible to listen for when the selection changes to request the updated TARGETS. Would it be fine to add a dependency on the XFixes extension for this purpose?

Isn't this is the same as Wayland here? But besides, I think xfixes is available in a lot of places so maybe fine.

[0HyperCube]

Isn't this is the same as Wayland here?

I don't think so? The code in this PR does something like:

let offer = seat.data_device()?.data().selection_offer()?;
offer.with_mime_types(|types| {
    types.iter().map(|mime| MimeType::parse(mime.clone())).collect()
});

Which appears inspects the mime types synchronously.

But besides, I think xfixes is available in a lot of places so maybe fine.

Sounds good; thanks for the input @kchibisov.

[ogoffart]

My concerns with this design are still

1. no support for the primary (selection) clipboard on Unix.
2. the fact that the DataTransferReceived is delivered to all window is awkward.

[timon-schelling]

1. no support for the primary (selection) clipboard on Unix.

This is intentional (also see PR description) focus for this PR is just what is supported everywhere.

2. the fact that the DataTransferReceived is delivered to all window is awkward.

This is no longer the case for all backends. I was told in matrix that just sending to the focused window would be fine.