handler.go RawHistoryFolder

1package neferclient
2
3// Handler receives the events [Conn.Dispatch] drains. Every method is called
4// on the goroutine that called Dispatch, never on the reader goroutine, so an
5// implementation may send requests and call [Conn.Bind], [Conn.Roundtrip],
6// [Conn.WatchFD] and [Conn.UnwatchFD] from inside any method. It must not call
7// Dispatch.
8type Handler interface {
9	// OutputAdded reports an output that became complete after [Connect]
10	// returned: the compositor sent its first wl_output.done. Outputs that
11	// existed during Connect are not reported; read them with [Conn.Outputs].
12	// Later property changes are applied to [Conn.Outputs] silently. out is
13	// valid only during the call.
14	OutputAdded(out *Output)
15	// OutputRemoved reports that the wl_output global went away. The output is
16	// already gone from [Conn.Outputs].
17	OutputRemoved(global uint32)
18	// FDReady reports that a descriptor registered with [Conn.WatchFD] is
19	// readable. The watch is re-armed when the call returns. It can be
20	// spurious: drain the descriptor without blocking.
21	FDReady(id uint64)
22	// Error reports a non-fatal failure while handling an event, for example
23	// a wl_output that could not be bound. Fatal transport errors are returned
24	// by Dispatch instead.
25	Error(err error)
26
27	// Configure reports the logical size of a surface after the compositor's
28	// configure was acknowledged (the library acks internally). The first
29	// call makes the surface presentable. For layer surfaces an axis the
30	// compositor leaves unchanged keeps its previous size.
31	Configure(id SurfaceID, width, height int32)
32	// Scale reports a changed preferred scale: fractional (n/120) when the
33	// compositor supports wp_fractional_scale, else the integer buffer scale.
34	// Re-read [Surface.PhysicalSize] and render again.
35	Scale(id SurfaceID, scale float64)
36	// Frame reports that the frame callback requested by the last
37	// [Surface.Present] fired; the next Present is allowed.
38	Frame(id SurfaceID)
39	// Closed reports that the compositor closed the surface (toplevel close,
40	// layer surface closed). Call [Surface.Close]; nothing else happens
41	// automatically.
42	Closed(id SurfaceID)
43	// FeedbackDone reports that a complete linux-dmabuf feedback round was
44	// applied; [Surface.Feedback] holds the new main device and formats. It
45	// is sent again whenever the compositor changes its preference.
46	FeedbackDone(id SurfaceID)
47	// Locked reports ext_session_lock_v1.locked for the live [Lock]: every
48	// output is protected. Only now may [Lock.Unlock] be called.
49	Locked()
50	// LockFinished reports ext_session_lock_v1.finished: the compositor
51	// refused or ended the lock. Destroy it with [Lock.Close].
52	LockFinished()
53
54	// Pointer reports pointer input over one of the connection's surfaces:
55	// enter, leave, motion, buttons and scrolling. ev is valid only during the
56	// call.
57	Pointer(ev *PointerEvent)
58	// Key reports a key press, repeat or release for the surface that has
59	// keyboard focus. Text is the text the key produced (nil for releases and
60	// keys without text) and is valid only during the call. While a
61	// [SecretBuffer] is installed with [Seat.SetSecret], Text is always nil
62	// and the text goes into the buffer; see [Handler.SecretChanged]. For
63	// those keys (press, repeat and release) ev.Secret is set and Keycode and
64	// Keysym are 0, so the event does not reveal the typed character; Enter,
65	// Escape, BackSpace and Control combinations keep their keysym. ev is
66	// valid only during the call.
67	Key(ev *KeyEvent)
68	// KeyboardFocus reports that a surface gained or lost keyboard focus.
69	KeyboardFocus(id SurfaceID, focused bool)
70	// SecretChanged reports that a key press, repeat or backspace changed the
71	// installed [SecretBuffer]; count is its length in code points. It is
72	// called after the [Handler.Key] call of that key.
73	SecretChanged(count int)
74}
75
76// NopHandler implements every Handler method as a no-op. Embed it in a handler
77// and override only the methods you need; methods added to Handler in later
78// versions get their no-op here, so embedding keeps the type compiling.
79type NopHandler struct{}
80
81func (NopHandler) OutputAdded(*Output)  {}
82func (NopHandler) OutputRemoved(uint32) {}
83func (NopHandler) FDReady(uint64)       {}
84func (NopHandler) Error(error)          {}
85
86func (NopHandler) Configure(SurfaceID, int32, int32) {}
87func (NopHandler) Scale(SurfaceID, float64)          {}
88func (NopHandler) Frame(SurfaceID)                   {}
89func (NopHandler) Closed(SurfaceID)                  {}
90func (NopHandler) FeedbackDone(SurfaceID)            {}
91func (NopHandler) Locked()                           {}
92func (NopHandler) LockFinished()                     {}
93
94func (NopHandler) Pointer(*PointerEvent)         {}
95func (NopHandler) Key(*KeyEvent)                 {}
96func (NopHandler) KeyboardFocus(SurfaceID, bool) {}
97func (NopHandler) SecretChanged(int)             {}