Warning, /frameworks/kguiaddons/src/systemclipboard/wlr-data-control-unstable-v1.xml is written in an unsupported language. File is not indexed.

0001 <?xml version="1.0" encoding="UTF-8"?>
0002 <protocol name="wlr_data_control_unstable_v1">
0003   <copyright>
0004     Copyright © 2018 Simon Ser
0005     Copyright © 2019 Ivan Molodetskikh
0006 
0007     Permission to use, copy, modify, distribute, and sell this
0008     software and its documentation for any purpose is hereby granted
0009     without fee, provided that the above copyright notice appear in
0010     all copies and that both that copyright notice and this permission
0011     notice appear in supporting documentation, and that the name of
0012     the copyright holders not be used in advertising or publicity
0013     pertaining to distribution of the software without specific,
0014     written prior permission.  The copyright holders make no
0015     representations about the suitability of this software for any
0016     purpose.  It is provided "as is" without express or implied
0017     warranty.
0018 
0019     THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
0020     SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
0021     FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
0022     SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
0023     WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
0024     AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
0025     ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
0026     THIS SOFTWARE.
0027   </copyright>
0028 
0029   <description summary="control data devices">
0030     This protocol allows a privileged client to control data devices. In
0031     particular, the client will be able to manage the current selection and take
0032     the role of a clipboard manager.
0033 
0034     Warning! The protocol described in this file is experimental and
0035     backward incompatible changes may be made. Backward compatible changes
0036     may be added together with the corresponding interface version bump.
0037     Backward incompatible changes are done by bumping the version number in
0038     the protocol and interface names and resetting the interface version.
0039     Once the protocol is to be declared stable, the 'z' prefix and the
0040     version number in the protocol and interface names are removed and the
0041     interface version number is reset.
0042   </description>
0043 
0044   <interface name="zwlr_data_control_manager_v1" version="2">
0045     <description summary="manager to control data devices">
0046       This interface is a manager that allows creating per-seat data device
0047       controls.
0048     </description>
0049 
0050     <request name="create_data_source">
0051       <description summary="create a new data source">
0052         Create a new data source.
0053       </description>
0054       <arg name="id" type="new_id" interface="zwlr_data_control_source_v1"
0055         summary="data source to create"/>
0056     </request>
0057 
0058     <request name="get_data_device">
0059       <description summary="get a data device for a seat">
0060         Create a data device that can be used to manage a seat's selection.
0061       </description>
0062       <arg name="id" type="new_id" interface="zwlr_data_control_device_v1"/>
0063       <arg name="seat" type="object" interface="wl_seat"/>
0064     </request>
0065 
0066     <request name="destroy" type="destructor">
0067       <description summary="destroy the manager">
0068         All objects created by the manager will still remain valid, until their
0069         appropriate destroy request has been called.
0070       </description>
0071     </request>
0072   </interface>
0073 
0074   <interface name="zwlr_data_control_device_v1" version="2">
0075     <description summary="manage a data device for a seat">
0076       This interface allows a client to manage a seat's selection.
0077 
0078       When the seat is destroyed, this object becomes inert.
0079     </description>
0080 
0081     <request name="set_selection">
0082       <description summary="copy data to the selection">
0083         This request asks the compositor to set the selection to the data from
0084         the source on behalf of the client.
0085 
0086         The given source may not be used in any further set_selection or
0087         set_primary_selection requests. Attempting to use a previously used
0088         source is a protocol error.
0089 
0090         To unset the selection, set the source to NULL.
0091       </description>
0092       <arg name="source" type="object" interface="zwlr_data_control_source_v1"
0093         allow-null="true"/>
0094     </request>
0095 
0096     <request name="destroy" type="destructor">
0097       <description summary="destroy this data device">
0098         Destroys the data device object.
0099       </description>
0100     </request>
0101 
0102     <event name="data_offer">
0103       <description summary="introduce a new wlr_data_control_offer">
0104         The data_offer event introduces a new wlr_data_control_offer object,
0105         which will subsequently be used in either the
0106         wlr_data_control_device.selection event (for the regular clipboard
0107         selections) or the wlr_data_control_device.primary_selection event (for
0108         the primary clipboard selections). Immediately following the
0109         wlr_data_control_device.data_offer event, the new data_offer object
0110         will send out wlr_data_control_offer.offer events to describe the MIME
0111         types it offers.
0112       </description>
0113       <arg name="id" type="new_id" interface="zwlr_data_control_offer_v1"/>
0114     </event>
0115 
0116     <event name="selection">
0117       <description summary="advertise new selection">
0118         The selection event is sent out to notify the client of a new
0119         wlr_data_control_offer for the selection for this device. The
0120         wlr_data_control_device.data_offer and the wlr_data_control_offer.offer
0121         events are sent out immediately before this event to introduce the data
0122         offer object. The selection event is sent to a client when a new
0123         selection is set. The wlr_data_control_offer is valid until a new
0124         wlr_data_control_offer or NULL is received. The client must destroy the
0125         previous selection wlr_data_control_offer, if any, upon receiving this
0126         event.
0127 
0128         The first selection event is sent upon binding the
0129         wlr_data_control_device object.
0130       </description>
0131       <arg name="id" type="object" interface="zwlr_data_control_offer_v1"
0132         allow-null="true"/>
0133     </event>
0134 
0135     <event name="finished">
0136       <description summary="this data control is no longer valid">
0137         This data control object is no longer valid and should be destroyed by
0138         the client.
0139       </description>
0140     </event>
0141 
0142     <!-- Version 2 additions -->
0143 
0144     <event name="primary_selection" since="2">
0145       <description summary="advertise new primary selection">
0146         The primary_selection event is sent out to notify the client of a new
0147         wlr_data_control_offer for the primary selection for this device. The
0148         wlr_data_control_device.data_offer and the wlr_data_control_offer.offer
0149         events are sent out immediately before this event to introduce the data
0150         offer object. The primary_selection event is sent to a client when a
0151         new primary selection is set. The wlr_data_control_offer is valid until
0152         a new wlr_data_control_offer or NULL is received. The client must
0153         destroy the previous primary selection wlr_data_control_offer, if any,
0154         upon receiving this event.
0155 
0156         If the compositor supports primary selection, the first
0157         primary_selection event is sent upon binding the
0158         wlr_data_control_device object.
0159       </description>
0160       <arg name="id" type="object" interface="zwlr_data_control_offer_v1"
0161         allow-null="true"/>
0162     </event>
0163 
0164     <request name="set_primary_selection" since="2">
0165       <description summary="copy data to the primary selection">
0166         This request asks the compositor to set the primary selection to the
0167         data from the source on behalf of the client.
0168 
0169         The given source may not be used in any further set_selection or
0170         set_primary_selection requests. Attempting to use a previously used
0171         source is a protocol error.
0172 
0173         To unset the primary selection, set the source to NULL.
0174 
0175         The compositor will ignore this request if it does not support primary
0176         selection.
0177       </description>
0178       <arg name="source" type="object" interface="zwlr_data_control_source_v1"
0179         allow-null="true"/>
0180     </request>
0181 
0182     <enum name="error" since="2">
0183       <entry name="used_source" value="1"
0184         summary="source given to set_selection or set_primary_selection was already used before"/>
0185     </enum>
0186   </interface>
0187 
0188   <interface name="zwlr_data_control_source_v1" version="1">
0189     <description summary="offer to transfer data">
0190       The wlr_data_control_source object is the source side of a
0191       wlr_data_control_offer. It is created by the source client in a data
0192       transfer and provides a way to describe the offered data and a way to
0193       respond to requests to transfer the data.
0194     </description>
0195 
0196     <enum name="error">
0197       <entry name="invalid_offer" value="1"
0198         summary="offer sent after wlr_data_control_device.set_selection"/>
0199     </enum>
0200 
0201     <request name="offer">
0202       <description summary="add an offered MIME type">
0203         This request adds a MIME type to the set of MIME types advertised to
0204         targets. Can be called several times to offer multiple types.
0205 
0206         Calling this after wlr_data_control_device.set_selection is a protocol
0207         error.
0208       </description>
0209       <arg name="mime_type" type="string"
0210         summary="MIME type offered by the data source"/>
0211     </request>
0212 
0213     <request name="destroy" type="destructor">
0214       <description summary="destroy this source">
0215         Destroys the data source object.
0216       </description>
0217     </request>
0218 
0219     <event name="send">
0220       <description summary="send the data">
0221         Request for data from the client. Send the data as the specified MIME
0222         type over the passed file descriptor, then close it.
0223       </description>
0224       <arg name="mime_type" type="string" summary="MIME type for the data"/>
0225       <arg name="fd" type="fd" summary="file descriptor for the data"/>
0226     </event>
0227 
0228     <event name="cancelled">
0229       <description summary="selection was cancelled">
0230         This data source is no longer valid. The data source has been replaced
0231         by another data source.
0232 
0233         The client should clean up and destroy this data source.
0234       </description>
0235     </event>
0236   </interface>
0237 
0238   <interface name="zwlr_data_control_offer_v1" version="1">
0239     <description summary="offer to transfer data">
0240       A wlr_data_control_offer represents a piece of data offered for transfer
0241       by another client (the source client). The offer describes the different
0242       MIME types that the data can be converted to and provides the mechanism
0243       for transferring the data directly from the source client.
0244     </description>
0245 
0246     <request name="receive">
0247       <description summary="request that the data is transferred">
0248         To transfer the offered data, the client issues this request and
0249         indicates the MIME type it wants to receive. The transfer happens
0250         through the passed file descriptor (typically created with the pipe
0251         system call). The source client writes the data in the MIME type
0252         representation requested and then closes the file descriptor.
0253 
0254         The receiving client reads from the read end of the pipe until EOF and
0255         then closes its end, at which point the transfer is complete.
0256 
0257         This request may happen multiple times for different MIME types.
0258       </description>
0259       <arg name="mime_type" type="string"
0260         summary="MIME type desired by receiver"/>
0261       <arg name="fd" type="fd" summary="file descriptor for data transfer"/>
0262     </request>
0263 
0264     <request name="destroy" type="destructor">
0265       <description summary="destroy this offer">
0266         Destroys the data offer object.
0267       </description>
0268     </request>
0269 
0270     <event name="offer">
0271       <description summary="advertise offered MIME type">
0272         Sent immediately after creating the wlr_data_control_offer object.
0273         One event per offered MIME type.
0274       </description>
0275       <arg name="mime_type" type="string" summary="offered MIME type"/>
0276     </event>
0277   </interface>
0278 </protocol>