a2baffdbfd94ebe3194264524c40f3a986d0af4b — Elias Naur 7 months ago a6c262c
ui: expand package documentation

Signed-off-by: Elias Naur <mail@eliasnaur.com>
3 files changed, 87 insertions(+), 7 deletions(-)

M ui/doc.go
M ui/ops.go
M ui/ui.go
M ui/doc.go => ui/doc.go +78 -3
@@ 1,9 1,84 @@
// 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.


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
	var ops ui.Ops
	paint.ColorOp{Color: ...}.Add(ops)
	paint.PaintOp{Rect: ...}.Add(ops)


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:

	var ops ui.Ops
	var stack ui.StackOp
	// Save the current state, in particular the transform.
	// Apply a transform to subsequent operations.
	// Restore the previous transform.

The MacroOp records a list of operations to be executed later:

	var ops ui.Ops
	var macro ui.MacroOp
	// Record operations by adding them.
	// Execute the recorded operations.

Note that operations added between Record and Stop are not executed until
the macro is Added.


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.

Package ui implements portable desktop and mobile GUI programs.
Scaled pixels, or sp, is the unit for text sizes. An sp is like dp with
text scaling applied.

See https://gioui.org for instructions to setup dependencies and
run Gio programs.
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
package ui

M ui/ops.go => ui/ops.go +6 -1
@@ 8,7 8,9 @@ import (

// Ops holds a list of serialized operations.
// Ops holds a list of operations. Operations are stored in
// serialized form to avoid garbage during construction of
// the ops list.
type Ops struct {
	// version is incremented at each Reset.
	version int

@@ 176,6 178,9 @@ func (m *MacroOp) Stop() {
	m.version = m.ops.version

// Add the recorded list of operations. The Ops
// argument may be different than the Ops argument
// passed to Record.
func (m MacroOp) Add(o *Ops) {
	if m.recording {
		panic("a recording is in progress")

M ui/ui.go => ui/ui.go +3 -3
@@ 11,8 11,8 @@ import (

// Config represents the essential configuration for
// updating and drawing a user interface.
// Config define the essential properties of
// the environment.
type Config interface {
	// Now returns the current animation time.
	Now() time.Time

@@ 26,7 26,7 @@ type InvalidateOp struct {
	At time.Time

// TransformOp applies a transform to later ops.
// TransformOp applies a transform to the current transform.
type TransformOp struct {
	// TODO: general transformations.
	offset f32.Point