docs(readme): popups

commit: 1bb004030d16ec7506b5bf821d8a73a882a8805b
author: brice · 13d ago · 2026-10-09 03:37 UTC
parent: b814107
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

1 file · +36 -0

M README.md +36 -0


@@ -38,6 +38,42 @@ for {
38	38		}
39	39		```
40	40
	41	+	### Popups
	42	+
	43	+	`Conn.NewPopup` creates an `xdg_popup` on a layer surface, a toplevel or another popup: a menu or tooltip placed relative to an anchor rectangle of its parent. With `Grab` the popup takes the keyboard and the compositor dismisses it on a click outside; the grab needs the `PointerEvent.Serial` of the button press that opened it. The compositor can dismiss a popup at any time, so a handler must implement `PopupDone` (embedded `NopHandler` ignores it) and close the popup; close popups before their parent.
	44	+
	45	+	```go
	46	+	func (h handler) Pointer(ev neferclient.PointerEvent) {
	47	+	if ev.Kind != neferclient.PointerButton \|\| !ev.Pressed {
	48	+	return
	49	+	}
	50	+	popup, err := h.conn.NewPopup(neferclient.PopupConfig{
	51	+	Parent: h.bar, // a layer surface
	52	+	Place: neferclient.PopupPlacement{
	53	+	Anchor: neferclient.Rect{X: 100, Y: 0, Width: 24, Height: 30}, // on the parent, logical px
	54	+	Edge: neferclient.EdgeBottom, Gravity: neferclient.EdgeBottomRight,
	55	+	Adjust: neferclient.AdjustSlideX \| neferclient.AdjustFlipY,
	56	+	Width: 200, Height: 120,
	57	+	},
	58	+	Grab: true, Serial: ev.Serial,
	59	+	})
	60	+	if err != nil {
	61	+	h.err = err
	62	+	return
	63	+	}
	64	+	h.popup = popup // presentable after Configure, like any surface
	65	+	}
	66	+
	67	+	func (h *handler) PopupDone(id neferclient.SurfaceID) {
	68	+	if h.popup != nil && h.popup.ID() == id {
	69	+	h.err = h.popup.Close()
	70	+	h.popup = nil
	71	+	}
	72	+	}
	73	+	```
	74	+
	75	+	`Surface.Reposition` moves a mapped popup (`xdg_wm_base` version 3).
	76	+
41	77		- [`examples/layer`](examples/layer): a layer surface with a counter button.
42	78		- [`examples/lock`](examples/lock): a session lock with a masked password field. It is a demo and authenticates nothing; read its header before running it.
43	79


@@ -38,6 +38,42 @@ for {
38	}	38		}
39	```	39		```
40		40
		41	+	### Popups
		42	+
		43	+	`Conn.NewPopup` creates an `xdg_popup` on a layer surface, a toplevel or another popup: a menu or tooltip placed relative to an anchor rectangle of its parent. With `Grab` the popup takes the keyboard and the compositor dismisses it on a click outside; the grab needs the `PointerEvent.Serial` of the button press that opened it. The compositor can dismiss a popup at any time, so a handler must implement `PopupDone` (embedded `NopHandler` ignores it) and close the popup; close popups before their parent.
		44	+
		45	+	```go
		46	+	func (h handler) Pointer(ev neferclient.PointerEvent) {
		47	+	if ev.Kind != neferclient.PointerButton \|\| !ev.Pressed {
		48	+	return
		49	+	}
		50	+	popup, err := h.conn.NewPopup(neferclient.PopupConfig{
		51	+	Parent: h.bar, // a layer surface
		52	+	Place: neferclient.PopupPlacement{
		53	+	Anchor: neferclient.Rect{X: 100, Y: 0, Width: 24, Height: 30}, // on the parent, logical px
		54	+	Edge: neferclient.EdgeBottom, Gravity: neferclient.EdgeBottomRight,
		55	+	Adjust: neferclient.AdjustSlideX \| neferclient.AdjustFlipY,
		56	+	Width: 200, Height: 120,
		57	+	},
		58	+	Grab: true, Serial: ev.Serial,
		59	+	})
		60	+	if err != nil {
		61	+	h.err = err
		62	+	return
		63	+	}
		64	+	h.popup = popup // presentable after Configure, like any surface
		65	+	}
		66	+
		67	+	func (h *handler) PopupDone(id neferclient.SurfaceID) {
		68	+	if h.popup != nil && h.popup.ID() == id {
		69	+	h.err = h.popup.Close()
		70	+	h.popup = nil
		71	+	}
		72	+	}
		73	+	```
		74	+
		75	+	`Surface.Reposition` moves a mapped popup (`xdg_wm_base` version 3).
		76	+
41	- [`examples/layer`](examples/layer): a layer surface with a counter button.	77		- [`examples/layer`](examples/layer): a layer surface with a counter button.
42	- [`examples/lock`](examples/lock): a session lock with a masked password field. It is a demo and authenticates nothing; read its header before running it.	78		- [`examples/lock`](examples/lock): a session lock with a masked password field. It is a demo and authenticates nothing; read its header before running it.
43		79