This is the interface description for the protocol to emulate virtual devices in a Wayland compositor (henceforce the Compositor).
This project is not an implementation. It's a discussion point for the required interfaces together with a basic implementation that can verify the concept and test clients or servers.
The basic goal is to provide functionality similar to xdotool in Wayland compositors. xdotool's requirements are out of scope for a wayland protocol. Wayland is a display server protocol, not a protocol to emulate input devices.
This is a dbus interface instead.
NOTE: THIS INTERFACE IS IN DEVELOPMENT AND SUBJECT TO CHANGE
This interface centers around the idea that each client has their own virtual device(s) separate from any other clients. The compositor creates these on-the-fly as the client registers on dbus.
These fake input events come from a different event stream than real input devices and can thus be enabled or disabled depending on the current context. For example, the Compositor may not allow fake events while lock screen is active.
One of the drawbacks of the XTest interface is that it provides no way to restrict the applications that can fake input events. Moving to a dbus-based interface allows identifying the client endpoint and thus the PID of the calling process. Going beyond this is an unsolved problem. Per-process permissions are not available with DBus existing tools.
A pre-shared key between the appliation and the compositor requires considerations in the API and provides minimal extra security - all clients and the compositor need to avoid keeping the key unencrypted in memory.
Configuration of any filtering is out of scope of this protocol. How dbus clients are matched with the whitelist is out of scope of this protocol.
The split into separate sub-interfaces allows clients to be restricted to a specific feature set in a discoverable manner.
Interfaces:
org.freedesktop.Woodotool.Manager
The manager interface is a singleton representing the compositor.
Methods:
GetKeyboard(String name) -> object
Service creates a new object implementing org.freedesktop.Woodotool.Keyboard interface for the requesting process.
MUST create at least one keyboard or throw an exception on EACCESS
MAY create multiple objects if called repeatedly
GetMouse(String name) -> object
Service creates a new object implementing org.freedesktop.Woodotool.Mouse interface for the requesting process.
MUST create at least one mouse device or throw an exception on EACCESS
MAY create multiple objects if called repeatedly
GetDesktop(String name) -> object
Service returns the singleton object implementing the org.freedesktop.Woodotool.Mouse interface. Only one object implementing this service exists.
org.freedesktop.Woodotool.Keyboard
Properties:
Name (String)
Methods
SetXKBKeymap(int fd, uint32 size) -> ()
fd: an memory-mapable file-descriptor to a libxkbcommon-compatible keymap.
Sets the keymap for this keyboard. This method must be called before any events are to be sent from the keyboard.
Press(uint32 keycode) -> ()
keycode: a keycode for the given layout
Emulate key press event for the key with the given keycode. If the key is already down, nothing happens.
Release(uint32 keycode) -> ()
keycode: a keycode for the given layout
Emulate key release event for the key with the given keycode. If the key is already up, nothing happens.
org.freedesktop.Woodotool.Mouse
Properties:
Name (String)
Methods
MoveRelative(int x, int y) -> ()
Moves the pointer by the given distance in logical pixels. Note that
in High-DPI screen a logical pixel may differ to a physical pixel.
MoveAbsolute(int x, int y) -> ()
Moves the pointer to the given location in logical pixels. Note that
in High-DPI screen a logical pixel may differ to a physical pixel.
Press(uint32 code) -> ()
Press the button with the given evdev code (e.g. BTN_LEFT)
Release(uint32 code) -> ()
Release the button with the given evdev code (e.g. BTN_LEFT)
org.freedesktop.Woodotool.Desktop
Signals
Edge(enum edge)
Signals that the pointer has hit an edge or corner. Valid arguments
are top
(0), bottom
(1), left
(2), right
(3) for edges and
top-left
(4), bottom-left
(5), top-right
(6) and
bottom-right
(7) for corners.
It is up to the Compositor to decide where the edge stops and the corner starts.
It is up to the Compositor to decide which corners are active. For the top-left trigger may only signal on the primary display.