mirror of
https://git.sr.ht/~eliasnaur/gio
synced 2026-07-01 15:45:38 +00:00
Elias Naur
dc6fedc163
The Queue interface was changed from
type Queue interface {
Events(k Key) []Event
}
to the more complex single-step protocol
type Queue interface {
Next(k Key) (Event, bool)
}
to cater for a particular use case: Editor's SubmitEvent. When a
SubmitEvent is passed to a caller of Editor.Next, the Editor state,
in particular the current text, must not have changed by edits
later in the command stream. For example, pressing the keys <E>,
<Enter>, <E> should result in a SubmitEvent where the Editor has
a single 'e' in Text(), not two.
However, there is no reason to push the more complex Queue to every user.
Rather, store remaining input events inside Editor and process them as
Editor.Event (or Layout) is called.
Finally, revert the Queue interface to the simpler Events method.
Signed-off-by: Elias Naur <mail@eliasnaur.com>
112 lines
2.7 KiB
Go
112 lines
2.7 KiB
Go
// SPDX-License-Identifier: Unlicense OR MIT
|
|
|
|
/*
|
|
Package ui defines operations buffers, units and common operations
|
|
for GUI programs written with the Gio module.
|
|
|
|
See https://gioui.org for instructions to setup and run Gio programs.
|
|
|
|
Operations
|
|
|
|
Gio programs use operations, or ops, for describing their user
|
|
interfaces. There are operations for drawing, defining input
|
|
handlers, changing window properties as well as operations for
|
|
controlling the execution of other operations.
|
|
|
|
Ops represents a list of operations. The most important use
|
|
for an Ops list is to describe a complete user interface update
|
|
to a ui/app.Window's Update method.
|
|
|
|
Drawing a colored square:
|
|
|
|
import "gioui.org/ui"
|
|
import "gioui.org/ui/app"
|
|
import "gioui.org/ui/paint"
|
|
|
|
var w app.Window
|
|
ops := new(ui.Ops)
|
|
...
|
|
ops.Reset()
|
|
paint.ColorOp{Color: ...}.Add(ops)
|
|
paint.PaintOp{Rect: ...}.Add(ops)
|
|
w.Update(ops)
|
|
|
|
State
|
|
|
|
An Ops list can be viewed as a very simple virtual machine: it has an implicit
|
|
mutable state stack and execution flow can be controlled with macros.
|
|
|
|
The StackOp saves the current state to the state stack and restores it later:
|
|
|
|
ops := new(ui.Ops)
|
|
var stack ui.StackOp
|
|
// Save the current state, in particular the transform.
|
|
stack.Push(ops)
|
|
// Apply a transform to subsequent operations.
|
|
ui.TransformOp{}.Offset(...).Add(ops)
|
|
...
|
|
// Restore the previous transform.
|
|
stack.Pop()
|
|
|
|
The MacroOp records a list of operations to be executed later:
|
|
|
|
ops := new(ui.Ops)
|
|
var macro ui.MacroOp
|
|
macro.Record()
|
|
// Record operations by adding them.
|
|
ui.InvalidateOp{}.Add(ops)
|
|
...
|
|
macro.Stop()
|
|
...
|
|
// Execute the recorded operations.
|
|
macro.Add(ops)
|
|
|
|
Note that operations added between Record and Stop are not executed until
|
|
the macro is Added.
|
|
|
|
Units
|
|
|
|
A Value is a value with a Unit attached.
|
|
|
|
Device independent pixel, or dp, is the unit for sizes independent of
|
|
the underlying display device.
|
|
|
|
Scaled pixels, or sp, is the unit for text sizes. An sp is like dp with
|
|
text scaling applied.
|
|
|
|
Finally, pixels, or px, is the unit for display dependent pixels. Their
|
|
size vary between platforms and displays.
|
|
|
|
To maintain a constant visual size across platforms and displays, always
|
|
use dps or sps to define user interfaces. Only use pixels for derived
|
|
values.
|
|
|
|
Events
|
|
|
|
The Queue interface is the protocol for receiving external events.
|
|
|
|
For example:
|
|
|
|
var queue ui.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/ui/key
|
|
|
|
ops := new(ui.Ops)
|
|
var h *Handler = ...
|
|
key.InputOp{Key: h}.Add(ops)
|
|
|
|
*/
|
|
package ui
|