vtimofei
/
smithay
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

data_device: module-level docs

This commit is contained in:
Victor Berger 2018-11-21 23:55:06 +01:00
parent 41f1b37834
commit cc80233318
1 changed files with 35 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
src/wayland/data_device/mod.rs
View File

@ -1,3 +1,29 @@
//! Utilities for manipulating the data devices
//!
//! The data device is wayland's abstraction to represent both selection (copy/paste) and
//! drag'n'drop actions. This module provides logic to handle this part of the protocol.
//! Selection and drag'n'drop are per-seat notions.
//!
//! This module provides 2 main freestanding functions:
//!
//! - `init_data_device`: this function must be called during the compositor startup to initialize
//! the data device logic
//! - `set_data_device_focus`: this function sets the data device focus for a given seat; you'd
//! typically call it whenever the keyboard focus changes, to follow it (for example in the focus
//! hook of your keyboards)
//!
//! Using these two functions is enough for your clients to be able to interact with each other using
//! the data devices.
//!
//! The module also provides additionnal mechanisms allowing your compositor to see and interact with
//! the contents of the data device:
//!
//! - You can provide a callback closure to `init_data_device` to peek into the the actions of your clients
//! - the freestanding function `set_data_device_selection` allows you to set the contents of the selection
//! for your clients
//! - the freestanding function `start_dnd` allows you to initiate a drag'n'drop event from the compositor
//! itself and receive interactions of clients with it via an other dedicated callback.
use std::os::unix::io::RawFd;
use std::sync::{Arc, Mutex};
@ -186,7 +212,13 @@ impl SeatData {
/// Initialize the data device global
///
/// You need to provide a `(DndAction, DndAction) -> DndAction` closure that will arbitrate
/// You can provide a callback to peek into the actions of your clients over the data devices
/// (allowing you to retrieve the current selection buffer, or intercept DnD data). See the
/// `DataDeviceEvent` type for details about what notifications you can receive. Note that this
/// closure will not receive notifications about dnd actions the compositor initiated, see
/// `start_dnd` for details about that.
///
/// You also need to provide a `(DndAction, DndAction) -> DndAction` closure that will arbitrate
/// the choice of action resulting from a drag'n'drop session. Its first argument is the set of
/// available actions (which is the intersection of the actions supported by the source and targets)
/// and the second argument is the preferred action reported by the target. If no action should be
@ -254,7 +286,8 @@ pub fn set_data_device_selection(seat: &Seat, mime_types: Vec<String>) {
/// Start a drag'n'drop from a ressource controlled by the compositor
///
/// You'll receive events generated by the interaction of clients with your
/// drag'n'drop in the provided callback.
/// drag'n'drop in the provided callback. See `SeverDndEvent` for details about
/// which events can be generated and what response is expected from you to them.
pub fn start_dnd<C>(seat: &Seat, serial: u32, metadata: SourceMetadata, callback: C)
where
C: FnMut(ServerDndEvent) + Send + 'static,