This repository has been archived by the owner on Nov 1, 2021. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 29
Add wlr-data-control-unstable-v1 #25
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,224 @@ | ||
<?xml version="1.0" encoding="UTF-8"?> | ||
<protocol name="wlr_data_control_unstable_v1"> | ||
<copyright> | ||
Copyright © 2018 Simon Ser | ||
|
||
Permission to use, copy, modify, distribute, and sell this | ||
software and its documentation for any purpose is hereby granted | ||
without fee, provided that the above copyright notice appear in | ||
all copies and that both that copyright notice and this permission | ||
notice appear in supporting documentation, and that the name of | ||
the copyright holders not be used in advertising or publicity | ||
pertaining to distribution of the software without specific, | ||
written prior permission. The copyright holders make no | ||
representations about the suitability of this software for any | ||
purpose. It is provided "as is" without express or implied | ||
warranty. | ||
|
||
THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS | ||
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND | ||
FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY | ||
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | ||
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN | ||
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, | ||
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF | ||
THIS SOFTWARE. | ||
</copyright> | ||
|
||
<description summary="control data devices"> | ||
This protocol allows a privileged client to control data devices. In | ||
particular, the client will be able to manage the current selection and take | ||
the role of a clipboard manager. | ||
|
||
Warning! The protocol described in this file is experimental and | ||
backward incompatible changes may be made. Backward compatible changes | ||
may be added together with the corresponding interface version bump. | ||
Backward incompatible changes are done by bumping the version number in | ||
the protocol and interface names and resetting the interface version. | ||
Once the protocol is to be declared stable, the 'z' prefix and the | ||
version number in the protocol and interface names are removed and the | ||
interface version number is reset. | ||
</description> | ||
|
||
<interface name="zwlr_data_control_manager_v1" version="1"> | ||
<description summary="manager to control data devices"> | ||
This interface is a manager that allows creating per-seat data device | ||
controls. | ||
</description> | ||
|
||
<request name="create_data_source"> | ||
<description summary="create a new data source"> | ||
Create a new data source. | ||
</description> | ||
<arg name="id" type="new_id" interface="zwlr_data_control_source_v1" | ||
summary="data source to create"/> | ||
</request> | ||
|
||
<request name="get_data_device"> | ||
<description summary="get a data device for a seat"> | ||
Create a data device that can be used to manage a seat's selection. | ||
</description> | ||
<arg name="id" type="new_id" interface="zwlr_data_control_device_v1"/> | ||
<arg name="seat" type="object" interface="wl_seat"/> | ||
</request> | ||
|
||
<request name="destroy" type="destructor"> | ||
<description summary="destroy the manager"> | ||
All objects created by the manager will still remain valid, until their | ||
appropriate destroy request has been called. | ||
</description> | ||
</request> | ||
</interface> | ||
|
||
<interface name="zwlr_data_control_device_v1" version="1"> | ||
<description summary="manage a data device for a seat"> | ||
This interface allows a client to manage a seat's selection. | ||
|
||
When the seat is destroyed, this object becomes inert. | ||
</description> | ||
|
||
<request name="set_selection"> | ||
<description summary="copy data to the selection"> | ||
All objects created by the device will still remain valid, until their | ||
appropriate destroy request has been called. | ||
</description> | ||
<arg name="source" type="object" interface="zwlr_data_control_source_v1" | ||
allow-null="true"/> | ||
</request> | ||
|
||
<request name="destroy" type="destructor"> | ||
<description summary="destroy this data device"> | ||
Destroys the data device object. | ||
</description> | ||
</request> | ||
|
||
<event name="data_offer"> | ||
<description summary="introduce a new wlr_data_control_offer"> | ||
The data_offer event introduces a new wlr_data_control_offer object, | ||
which will subsequently be used in the wlr_data_control_device.selection | ||
event. Immediately following the wlr_data_control_device.data_offer | ||
event, the new data_offer object will send out | ||
wlr_data_control_offer.offer events to describe the MIME types it | ||
offers. | ||
|
||
This event replaces the previous data offer, which should be destroyed | ||
by the client. | ||
</description> | ||
<arg name="id" type="new_id" interface="zwlr_data_control_offer_v1"/> | ||
</event> | ||
|
||
<event name="selection"> | ||
<description summary="introduce a new wlr_data_control_offer"> | ||
The selection event is sent out to notify the client of a new | ||
wlr_data_control_offer for the selection for this device. The | ||
wlr_data_control_device.data_offer and the wlr_data_control_offer.offer | ||
events are sent out immediately before this event to introduce the data | ||
offer object. The selection event is sent to a client when a new | ||
selection is set. The wlr_data_control_offer is valid until a new | ||
wlr_data_control_offer or NULL is received. The client must destroy the | ||
previous selection wlr_data_control_offer, if any, upon receiving this | ||
event. | ||
</description> | ||
<arg name="id" type="object" interface="zwlr_data_control_offer_v1" | ||
allow-null="true"/> | ||
</event> | ||
|
||
<event name="finished"> | ||
<description summary="this data control is no longer valid"> | ||
This data control object is no longer valid and should be destroyed by | ||
the client. | ||
</description> | ||
</event> | ||
</interface> | ||
|
||
<interface name="zwlr_data_control_source_v1" version="1"> | ||
<description summary="offer to transfer data"> | ||
The wlr_data_control_source object is the source side of a | ||
wlr_data_control_offer. It is created by the source client in a data | ||
transfer and provides a way to describe the offered data and a way to | ||
respond to requests to transfer the data. | ||
</description> | ||
|
||
<enum name="error"> | ||
<entry name="invalid_offer" value="1" | ||
summary="offer sent after wlr_data_control_device.set_selection"/> | ||
</enum> | ||
|
||
<request name="offer"> | ||
<description summary="add an offered MIME type"> | ||
This request adds a MIME type to the set of MIME types advertised to | ||
targets. Can be called several times to offer multiple types. | ||
|
||
Calling this after wlr_data_control_device.set_selection is a protocol | ||
error. | ||
</description> | ||
<arg name="mime_type" type="string" | ||
summary="MIME type offered by the data source"/> | ||
</request> | ||
|
||
<request name="destroy" type="destructor"> | ||
<description summary="destroy this source"> | ||
Destroys the data source object. | ||
</description> | ||
</request> | ||
|
||
<event name="send"> | ||
<description summary="send the data"> | ||
Request for data from the client. Send the data as the specified MIME | ||
type over the passed file descriptor, then close it. | ||
</description> | ||
<arg name="mime_type" type="string" summary="MIME type for the data"/> | ||
<arg name="fd" type="fd" summary="file descriptor for the data"/> | ||
</event> | ||
|
||
<event name="cancelled"> | ||
<description summary="selection was cancelled"> | ||
This data source is no longer valid. The data source has been replaced | ||
by another data source. | ||
|
||
The client should clean up and destroy this data source. | ||
</description> | ||
</event> | ||
</interface> | ||
|
||
<interface name="zwlr_data_control_offer_v1" version="1"> | ||
<description summary="offer to transfer data"> | ||
A wlr_data_control_offer represents a piece of data offered for transfer | ||
by another client (the source client). The offer describes the different | ||
MIME types that the data can be converted to and provides the mechanism | ||
for transferring the data directly from the source client. | ||
</description> | ||
|
||
<request name="receive"> | ||
<description summary="request that the data is transferred"> | ||
To transfer the offered data, the client issues this request and | ||
indicates the MIME type it wants to receive. The transfer happens | ||
through the passed file descriptor (typically created with the pipe | ||
system call). The source client writes the data in the MIME type | ||
representation requested and then closes the file descriptor. | ||
|
||
The receiving client reads from the read end of the pipe until EOF and | ||
then closes its end, at which point the transfer is complete. | ||
|
||
This request may happen multiple times for different MIME types. | ||
</description> | ||
<arg name="mime_type" type="string" | ||
summary="MIME type desired by receiver"/> | ||
<arg name="fd" type="fd" summary="file descriptor for data transfer"/> | ||
</request> | ||
|
||
<request name="destroy" type="destructor"> | ||
<description summary="destroy this offer"> | ||
Destroys the data offer object. | ||
</description> | ||
</request> | ||
|
||
<event name="offer"> | ||
<description summary="advertise offered MIME type"> | ||
Sent immediately after creating the wlr_data_control_offer object. | ||
One event per offered MIME type. | ||
</description> | ||
<arg name="mime_type" type="string" summary="offered MIME type"/> | ||
</event> | ||
</interface> | ||
</protocol> |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there a reason why every new clipboard protocol has to ship its own offer/source types? Why not reuse
wl_data_offer
/wl_data_source
?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It would be a maintenance burden and leads to questions regarding protocol object versions.
If it's all in a single protocol, you just have your different objects have the same interface version. If you're dealing with types defined by other protocols (including the core wayland protocol), who knows what version you're supposed to return?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
wl_buffer
is supposed to be used this way, which is why it's always on version 1wl_data_offer
/wl_data_source
v1 is exactly what you need wrt d'n'd stuffThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Objects in Wayland inherit the version of their parent object. You can't do anything about it, it's hardcoded in the Wayland design.
This means if you have
wlr_data_control_offer
v10, it will only be able to create v10 objects. You won't be able to create e.g.wl_data_offer
v1 objects.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
wl_buffer
is an exception that works only because it's frozen. It makes it impossible to ever add anything to its interface.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
wl_buffer is special. It's not a good example when bringing up wayland types.
That's not forwards compatible. What happens when someone bumps that to version 4 and adds something new?
Not to mention, you're now going to have clients that may need to deal with multiple versions of the same protocol object, which in itself seems extremely annoying.
It's just the nature of how wayland is designed. It's very boilerplatey.