Task-shaped answers. For a first program see getting-started.md; when something silently does nothing, troubleshooting.md.
- Avoiding the consent dialog on every run
- Pointer, buttons and scrolling
- Absolute positioning
- Picking the right device when several resume
- Keyboard: positions, not characters
- Typing text directly, on libei 1.6
- Touch
- Reading input instead of sending it
- Keeping a connection alive, and closing it
- Running your own EIS server
- Logging
libei.oeffis cannot do it. liboeffis wraps the portal handshake into one
call and exposes no options dict, so the two things that make an approval
persist — persist_mode on SelectDevices, and the restore_token that
comes back on Start — are unreachable through it. This is a limitation of
the C library, not of these bindings; upstream's own docs say liboeffis is
"intentionally kept simple, any more complex needs should be handled by an
application talking to DBus directly"
(source).
libei.portal is that: the same CreateSession → SelectDevices → Start →
ConnectToEIS sequence, driven directly over D-Bus (needs PyGObject —
pip install 'python-libei[portal]'), with those two as real parameters:
from libei import ei, portal
with portal.RemoteDesktopSession.negotiate(
devices=portal.DeviceType.POINTER,
persist_mode=portal.PersistMode.UNTIL_REVOKED,
restore_token=saved_token, # None on the first run
) as session:
save_somewhere(session.restore_token) # a fresh token every time -- save it
sender = ei.Sender.create_for_fd(session.eis_fd, name="my-app")
... # inject input for as long as the session is neededSave whatever comes back on every run, not just the first. The portal is free to hand back a different token each time, and a caller that keeps only the original would eventually present a stale one. (On GNOME the same token comes back on each restore — that is one portal's behaviour, not a guarantee.)
Passing restore_token without a persist_mode raises ValueError: the
portal answers such a request with no token at all, so storing what came back
would write None over the token you just spent.
Treat the token as a credential. Anyone holding it can reopen input injection on that desktop, so it belongs wherever you would keep a password. The decision to store it at all belongs to the application rather than to this library, which never writes it anywhere itself.
Three differences from Oeffis worth knowing:
- Blocking, not event-driven.
negotiate()runs its own nestedGLib.MainLoopper D-Bus round trip and returns only once connected, or raisesPortalVersionError/PortalDeniedError/PortalTimeoutError. - Bounded. Each round trip gets
timeoutseconds (60 by default — generous, sinceStartwaits on a user answering a dialog). Without it a portal that dies after accepting the call would wedge the calling thread forever, which is the one thingOeffis's pollable fd protects against. - Close it. The portal session lives in xdg-desktop-portal and outlives
the object unless
Session.Close()is called —Gio.bus_get_sync()hands back GLib's shared connection, so dropping the session tears nothing down, and a long-running process that negotiates repeatedly accumulates live sessions. Thewithblock above handles it; otherwise callsession.close().
Every burst of input is wrapped in start_emulating() … frame() …
stop_emulating(), and frame() is what actually commits the queued events.
# Move the pointer 10px right, 5px down
device.start_emulating().pointer_motion(10, 5).frame().stop_emulating()
# Left click (BTN_LEFT; codes are Linux input codes, from
# <linux/input-event-codes.h>)
BTN_LEFT = 0x110
device.start_emulating()
device.button(BTN_LEFT, True).frame()
device.button(BTN_LEFT, False).frame()
device.stop_emulating()
# Scroll: smooth (logical pixels) or discrete (one detent is 120)
device.start_emulating().scroll_delta(0, 20).frame().stop_emulating()
device.start_emulating().scroll_discrete(0, 120).frame().stop_emulating()scroll_stop() and scroll_cancel() exist too, for ending a kinetic scroll
gesture properly.
Needs the POINTER_ABSOLUTE capability, and coordinates must fall inside one
of device.regions:
device.start_emulating().pointer_motion_absolute(960, 540).frame().stop_emulating()Regions carry more than bounds. region.mapping_id groups the ones that map
to the same thing, device.region_at(x, y) finds which region a point falls
in, and region.convert_point(x, y) turns a desktop-wide point into one
relative to that region — returning None when it falls outside, which also
answers "is it in here?" in a single call. mapping_id and region_at()
need libei 1.1; convert_point() works on the libei 1.0.0 floor.
Pick by capability, not by arrival order. A seat can resume more than one
device — on GNOME you get both a relative virtual pointer and an absolute
shared virtual absolute pointer, and the relative one arrives first.
Reusing the quick start's "first DEVICE_RESUMED wins" loop hands you the
relative device, on which pointer_motion_absolute() does nothing at all: no
exception, no movement, just an internal libei warning (device is not an absolute pointer, visible only with logging on).
device = None
while device is None:
select.select([sender.fd], [], [], 5)
sender.dispatch()
for event in sender.events:
if event.event_type is ei.EventType.SEAT_ADDED:
event.seat.bind((
ei.DeviceCapability.POINTER_ABSOLUTE,
ei.DeviceCapability.BUTTON,
))
elif event.event_type is ei.EventType.DEVICE_RESUMED:
if ei.DeviceCapability.POINTER_ABSOLUTE in event.device.capabilities:
device = event.device # skip the relative siblingkeyboard_key() takes a Linux evdev keycode — a physical key position, not
a character. KEY_A = 30 means "the key where A sits on a US QWERTY board";
under Dvorak or AZERTY the compositor turns that same code into a different
character. There is no type("hello") here, so shifted characters mean
sending the modifier yourself:
KEY_LEFTSHIFT, KEY_A = 42, 30
device.start_emulating()
device.keyboard_key(KEY_LEFTSHIFT, True).frame()
device.keyboard_key(KEY_A, True).frame() # "A", not "a"
device.keyboard_key(KEY_A, False).frame()
device.keyboard_key(KEY_LEFTSHIFT, False).frame()
device.stop_emulating()To get this right for whatever layout the user actually has, read the keymap
the compositor handed you and resolve characters through it — with the
xkbcommon bindings, say, which this package does not depend on:
keymap = device.keymap # None unless the device has KEYBOARD
if keymap is not None:
assert keymap.keymap_type is ei.KeymapType.XKB # the only type so far
with keymap.fd as f: # a fresh dup() each read; closing it is yours
data = f.read(keymap.size)keymap.fd duplicates libei's descriptor and rewinds the copy for you. Left
to itself a dup() shares the original's file offset, which libei leaves at
the end — reading through it returned zero bytes and no error, which is
indistinguishable from an empty keymap.
Modifier state arrives as events rather than being queryable — watch for
EventType.KEYBOARD_MODIFIERS and read event.keyboard_xkb_modifiers, which
gives depressed, latched, locked and group. That is how you find out
the compositor thinks Caps Lock is on before you start injecting.
A device with the TEXT capability takes characters directly, and the
compositor works out which keys that means under the active layout:
device.start_emulating().text_utf8("héllo").frame().stop_emulating()
device.start_emulating().text_keysym(0x61, True).frame().stop_emulating()This is the one path here that types text rather than pressing positions. It
needs libei 1.6 on both sides and a seat that offers DeviceCapability.TEXT;
on anything older, text_utf8() raises LibraryNotFoundError, so keep the
keycode path as a fallback.
Touch uses its own short-lived object rather than the device directly:
touch = device.touch_new()
device.start_emulating()
touch.down(100, 200)
device.frame()
touch.motion(150, 250)
device.frame()
touch.up() # or touch.cancel(), if the gesture was aborted
device.frame()
device.stop_emulating()A cancelled touch still reaches the other side as a TOUCH_UP event; what
separates it from a normal release is event.touch_up_event.is_cancel. Both
sides need version 2 or later of the ei_touchscreen interface, and against
anything older cancel() is a noop.
Use ei.Receiver in place of ei.Sender — same connection dance, but events
carry input from the compositor:
receiver = ei.Receiver.create_for_fd(eis_fd, name="my-app")
receiver.dispatch()
for event in receiver.events:
if event.event_type is ei.EventType.POINTER_MOTION:
motion = event.pointer_event
print(motion.dx, motion.dy)Which getter goes with which event is fixed, and each checks the event's
type before reading, raising TypeError rather than handing back the
zero-filled result libei would give for a mismatch:
event_type |
Getter | You get |
|---|---|---|
KEYBOARD_KEY |
key_event |
KeyEvent(key, is_press) — a Linux KEY_* code |
KEYBOARD_MODIFIERS |
keyboard_xkb_modifiers |
XkbModifiersEvent(depressed, latched, locked, group), the only getter not named after the class it unwraps |
BUTTON_BUTTON |
button_event |
ButtonEvent(button, is_press) — a Linux BTN_* code |
POINTER_MOTION |
pointer_event |
PointerEvent(dx, dy) |
POINTER_MOTION_ABSOLUTE |
pointer_absolute_event |
PointerAbsoluteEvent(x, y), in the emitting device's Region space |
SCROLL_DELTA |
scroll_event |
ScrollEvent(dx, dy) — smooth, in logical pixels |
SCROLL_DISCRETE |
scroll_discrete_event |
ScrollDiscreteEvent(dx, dy) — detents, 120 to each |
SCROLL_STOP, SCROLL_CANCEL |
scroll_stop_event |
ScrollStopEvent(stop_x, stop_y) |
TOUCH_DOWN, TOUCH_MOTION |
touch_event |
TouchEvent(touchid, x, y) |
TOUCH_UP |
touch_up_event |
TouchUpEvent(touchid, is_cancel) |
TEXT_UTF8 |
text_utf8_event |
TextUtf8Event(text) — libei 1.6 |
TEXT_KEYSYM |
text_keysym_event |
TextKeysymEvent(keysym, is_press) — libei 1.6 |
PONG |
pong |
the Ping this answers — libei 1.4 |
DEVICE_START_EMULATING |
emulating_sequence |
the sequence number of that transaction |
The lifecycle events — CONNECT, DISCONNECT, SEAT_ADDED, SEAT_REMOVED,
DEVICE_ADDED, DEVICE_REMOVED, DEVICE_PAUSED, DEVICE_RESUMED, SYNC,
FRAME and DEVICE_STOP_EMULATING — have no getter: read them through
event_type, plus event.device or event.seat where they concern one.
Event types this package has never heard of do not raise: event_type returns
a plain int, because libei's own header says the enum "is not exhaustive".
To look at what is coming without consuming it, peek_event_type() reports
the next event's type and leaves it queued.
Do not keep an event past its loop iteration. Each event is released as
soon as the loop moves on, and using it afterwards raises RuntimeError.
Objects you pull off an event (event.device, event.seat) are safe to
keep — copy out event.pointer_event and friends rather than the event.
Check the connection is alive. A ping is a round trip that comes back as a
PONG event carrying the same object, so several can be in flight at once and
still be told apart:
ping = sender.new_ping()
ping.send()
# ... later, in the event loop:
# if event.event_type is ei.EventType.PONG and event.pong.id == ping.id:
# ...Ask for another device. If you closed one, or the ones the seat gave you
no longer cover what you need, seat.request_device((cap, ...)) asks for
another — a subset of what bind() requested. The server may answer with
different capabilities, or not at all; anything it does create arrives as a
DEVICE_ADDED event. Needs libei 1.6.
Shut down deliberately. sender.disconnect() tears the session down
through the event queue: seats and devices are removed as though the server
had done it, and DISCONNECT is the last event you get. The context is inert
afterwards but still needs releasing like any other object. Needs libei 1.4.
libei.eis is the compositor side of the protocol. Most people want it for
testing — it lets you drive the client code above without a real compositor
or a consent dialog:
import select
from libei import eis
server = eis.Eis.create_for_fd()
client_fd = server.add_client() # hand this fd to a client's ei.Sender/Receiver
while True:
select.select([server.fd], [], [])
server.dispatch() # events is empty until dispatch() reads the connection
for event in server.events:
if event.event_type is eis.EventType.CLIENT_CONNECT:
event.client.connect()
seat = event.client.new_seat("default")
seat.configure_capabilities((eis.DeviceCapability.POINTER,))
seat.add()
elif event.event_type is eis.EventType.SEAT_BIND:
device = event.seat.new_device()
device.configure(
name="my-pointer",
capabilities=(eis.DeviceCapability.POINTER,),
# A region is *described* rather than passed as a live
# eis.Region: configure() allocates, fills in and adds each
# one itself, so there is never a moment at which you hold
# one to set fields on. Omit it for a device whose space is
# unknown to you.
regions=(eis.ConfigureRegion(offset=(0, 0), size=(1920, 1080)),),
)
device.add()
device.resume() # until you resume it, the client may not sendtests/test_integration_socketpair.py is a complete, working version of both
halves — connect, negotiate, and round-trip a pointer motion, in one process
against the real library.
libei's and libeis's own diagnostics are routed into Python's logging — the
libei.ei and libei.eis loggers — rather than being written to stderr by the
C library. This is how you see the warnings that otherwise look like nothing
happening at all, device is not an absolute pointer among them:
import logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("libei").setLevel(logging.DEBUG)At DEBUG this is a full protocol trace (every object, message and signature,
both directions — a few hundred lines for a single connect and one pointer
motion), which makes it the first thing to reach for when a negotiation
stalls. WARNING gets you just libei's complaints.
There is no equivalent for liboeffis: it exposes no log-handler entry point to
hook, so no C-library diagnostics reach the libei.oeffis logger. That logger
carries only this package's own messages — a single DEBUG line when an oeffis
event of an unrecognised type arrives — never routed C diagnostics.