io/input: [API] introduce Source, the interface between a Router and widgets

This change gets rid of the event.Queue interface by replacing it with
input.Source values. Source provides the interface to Router necessary
to implement interface widgets.

Signed-off-by: Elias Naur <mail@eliasnaur.com>

io/event/event.go

@@ -1,42 +1,8 @@
 // SPDX-License-Identifier: Unlicense OR MIT
 
-/*
-Package event contains the types for event handling.
-
-The Queue interface is the protocol for receiving external events.
-
-For example:
-
-	var queue event.Queue = ...
-
-	for _, e := range queue.Events(h) {
-		switch e.(type) {
-			...
-		}
-	}
-
-In general, handlers must be declared before events become
-available. Other packages such as pointer and key provide
-the means for declaring handlers for specific event types.
-
-The following example declares a handler ready for key input:
-
-	import gioui.org/io/key
-
-	ops := new(op.Ops)
-	var h *Handler = ...
-	key.InputOp{Tag: h, Filter: ...}.Add(ops)
-*/
+// Package event contains types for event handling.
 package event
 
-// Queue maps an event handler key to the events
-// available to the handler.
-type Queue interface {
-	// Events returns the available events for an
-	// event handler tag.
-	Events(t Tag) []Event
-}
-
 // Tag is the stable identifier for an event handler.
 // For a handler h, the tag is typically &h.
 type Tag interface{}

io/input/doc.go

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Unlicense OR MIT
+
+/*
+Package input implements input routing and tracking of interface
+state for a window.
+
+The [Source] is the interface between the window and the widgets
+of a user interface and is exposed by [gioui.org/app.FrameEvent]
+received from windows.
+
+The [Router] is used by [gioui.org/app.Window] to track window state and route
+events from the platform to event handlers. It is otherwise only
+useful for using Gio with external window implementations.
+*/
+package input

io/input/router.go

@@ -1,13 +1,5 @@
 // SPDX-License-Identifier: Unlicense OR MIT
 
-/*
-Package input implements Router, an event.Queue implementation
-that disambiguates and routes events to handlers declared
-in operation lists.
-
-Router is used by app.Window and is otherwise only useful for
-using Gio with external window implementations.
-*/
 package input
 
 import (
@@ -31,8 +23,8 @@ import (
 	"gioui.org/op"
 )
 
-// Router is a Queue implementation that routes events
-// to handlers declared in operation lists.
+// Router tracks the [io/event.Tag] identifiers of user interface widgets
+// and routes events to them. [Source] is its interface exposed to widgets.
 type Router struct {
 	savedTrans []f32.Affine2D
 	transStack []f32.Affine2D
@@ -55,6 +47,12 @@ type Router struct {
 	wakeupTime time.Time
 }
 
+// Source implements the interface between a Router and user interface widgets.
+// The value Source is disabled.
+type Source struct {
+	r *Router
+}
+
 // SemanticNode represents a node in the tree describing the components
 // contained in a frame.
 type SemanticNode struct {
@@ -95,7 +93,25 @@ type handlerEvents struct {
 	hadEvents bool
 }
 
-// Events returns the available events for the handler key.
+// Source returns a Source backed by this Router.
+func (q *Router) Source() Source {
+	return Source{r: q}
+}
+
+// Enabled reports whether the source is enabled. Only enabled
+// Sources deliver events and respond to commands.
+func (s Source) Enabled() bool {
+	return s.r != nil
+}
+
+// Events returns the available events for the handler tag.
+func (s Source) Events(k event.Tag) []event.Event {
+	if !s.Enabled() {
+		return nil
+	}
+	return s.r.Events(k)
+}
+
 func (q *Router) Events(k event.Tag) []event.Event {
 	events := q.handlers.Events(k)
 	return events