io/key: [API] implement key event propagation

Before this change, every Event would be passed to the focused InputOp
tag, making it impossible to implement, say, program-wide shortcuts.
This change implements key.Event routing similar to how pointer.Events
are routed: every InputOp describes the set of keys it can handle, and
the router use that information to deliver an Event to the matching
handler.

This is an API change, because every InputOp must now include a filter
matching the keys it wants to handle.

Fixes: https://todo.sr.ht/~eliasnaur/gio/395
Signed-off-by: Elias Naur <mail@eliasnaur.com>

io/key/key.go

@@ -25,10 +25,30 @@ import (
 // Key events are in general only delivered to the
 // focused key handler.
 type InputOp struct {
-	Tag  event.Tag
+	Tag event.Tag
+	// Hint describes the type of text expected by Tag.
 	Hint InputHint
+	// Keys is the set of keys Tag can handle. That is, Tag will only
+	// receive an Event if its key and modifiers are accepted by Keys.Contains.
+	Keys Set
 }
 
+// Set is an expression that describes a set of key combinations, in the form
+// "<modifiers>-<keyset>|...".  Modifiers are separated by dashes, optional
+// modifiers are enclosed by parentheses.  A key set is either a literal key
+// name or a list of key names separated by commas and enclosed in brackets.
+//
+// The "Short" modifier matches the shortcut modifier (ModShortcut) and
+// "ShortAlt" matches the alternative modifier (ModShortcutAlt).
+//
+// Examples:
+//
+//   - A|B matches the A and B keys
+//   - [A,B] also matches the A and B keys
+//   - Shift-A matches A key if shift is pressed, and no other modifier.
+//   - Shift-(Ctrl)-A matches A if shift is pressed, and optionally ctrl.
+type Set string
+
 // SoftKeyboardOp shows or hide the on-screen keyboard, if available.
 // It replaces any previous SoftKeyboardOp.
 type SoftKeyboardOp struct {
@@ -207,11 +227,99 @@ func (m Modifiers) Contain(m2 Modifiers) bool {
 	return m&m2 == m2
 }
 
+func (k Set) Contains(name string, mods Modifiers) bool {
+	ks := string(k)
+	for len(ks) > 0 {
+		// Cut next key expression.
+		chord, rest, _ := cut(ks, "|")
+		ks = rest
+		// Separate key set and modifier set.
+		var modSet, keySet string
+		sep := strings.LastIndex(chord, "-")
+		if sep != -1 {
+			modSet, keySet = chord[:sep], chord[sep+1:]
+		} else {
+			modSet, keySet = "", chord
+		}
+		if !keySetContains(keySet, name) {
+			continue
+		}
+		if modSetContains(modSet, mods) {
+			return true
+		}
+	}
+	return false
+}
+
+func keySetContains(keySet, name string) bool {
+	// Check for single key match.
+	if keySet == name {
+		return true
+	}
+	// Check for set match.
+	if len(keySet) < 2 || keySet[0] != '[' || keySet[len(keySet)-1] != ']' {
+		return false
+	}
+	keySet = keySet[1 : len(keySet)-1]
+	for len(keySet) > 0 {
+		key, rest, _ := cut(keySet, ",")
+		keySet = rest
+		if key == name {
+			return true
+		}
+	}
+	return false
+}
+
+func modSetContains(modSet string, mods Modifiers) bool {
+	var smods Modifiers
+	for len(modSet) > 0 {
+		mod, rest, _ := cut(modSet, "-")
+		modSet = rest
+		if len(mod) >= 2 && mod[0] == '(' && mod[len(mod)-1] == ')' {
+			mods &^= modFor(mod[1 : len(mod)-1])
+		} else {
+			smods |= modFor(mod)
+		}
+	}
+	return mods == smods
+}
+
+// cut is a copy of the standard library strings.Cut.
+// TODO: remove when Go 1.18 is our minimum.
+func cut(s, sep string) (before, after string, found bool) {
+	if i := strings.Index(s, sep); i >= 0 {
+		return s[:i], s[i+len(sep):], true
+	}
+	return s, "", false
+}
+
+func modFor(name string) Modifiers {
+	switch name {
+	case NameCtrl:
+		return ModCtrl
+	case NameShift:
+		return ModShift
+	case NameAlt:
+		return ModAlt
+	case NameSuper:
+		return ModSuper
+	case NameCommand:
+		return ModCommand
+	case "Short":
+		return ModShortcut
+	case "ShortAlt":
+		return ModShortcutAlt
+	}
+	return 0
+}
+
 func (h InputOp) Add(o *op.Ops) {
 	if h.Tag == nil {
 		panic("Tag must be non-nil")
 	}
-	data := ops.Write1(&o.Internal, ops.TypeKeyInputLen, h.Tag)
+	filter := h.Keys
+	data := ops.Write2(&o.Internal, ops.TypeKeyInputLen, h.Tag, &filter)
 	data[0] = byte(ops.TypeKeyInput)
 	data[1] = byte(h.Hint)
 }

io/key/key_test.go

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Unlicense OR MIT
+
+package key
+
+import (
+	"testing"
+)
+
+func TestKeySet(t *testing.T) {
+	const allMods = ModAlt | ModShift | ModSuper | ModCtrl | ModCommand
+	tests := []struct {
+		Set        Set
+		Matches    []Event
+		Mismatches []Event
+	}{
+		{"A", []Event{{Name: "A"}}, []Event{{Name: "A", Modifiers: ModShift}}},
+		{"[A,B,C]", []Event{{Name: "A"}, {Name: "B"}}, []Event{}},
+		{"Short-A", []Event{{Name: "A", Modifiers: ModShortcut}}, []Event{{Name: "A", Modifiers: ModShift}}},
+		{"(Ctrl)-A", []Event{{Name: "A", Modifiers: ModCtrl}, {Name: "A"}}, []Event{{Name: "A", Modifiers: ModShift}}},
+		{"Shift-[A,B,C]", []Event{{Name: "A", Modifiers: ModShift}}, []Event{{Name: "B", Modifiers: ModShift | ModCtrl}}},
+		{Set(allMods.String() + "-A"), []Event{{Name: "A", Modifiers: allMods}}, []Event{}},
+	}
+	for _, tst := range tests {
+		for _, e := range tst.Matches {
+			if !tst.Set.Contains(e.Name, e.Modifiers) {
+				t.Errorf("key set %q didn't contain %+v", tst.Set, e)
+			}
+		}
+		for _, e := range tst.Mismatches {
+			if tst.Set.Contains(e.Name, e.Modifiers) {
+				t.Errorf("key set %q contains %+v", tst.Set, e)
+			}
+		}
+	}
+}

io/key/mod.go

@@ -5,6 +5,10 @@
 
 package key
 
-// ModShortcut is the platform's shortcut modifier, usually the Ctrl
-// key. On Apple platforms it is the Cmd key.
+// ModShortcut is the platform's shortcut modifier, usually the ctrl
+// modifier. On Apple platforms it is the cmd key.
 const ModShortcut = ModCtrl
+
+// ModShortcutAlt is the platform's alternative shortcut modifier,
+// usually the ctrl modifier. On Apple platforms it is the alt modifier.
+const ModShortcutAlt = ModCtrl

io/key/mod_darwin.go

@@ -2,6 +2,10 @@
 
 package key
 
-// ModShortcut is the platform's shortcut modifier, usually the Ctrl
-// key. On Apple platforms it is the Cmd key.
+// ModShortcut is the platform's shortcut modifier, usually the ctrl
+// modifier. On Apple platforms it is the cmd key.
 const ModShortcut = ModCommand
+
+// ModShortcut is the platform's alternative shortcut modifier,
+// usually the ctrl modifier. On Apple platforms it is the alt modifier.
+const ModShortcutAlt = ModAlt