app: rename UpdateEvent to FrameEvent and add Frame field

While "DrawEvent" was too specific (op.Ops contains non-draw events),
"Update" is too vague: it's a common word, and could be misunderstood
to mean update parts of a window, not replace it.

"FrameEvent" is more specific, and is the usual way to refer to immediate
mode drawing.

While we're here, unexport Window.Update and add a Frame function to
FrameEvent, to emphasize that updating the window frame is only
appropriate during the handling of a FrameEvent.

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

app/app.go

@@ -10,20 +10,23 @@ import (
 	"strings"
 	"time"
 
+	"gioui.org/op"
 	"gioui.org/unit"
 )
 
-// An UpdateEvent is generated when a Window's Update
-// method must be called.
-type UpdateEvent struct {
+// A FrameEvent asks for a new frame in the form of a list of
+// operations.
+type FrameEvent struct {
 	Config Config
 	// Size is the dimensions of the window.
 	Size image.Point
 	// Insets is the insets to apply.
 	Insets Insets
-	// Whether this draw is system generated
-	// and needs a complete frame before
-	// proceeding.
+	// Frame replaces the window's frame with the new
+	// frame.
+	Frame func(frame *op.Ops)
+	// Whether this draw is system generated and needs a complete
+	// frame before proceeding.
 	sync bool
 }
 
@@ -74,7 +77,7 @@ type windowAndOptions struct {
 
 const (
 	// StagePaused is the Stage for inactive Windows.
-	// Inactive Windows don't receive UpdateEvents.
+	// Inactive Windows don't receive FrameEvents.
 	StagePaused Stage = iota
 	// StateRunning is for active Windows.
 	StageRunning
@@ -200,7 +203,7 @@ func newWindowRendezvous() *windowRendezvous {
 	return wr
 }
 
-func (_ UpdateEvent) ImplementsEvent()   {}
+func (_ FrameEvent) ImplementsEvent()    {}
 func (_ StageEvent) ImplementsEvent()    {}
 func (_ *CommandEvent) ImplementsEvent() {}
 func (_ DestroyEvent) ImplementsEvent()  {}

app/doc.go

@@ -13,7 +13,7 @@ is embedded in another project, NewWindow merely connects with a previously
 created window.
 
 A Window is run by receiving events from its Events channel. The most
-important event is UpdateEvent that prompts an update of the window
+important event is FrameEvent that prompts an update of the window
 contents and state.
 
 For example:
@@ -22,7 +22,7 @@ For example:
 
 	w := app.NewWindow()
 	for e := range w.Events() {
-		if e, ok := e.(app.UpdateEvent); ok {
+		if e, ok := e.(app.FrameEvent); ok {
 			ops.Reset()
 			// Add operations to ops.
 			...
@@ -60,7 +60,7 @@ For example, to display a blank but otherwise functional window:
 Event queue
 
 A Window's Queue method returns an event.Queue implementation that distributes
-incoming events to the event handlers declared in the latest call to Update.
+incoming events to the event handlers declared in the latest frame.
 See the gioui.org/ui package for more information about event handlers.
 
 */

app/os_android.go

@@ -296,7 +296,7 @@ func (w *window) draw(sync bool) {
 		return
 	}
 	ppdp := float32(w.dpi) * inchPrDp
-	w.event(UpdateEvent{
+	w.event(FrameEvent{
 		Size: image.Point{
 			X: int(width),
 			Y: int(height),

app/os_ios.go

@@ -80,7 +80,7 @@ func onDraw(view C.CFTypeRef, dpi, sdpi, width, height C.CGFloat, sync C.int, to
 	if sync != 0 {
 		isSync = true
 	}
-	w.w.event(UpdateEvent{
+	w.w.event(FrameEvent{
 		Size: image.Point{
 			X: int(width + .5),
 			Y: int(height + .5),

app/os_js.go

@@ -345,7 +345,7 @@ func (w *window) draw(sync bool) {
 	w.scale = float32(scale)
 	w.mu.Unlock()
 	cfg.now = time.Now()
-	w.w.event(UpdateEvent{
+	w.w.event(FrameEvent{
 		Size: image.Point{
 			X: width,
 			Y: height,

app/os_macos.go

@@ -198,7 +198,7 @@ func (w *window) draw(sync bool) {
 	cfg := configFor(w.ppdp, w.scale)
 	cfg.now = time.Now()
 	w.setStage(StageRunning)
-	w.w.event(UpdateEvent{
+	w.w.event(FrameEvent{
 		Size: image.Point{
 			X: width,
 			Y: height,

app/os_wayland.go

@@ -1018,7 +1018,7 @@ func (w *window) draw(sync bool) {
 		C.gio_wl_callback_add_listener(w.lastFrameCallback, unsafe.Pointer(w.surf))
 	}
 	cfg.now = time.Now()
-	w.w.event(UpdateEvent{
+	w.w.event(FrameEvent{
 		Size: image.Point{
 			X: width,
 			Y: height,

app/os_windows.go

@@ -407,7 +407,7 @@ func (w *window) draw(sync bool) {
 	w.height = int(r.bottom - r.top)
 	cfg := configForDC(w.hdc)
 	cfg.now = time.Now()
-	w.w.event(UpdateEvent{
+	w.w.event(FrameEvent{
 		Size: image.Point{
 			X: w.width,
 			Y: w.height,

app/window.go

@@ -47,7 +47,7 @@ type Window struct {
 }
 
 // Queue is an event.Queue implementation that distributes system events
-// to the input handlers declared in the most recent call to Update.
+// to the input handlers declared in the most recent frame.
 type Queue struct {
 	q input.Router
 }
@@ -62,7 +62,7 @@ type driverEvent struct {
 // of a Window.
 var _ interface {
 	// setAnimating sets the animation flag. When the window is animating,
-	// UpdateEvents are delivered as fast as the display can handle them.
+	// FrameEvents are delivered as fast as the display can handle them.
 	setAnimating(anim bool)
 	// showTextInput updates the virtual keyboard state.
 	showTextInput(show bool)
@@ -110,16 +110,16 @@ func (w *Window) Events() <-chan event.Event {
 }
 
 // Queue returns the Window's event queue. The queue contains
-// the events received since the last UpdateEvent.
+// the events received since the last frame.
 func (w *Window) Queue() *Queue {
 	return &w.queue
 }
 
-// Update updates the Window. Paint operations updates the
+// update updates the Window. Paint operations updates the
 // window contents, input operations declare input handlers,
 // and so on. The supplied operations list completely replaces
 // the window state from previous calls.
-func (w *Window) Update(frame *op.Ops) {
+func (w *Window) update(frame *op.Ops) {
 	w.frames <- frame
 }
 
@@ -153,7 +153,7 @@ func (w *Window) draw(size image.Point, frame *op.Ops) {
 	w.updateAnimation()
 }
 
-// Invalidate the window such that a UpdateEvent will be generated
+// Invalidate the window such that a FrameEvent will be generated
 // immediately. If the window is inactive, the event is sent when the
 // window becomes active.
 // Invalidate is safe for concurrent use.
@@ -253,7 +253,7 @@ func (w *Window) run(opts *windowOptions) {
 				w.updateAnimation()
 				w.out <- e
 				w.waitAck()
-			case UpdateEvent:
+			case FrameEvent:
 				if e2.Size == (image.Point{}) {
 					panic(errors.New("internal error: zero-sized Draw"))
 				}
@@ -263,7 +263,8 @@ func (w *Window) run(opts *windowOptions) {
 				}
 				w.drawStart = time.Now()
 				w.hasNextFrame = false
-				w.out <- e
+				e2.Frame = w.update
+				w.out <- e2
 				var frame *op.Ops
 				// Wait for either a frame or the ack event,
 				// which meant that the client didn't draw.