gioui.org: gioui.org/ui Index | Files | Directories

package ui

import "gioui.org/ui"

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.

Index

Package Files

doc.go ops.go ui.go unit.go

type Config Uses

type Config interface {
    // Now returns the current animation time.
    Now() time.Time
    // Px converts a Value to pixels.
    Px(v Value) int
}

Config define the essential properties of the environment.

type InvalidateOp Uses

type InvalidateOp struct {
    At time.Time
}

InvalidateOp requests a redraw at the given time. Use the zero value to request an immediate redraw.

func (InvalidateOp) Add Uses

func (r InvalidateOp) Add(o *Ops)

type MacroOp Uses

type MacroOp struct {
    // contains filtered or unexported fields
}

MacroOp can record a list of operations for later use.

func (MacroOp) Add Uses

func (m MacroOp) Add(o *Ops)

Add the recorded list of operations. The Ops argument may be different than the Ops argument passed to Record.

func (*MacroOp) Record Uses

func (m *MacroOp) Record(o *Ops)

Record a macro of operations.

func (*MacroOp) Stop Uses

func (m *MacroOp) Stop()

Stop ends a previously started recording.

type Ops Uses

type Ops struct {
    // contains filtered or unexported fields
}

Ops holds a list of operations. Operations are stored in serialized form to avoid garbage during construction of the ops list.

func (*Ops) Aux Uses

func (o *Ops) Aux() []byte

Internal use only.

func (*Ops) Data Uses

func (o *Ops) Data() []byte

Internal use only.

func (*Ops) Refs Uses

func (o *Ops) Refs() []interface{}

Internal use only.

func (*Ops) Reset Uses

func (o *Ops) Reset()

Reset the Ops, preparing it for re-use.

func (*Ops) Version Uses

func (o *Ops) Version() int

Internal use only.

func (*Ops) Write Uses

func (o *Ops) Write(op []byte, refs ...interface{})

Internal use only.

type StackOp Uses

type StackOp struct {
    // contains filtered or unexported fields
}

StackOp can save and restore the operation state in a stack-like manner.

func (*StackOp) Pop Uses

func (s *StackOp) Pop()

Pop (restore) a previously Pushed operations state.

func (*StackOp) Push Uses

func (s *StackOp) Push(o *Ops)

Push (save) the current operations state.

type TransformOp Uses

type TransformOp struct {
    // contains filtered or unexported fields
}

TransformOp applies a transform to the current transform.

func (TransformOp) Add Uses

func (t TransformOp) Add(o *Ops)

func (TransformOp) Invert Uses

func (t TransformOp) Invert() TransformOp

Invert the transformation.

func (TransformOp) Multiply Uses

func (t TransformOp) Multiply(t2 TransformOp) TransformOp

Multiply by a transformation.

func (TransformOp) Offset Uses

func (t TransformOp) Offset(o f32.Point) TransformOp

Offset the transformation.

func (TransformOp) Transform Uses

func (t TransformOp) Transform(p f32.Point) f32.Point

Transform a point.

type Unit Uses

type Unit uint8

Unit represents a unit for a Value.

const (
    // UnitPx represent device pixels in the resolution of
    // the underlying display.
    UnitPx Unit = iota
    // UnitDp represents device independent pixels. 1 dp will
    // have the same apparent size across platforms and
    // display resolutions.
    UnitDp
    // UnitSp is like UnitDp but for font sizes.
    UnitSp
)

func (Unit) String Uses

func (u Unit) String() string

type Value Uses

type Value struct {
    V   float32
    U   Unit
}

Value is a value with a unit.

func Dp Uses

func Dp(v float32) Value

Px returns the Value for v device independent pixels.

func Px Uses

func Px(v float32) Value

Px returns the Value for v device pixels.

func Sp Uses

func Sp(v float32) Value

Sp returns the Value for v scaled dps.

func (Value) String Uses

func (v Value) String() string

Directories

PathSynopsis
appPackage app provides a platform-independent interface to operating system functionality for running graphical user interfaces.
app/internal/gl
app/internal/gpu
app/internal/input
f32Package f32 is a float32 implementation of package image's Point and Rectangle.
gesturePackage gesture implements common pointer gestures.
inputPackage input exposes a unified interface for receiving input events.
internal/opconst
internal/ops
internal/path
keyPackage key implements key and text events and operations.
layoutPackage layout implements layouts common to GUI programs.
measurePackage measure implements text layout and shaping.
paintPackage paint provides operations for 2D graphics.
pointerPackage pointer implements pointer events and operations.
systemPackage system contain ops and types for system events.
textPackage text implements text widgets.
widgetPackage widget implements common widgets.

Package ui imports 6 packages (graph) and is imported by 37 packages. Updated 2019-08-20. Refresh now. Tools for package owners.