.TH "wayland::data_source_t" 3 "Wed May 3 2023" "Version 1.0.0" "Wayland++" \" -*- nroff -*- .ad l .nh .SH NAME wayland::data_source_t \- offer to transfer data .SH SYNOPSIS .br .PP .PP \fC#include \fP .PP Inherits \fBwayland::proxy_t\fP\&. .SS "Public Types" .in +1c .ti -1c .RI "enum class \fBwrapper_type\fP { \fBstandard\fP, \fBdisplay\fP, \fBforeign\fP, \fBproxy_wrapper\fP }" .br .in -1c .SS "Public Member Functions" .in +1c .ti -1c .RI "void \fBoffer\fP (std::string const &mime_type)" .br .RI "add an offered mime type " .ti -1c .RI "void \fBset_actions\fP (\fBdata_device_manager_dnd_action\fP const &dnd_actions)" .br .RI "set the available drag-and-drop actions " .ti -1c .RI "bool \fBcan_set_actions\fP () const" .br .RI "Check whether the \fBset_actions\fP function is available with the currently bound version of the protocol\&. " .ti -1c .RI "std::function< void(std::string)> & \fBon_target\fP ()" .br .RI "a target accepts an offered mime type " .ti -1c .RI "std::function< void(std::string, int)> & \fBon_send\fP ()" .br .RI "send the data " .ti -1c .RI "std::function< void()> & \fBon_cancelled\fP ()" .br .RI "selection was cancelled " .ti -1c .RI "std::function< void()> & \fBon_dnd_drop_performed\fP ()" .br .RI "the drag-and-drop operation physically finished " .ti -1c .RI "std::function< void()> & \fBon_dnd_finished\fP ()" .br .RI "the drag-and-drop operation concluded " .ti -1c .RI "std::function< void(\fBdata_device_manager_dnd_action\fP)> & \fBon_action\fP ()" .br .RI "notify the selected action " .ti -1c .RI "uint32_t \fBget_id\fP () const" .br .RI "Get the id of a proxy object\&. " .ti -1c .RI "std::string \fBget_class\fP () const" .br .RI "Get the interface name (class) of a proxy object\&. " .ti -1c .RI "uint32_t \fBget_version\fP () const" .br .RI "Get the protocol object version of a proxy object\&. " .ti -1c .RI "\fBwrapper_type\fP \fBget_wrapper_type\fP () const" .br .RI "Get the type of a proxy object\&. " .ti -1c .RI "void \fBset_queue\fP (\fBevent_queue_t\fP queue)" .br .RI "Assign a proxy to an event queue\&. " .ti -1c .RI "wl_proxy * \fBc_ptr\fP () const" .br .RI "Get a pointer to the underlying C struct\&. " .ti -1c .RI "bool \fBproxy_has_object\fP () const" .br .RI "Check whether this wrapper actually wraps an object\&. " .ti -1c .RI "\fBoperator bool\fP () const" .br .RI "Check whether this wrapper actually wraps an object\&. " .ti -1c .RI "bool \fBoperator==\fP (const \fBproxy_t\fP &right) const" .br .RI "Check whether two wrappers refer to the same object\&. " .ti -1c .RI "bool \fBoperator!=\fP (const \fBproxy_t\fP &right) const" .br .RI "Check whether two wrappers refer to different objects\&. " .ti -1c .RI "void \fBproxy_release\fP ()" .br .RI "Release the wrapped object (if any), making this an empty wrapper\&. " .in -1c .SS "Static Public Attributes" .in +1c .ti -1c .RI "static constexpr std::uint32_t \fBoffer_since_version\fP = 1" .br .RI "Minimum protocol version required for the \fBoffer\fP function\&. " .ti -1c .RI "static constexpr std::uint32_t \fBset_actions_since_version\fP = 3" .br .RI "Minimum protocol version required for the \fBset_actions\fP function\&. " .in -1c .SH "Detailed Description" .PP offer to transfer data The wl_data_source object is the source side of a wl_data_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\&. .PP Definition at line \fB1001\fP of file \fBwayland\-client\-protocol\&.hpp\fP\&. .SH "Member Enumeration Documentation" .PP .SS "enum class \fBwayland::proxy_t::wrapper_type\fP\fC [strong]\fP, \fC [inherited]\fP" Underlying wl_proxy type and properties of a \fBproxy_t\fP that affect construction, destruction, and event handling .PP \fBEnumerator\fP .in +1c .TP \fB\fIstandard \fP\fP C pointer is a standard type compatible with wl_proxy*\&. Events are dispatched and it is destructed when the \fBproxy_t\fP is destructed\&. User data is set\&. .TP \fB\fIdisplay \fP\fP C pointer is a wl_display*\&. No events are dispatched, wl_display_disconnect is called when the \fBproxy_t\fP is destructed\&. User data is set\&. .TP \fB\fIforeign \fP\fP C pointer is a standard type compatible with wl_proxy*, but another library owns it and it should not be touched in a way that could affect the operation of the other library\&. No events are dispatched, wl_proxy_destroy is not called when the \fBproxy_t\fP is destructed, user data is not touched\&. Consequently, there is no reference counting for the \fBproxy_t\fP\&. Lifetime of such wrappers should preferably be short to minimize the chance that the owning library decides to destroy the wl_proxy\&. .TP \fB\fIproxy_wrapper \fP\fP C pointer is a wl_proxy* that was constructed with wl_proxy_create_wrapper\&. No events are dispatched, wl_proxy_wrapper_destroy is called when the \fBproxy_t\fP is destroyed\&. Reference counting is active\&. A reference to the \fBproxy_t\fP creating this proxy wrapper is held to extend its lifetime until after the proxy wrapper is destroyed\&. .PP Definition at line \fB115\fP of file \fBwayland\-client\&.hpp\fP\&. .SH "Member Function Documentation" .PP .SS "wl_proxy * wayland::proxy_t::c_ptr () const\fC [inherited]\fP" .PP Get a pointer to the underlying C struct\&. .PP \fBReturns\fP .RS 4 The underlying wl_proxy wrapped by this \fBproxy_t\fP if it exists, otherwise an exception is thrown .RE .PP .SS "bool data_source_t::can_set_actions () const" .PP Check whether the \fBset_actions\fP function is available with the currently bound version of the protocol\&. .PP Definition at line \fB2158\fP of file \fBwayland\-client\-protocol\&.cpp\fP\&. .SS "std::string wayland::proxy_t::get_class () const\fC [inherited]\fP" .PP Get the interface name (class) of a proxy object\&. .PP \fBReturns\fP .RS 4 The interface name of the object associated with the proxy .RE .PP .SS "uint32_t wayland::proxy_t::get_id () const\fC [inherited]\fP" .PP Get the id of a proxy object\&. .PP \fBReturns\fP .RS 4 The id the object associated with the proxy .RE .PP .SS "uint32_t wayland::proxy_t::get_version () const\fC [inherited]\fP" .PP Get the protocol object version of a proxy object\&. Gets the protocol object version of a proxy object, or 0 if the proxy was created with unversioned API\&. .PP A returned value of 0 means that no version information is available, so the caller must make safe assumptions about the object's real version\&. .PP \fBdisplay_t\fP will always return version 0\&. .PP \fBReturns\fP .RS 4 The protocol object version of the proxy or 0 .RE .PP .SS "\fBwrapper_type\fP wayland::proxy_t::get_wrapper_type () const\fC [inline]\fP, \fC [inherited]\fP" .PP Get the type of a proxy object\&. .PP Definition at line \fB301\fP of file \fBwayland\-client\&.hpp\fP\&. .SS "void data_source_t::offer (std::string const & mime_type)" .PP add an offered mime type .PP \fBParameters\fP .RS 4 \fImime_type\fP mime type offered by the data source .RE .PP This request adds a mime type to the set of mime types advertised to targets\&. Can be called several times to offer multiple types\&. .PP Definition at line \fB2147\fP of file \fBwayland\-client\-protocol\&.cpp\fP\&. .SS "std::function< void(\fBdata_device_manager_dnd_action\fP)> & data_source_t::on_action ()" .PP notify the selected action .PP \fBParameters\fP .RS 4 \fIdnd_action\fP action selected by the compositor .RE .PP This event indicates the action selected by the compositor after matching the source/destination side actions\&. Only one action (or none) will be offered here\&. .PP This event can be emitted multiple times during the drag-and-drop operation, mainly in response to destination side changes through wl_data_offer\&.set_actions, and as the data device enters/leaves surfaces\&. .PP It is only possible to receive this event after wl_data_source\&.dnd_drop_performed if the drag-and-drop operation ended in an 'ask' action, in which case the final wl_data_source\&.action event will happen immediately before wl_data_source\&.dnd_finished\&. .PP Compositors may also change the selected action on the fly, mainly in response to keyboard modifier changes during the drag-and-drop operation\&. .PP The most recent action received is always the valid one\&. The chosen action may change alongside negotiation (e\&.g\&. an 'ask' action can turn into a 'move' operation), so the effects of the final action must always be applied in wl_data_offer\&.dnd_finished\&. .PP Clients can trigger cursor surface changes from this point, so they reflect the current action\&. .PP Definition at line \fB2189\fP of file \fBwayland\-client\-protocol\&.cpp\fP\&. .SS "std::function< void()> & data_source_t::on_cancelled ()" .PP selection was cancelled This data source is no longer valid\&. There are several reasons why this could happen: .PP .IP "\(bu" 2 The data source has been replaced by another data source\&. .IP "\(bu" 2 The drag-and-drop operation was performed, but the drop destination did not accept any of the mime types offered through wl_data_source\&.target\&. .IP "\(bu" 2 The drag-and-drop operation was performed, but the drop destination did not select any of the actions present in the mask offered through wl_data_source\&.action\&. .IP "\(bu" 2 The drag-and-drop operation was performed but didn't happen over a surface\&. .IP "\(bu" 2 The compositor cancelled the drag-and-drop operation (e\&.g\&. compositor dependent timeouts to avoid stale drag-and-drop transfers)\&. .PP .PP The client should clean up and destroy this data source\&. .PP For objects of version 2 or older, wl_data_source\&.cancelled will only be emitted if the data source was replaced by another data source\&. .PP Definition at line \fB2174\fP of file \fBwayland\-client\-protocol\&.cpp\fP\&. .SS "std::function< void()> & data_source_t::on_dnd_drop_performed ()" .PP the drag-and-drop operation physically finished The user performed the drop action\&. This event does not indicate acceptance, wl_data_source\&.cancelled may still be emitted afterwards if the drop destination does not accept any mime type\&. .PP However, this event might however not be received if the compositor cancelled the drag-and-drop operation before this event could happen\&. .PP Note that the data_source may still be used in the future and should not be destroyed here\&. .PP Definition at line \fB2179\fP of file \fBwayland\-client\-protocol\&.cpp\fP\&. .SS "std::function< void()> & data_source_t::on_dnd_finished ()" .PP the drag-and-drop operation concluded The drop destination finished interoperating with this data source, so the client is now free to destroy this data source and free all associated data\&. .PP If the action used to perform the operation was 'move', the source can now delete the transferred data\&. .PP Definition at line \fB2184\fP of file \fBwayland\-client\-protocol\&.cpp\fP\&. .SS "std::function< void(std::string, int)> & data_source_t::on_send ()" .PP send the data .PP \fBParameters\fP .RS 4 \fImime_type\fP mime type for the data .br \fIfd\fP file descriptor for the data .RE .PP Request for data from the client\&. Send the data as the specified mime type over the passed file descriptor, then close it\&. .PP Definition at line \fB2169\fP of file \fBwayland\-client\-protocol\&.cpp\fP\&. .SS "std::function< void(std::string)> & data_source_t::on_target ()" .PP a target accepts an offered mime type .PP \fBParameters\fP .RS 4 \fImime_type\fP mime type accepted by the target .RE .PP Sent when a target accepts pointer_focus or motion events\&. If a target does not accept any of the offered types, type is NULL\&. .PP Used for feedback during drag-and-drop\&. .PP Definition at line \fB2164\fP of file \fBwayland\-client\-protocol\&.cpp\fP\&. .SS "wayland::proxy_t::operator bool () const\fC [inherited]\fP" .PP Check whether this wrapper actually wraps an object\&. .PP \fBReturns\fP .RS 4 true if there is an underlying object, false if this wrapper is empty .RE .PP .SS "bool wayland::proxy_t::operator!= (const \fBproxy_t\fP & right) const\fC [inherited]\fP" .PP Check whether two wrappers refer to different objects\&. .SS "bool wayland::proxy_t::operator== (const \fBproxy_t\fP & right) const\fC [inherited]\fP" .PP Check whether two wrappers refer to the same object\&. .SS "bool wayland::proxy_t::proxy_has_object () const\fC [inherited]\fP" .PP Check whether this wrapper actually wraps an object\&. .PP \fBReturns\fP .RS 4 true if there is an underlying object, false if this wrapper is empty .RE .PP .SS "void wayland::proxy_t::proxy_release ()\fC [inherited]\fP" .PP Release the wrapped object (if any), making this an empty wrapper\&. Note that \fBdisplay_t\fP instances cannot be released this way\&. Attempts to do so are ignored\&. .PP \fBExamples\fP .in +1c \fBforeign_display\&.cpp\fP\&. .SS "void data_source_t::set_actions (\fBdata_device_manager_dnd_action\fP const & dnd_actions)" .PP set the available drag-and-drop actions .PP \fBParameters\fP .RS 4 \fIdnd_actions\fP actions supported by the data source .RE .PP Sets the actions that the source side client supports for this operation\&. This request may trigger wl_data_source\&.action and wl_data_offer\&.action events if the compositor needs to change the selected action\&. .PP The dnd_actions argument must contain only values expressed in the wl_data_device_manager\&.dnd_actions enum, otherwise it will result in a protocol error\&. .PP This request must be made once only, and can only be made on sources used in drag-and-drop, so it must be performed before wl_data_device\&.start_drag\&. Attempting to use the source other than for drag-and-drop will raise a protocol error\&. .PP Definition at line \fB2153\fP of file \fBwayland\-client\-protocol\&.cpp\fP\&. .SS "void wayland::proxy_t::set_queue (\fBevent_queue_t\fP queue)\fC [inherited]\fP" .PP Assign a proxy to an event queue\&. .PP \fBParameters\fP .RS 4 \fIqueue\fP The event queue that will handle this proxy .RE .PP Assign proxy to event queue\&. Events coming from proxy will be queued in queue instead of the display's main queue\&. .PP See also: \fBdisplay_t::dispatch_queue()\fP\&. .PP \fBExamples\fP .in +1c \fBproxy_wrapper\&.cpp\fP\&. .SH "Member Data Documentation" .PP .SS "constexpr std::uint32_t wayland::data_source_t::offer_since_version = 1\fC [static]\fP, \fC [constexpr]\fP" .PP Minimum protocol version required for the \fBoffer\fP function\&. .PP Definition at line \fB1041\fP of file \fBwayland\-client\-protocol\&.hpp\fP\&. .SS "constexpr std::uint32_t wayland::data_source_t::set_actions_since_version = 3\fC [static]\fP, \fC [constexpr]\fP" .PP Minimum protocol version required for the \fBset_actions\fP function\&. .PP Definition at line \fB1065\fP of file \fBwayland\-client\-protocol\&.hpp\fP\&. .SH "Author" .PP Generated automatically by Doxygen for Wayland++ from the source code\&.