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 // PopupDone reports that the compositor dismissed a popup created with
44 // [Conn.NewPopup]: an outside click, a denied grab, or a gone parent. Call
45 // [Surface.Close] on it (and on its own child popups first).
46 PopupDone(id SurfaceID)
47 // FeedbackDone reports that a complete linux-dmabuf feedback round was
48 // applied; [Surface.Feedback] holds the new main device and formats. It
49 // is sent again whenever the compositor changes its preference.
50 FeedbackDone(id SurfaceID)
51 // Locked reports ext_session_lock_v1.locked for the live [Lock]: every
52 // output is protected. Only now may [Lock.Unlock] be called.
53 Locked()
54 // LockFinished reports ext_session_lock_v1.finished: the compositor
55 // refused or ended the lock. Destroy it with [Lock.Close].
56 LockFinished()
57
58 // Pointer reports pointer input over one of the connection's surfaces:
59 // enter, leave, motion, buttons and scrolling. ev is valid only during the
60 // call.
61 Pointer(ev *PointerEvent)
62 // Key reports a key press, repeat or release for the surface that has
63 // keyboard focus. Text is the text the key produced (nil for releases and
64 // keys without text) and is valid only during the call. While a
65 // [SecretBuffer] is installed with [Seat.SetSecret], Text is always nil
66 // and the text goes into the buffer; see [Handler.SecretChanged]. For
67 // those keys (press, repeat and release) ev.Secret is set and Keycode and
68 // Keysym are 0, so the event does not reveal the typed character; Enter,
69 // Escape, BackSpace and Control combinations keep their keysym. ev is
70 // valid only during the call.
71 Key(ev *KeyEvent)
72 // KeyboardFocus reports that a surface gained or lost keyboard focus.
73 KeyboardFocus(id SurfaceID, focused bool)
74 // SecretChanged reports that a key press, repeat or backspace changed the
75 // installed [SecretBuffer]; count is its length in code points. It is
76 // called after the [Handler.Key] call of that key.
77 SecretChanged(count int)
78}
79
80// NopHandler implements every Handler method as a no-op. Embed it in a handler
81// and override only the methods you need; methods added to Handler in later
82// versions get their no-op here, so embedding keeps the type compiling.
83type NopHandler struct{}
84
85func (NopHandler) OutputAdded(*Output) {}
86func (NopHandler) OutputRemoved(uint32) {}
87func (NopHandler) FDReady(uint64) {}
88func (NopHandler) Error(error) {}
89
90func (NopHandler) Configure(SurfaceID, int32, int32) {}
91func (NopHandler) Scale(SurfaceID, float64) {}
92func (NopHandler) Frame(SurfaceID) {}
93func (NopHandler) Closed(SurfaceID) {}
94func (NopHandler) PopupDone(SurfaceID) {}
95func (NopHandler) FeedbackDone(SurfaceID) {}
96func (NopHandler) Locked() {}
97func (NopHandler) LockFinished() {}
98
99func (NopHandler) Pointer(*PointerEvent) {}
100func (NopHandler) Key(*KeyEvent) {}
101func (NopHandler) KeyboardFocus(SurfaceID, bool) {}
102func (NopHandler) SecretChanged(int) {}