blob: 89893f5782dc2ac0b59d1d6da8611076655de366 [file] [log] [blame]
// Copyright 2016 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// Package node provides the structure for a tree of heterogenous widget nodes.
//
// Most programmers should not need to import this package, only the top-level
// widget package. Only those that write custom widgets need to explicitly
// refer to the Node, Embed and related types.
//
// The Node interface is usually implemented by struct types that embed one of
// LeafEmbed, ShellEmbed or ContainerEmbed (all of which themselves embed an
// Embed), providing default implementations of all of Node's methods.
//
// The split between an outer wrapper (Node) interface type and an inner
// wrappee (Embed) struct type enables heterogenous nodes, such as a buttons
// and labels, in a widget tree where every node contains common fields such as
// position, size and tree structure links (parent, siblings and children).
//
// In a traditional object-oriented type system, this might be represented by
// the Button and Label types both subclassing the Node type. Go does not have
// inheritance, so the outer / inner split is composed explicitly. For example,
// the concrete Button type is a struct type that embeds an XxxEmbed (such as
// LeafEmbed), and the NewButton function sets the inner Embed's Wrapper field
// to point back to the outer value.
//
// There are three layers here (Button embeds LeafEmbed embeds Embed) instead
// of two. The intermediate layer exists because there needs to be a place to
// provide default implementations of methods like Measure, but that place
// shouldn't be the inner-most type (Embed), otherwise it'd be too easy to
// write subtly incorrect code like:
//
// for c := w.FirstChild; c != nil; c = c.NextSibling {
// c.Measure(etc) // This should instead be c.Wrapper.Measure(etc).
// }
//
// In any case, most programmers that want to construct a widget tree should
// not need to know this detail. It usually suffices to call functions such as
// widget.NewButton or widget.NewLabel, and then parent.Insert(button, nil).
//
// See the example/gallery program for some example code for a custom widget.
package node // import "golang.org/x/exp/shiny/widget/node"
import (
"image"
"golang.org/x/exp/shiny/gesture"
"golang.org/x/exp/shiny/screen"
"golang.org/x/exp/shiny/widget/theme"
"golang.org/x/image/math/f64"
"golang.org/x/mobile/event/lifecycle"
"golang.org/x/mobile/event/mouse"
)
// EventHandled is whether or not an input event (a key, mouse, touch or
// gesture event) was handled by a widget. If it was not handled, the event is
// propagated along the widget tree.
type EventHandled bool
const (
NotHandled = EventHandled(false)
Handled = EventHandled(true)
)
// NoHint means that there is no width or height hint in a Measure call.
const NoHint = -1
// Node is a node in the widget tree.
type Node interface {
// Wrappee returns the inner (embedded) type that is wrapped by this type.
Wrappee() *Embed
// Insert adds a node c as a child of this node. If nextSibling is nil, c
// will be inserted at the end of this node's children. Otherwise, c will
// be inserted such that its next sibling is nextSibling.
//
// It will panic if c already has a parent or siblings.
Insert(c, nextSibling Node)
// Remove removes a node c that is a child of this node. Afterwards, c will
// have no parent and no siblings.
//
// It will panic if c's parent is not this node.
Remove(c Node)
// Measure sets this node's Embed.MeasuredSize to its natural size, taking
// its children into account.
//
// Some nodes' natural height might depend on their imposed width, such as
// a text widget word-wrapping its contents. The caller may provide hints
// that the parent can override the child's natural size in the width,
// height or both directions. A negative value means that there is no hint.
// For example, a container might lay out its children to all have the same
// width, and could pass that width as the widthHint argument.
Measure(t *theme.Theme, widthHint, heightHint int)
// Layout lays out this node (and its children), setting the Embed.Rect
// fields of each child. This node's Embed.Rect field should have
// previously been set during the parent node's layout.
Layout(t *theme.Theme)
// Paint paints this node (and its children). Painting is split into two
// passes: a base pass and an effects pass. The effects pass is often a
// no-op, and the bulk of the work is typically done in the base pass.
//
// The base pass paints onto an *image.RGBA pixel buffer and ancestor nodes
// may choose to re-use the result. For example, re-painting a text widget
// after scrolling may copy cached buffers at different offsets, instead of
// painting the text's glyphs onto a fresh buffer. Similarly, animating the
// scale and opacity of an overlay can re-use the buffer from a previous
// base pass.
//
// The effects pass paints that part of the widget that can not or should
// not be cached. For example, the border of a text widget shouldn't move
// on the screen when that text widget is scrolled. The effects pass does
// not have a destination RGBA pixel buffer, and is limited to what a
// screen.Drawer provides: affine-transformed textures and uniform fills.
//
// TODO: app-specific OpenGL, if available, should be part of the effects
// pass. Is that exposed via the screen.Drawer or by another mechanism?
//
// The Paint method may create base pass RGBA pixel buffers, by calling
// ctx.Screen.NewBuffer. Many implementations won't, and instead assume
// that PaintBase is recursively triggered by an ancestor node such as a
// widget.Sheet. If it does create those RGBA pixel buffers, it is also
// responsible for calling PaintBase on this node (and its children). In
// any case, the Paint method should then paint any effects. Many widgets
// will neither create their own buffers nor have any effects, so their
// Paint methods will simply be the default implemention: do nothing except
// call Paint on its children. As mentioned above, the bulk of the work is
// typically done in PaintBase.
//
// origin is the parent widget's origin with respect to the ctx.Src2Dst
// transformation matrix; this node's Embed.Rect.Add(origin) will be its
// position and size in pre-transformed coordinate space.
Paint(ctx *PaintContext, origin image.Point) error
// PaintBase paints the base pass of this node (and its children) onto an
// RGBA pixel buffer.
//
// origin is the parent widget's origin with respect to the ctx.Dst image's
// origin; this node's Embed.Rect.Add(origin) will be its position and size
// in ctx.Dst's coordinate space.
PaintBase(ctx *PaintBaseContext, origin image.Point) error
// Mark adds the given marks to this node. It calls OnChildMarked on its
// parent if new marks were added.
Mark(m Marks)
// OnChildMarked handles a child being given new marks. By default, marks
// are propagated up the node tree towards the root. For example, a child
// being marked for needing paint will cause the parent being marked for
// needing paint.
OnChildMarked(child Node, newMarks Marks)
// OnLifecycleEvent propagates a lifecycle event to a node (and its
// children).
OnLifecycleEvent(e lifecycle.Event)
// OnInputEvent handles a key, mouse, touch or gesture event.
//
// origin is the parent widget's origin with respect to the event origin;
// this node's Embed.Rect.Add(origin) will be its position and size in
// event coordinate space.
OnInputEvent(e interface{}, origin image.Point) EventHandled
// TODO: other OnXxxEvent methods?
}
// PaintContext is the context for the Node.Paint method.
type PaintContext struct {
Theme *theme.Theme
Screen screen.Screen
Drawer screen.Drawer
Src2Dst f64.Aff3
// TODO: add a clip rectangle?
// TODO: add the DrawContext from the lifecycle event?
}
// PaintBaseContext is the context for the Node.PaintBase method.
type PaintBaseContext struct {
Theme *theme.Theme
Dst *image.RGBA
// TODO: add a clip rectangle? Or rely on the RGBA.SubImage method to pass
// smaller Dst images?
}
// LeafEmbed is designed to be embedded in struct types for nodes with no
// children.
type LeafEmbed struct{ Embed }
func (m *LeafEmbed) Insert(c, nextSibling Node) {
panic("node: Insert called for a leaf parent")
}
func (m *LeafEmbed) Remove(c Node) { m.remove(c) }
func (m *LeafEmbed) Measure(t *theme.Theme, widthHint, heightHint int) {
m.MeasuredSize = image.Point{}
}
func (m *LeafEmbed) Layout(t *theme.Theme) {}
func (m *LeafEmbed) Paint(ctx *PaintContext, origin image.Point) error {
m.Marks.UnmarkNeedsPaint()
return nil
}
func (m *LeafEmbed) PaintBase(ctx *PaintBaseContext, origin image.Point) error {
m.Marks.UnmarkNeedsPaintBase()
return nil
}
func (m *LeafEmbed) OnChildMarked(child Node, newMarks Marks) {}
func (m *LeafEmbed) OnLifecycleEvent(e lifecycle.Event) {}
func (m *LeafEmbed) OnInputEvent(e interface{}, origin image.Point) EventHandled { return NotHandled }
// ShellEmbed is designed to be embedded in struct types for nodes with at most
// one child.
type ShellEmbed struct{ Embed }
func (m *ShellEmbed) Insert(c, nextSibling Node) {
if m.FirstChild != nil {
panic("node: Insert called for a shell parent that already has a child")
}
m.insert(c, nextSibling)
}
func (m *ShellEmbed) Remove(c Node) { m.remove(c) }
func (m *ShellEmbed) Measure(t *theme.Theme, widthHint, heightHint int) {
if c := m.FirstChild; c != nil {
c.Wrapper.Measure(t, widthHint, heightHint)
m.MeasuredSize = c.MeasuredSize
} else {
m.MeasuredSize = image.Point{}
}
}
func (m *ShellEmbed) Layout(t *theme.Theme) {
if c := m.FirstChild; c != nil {
c.Rect = m.Rect.Sub(m.Rect.Min)
c.Wrapper.Layout(t)
}
}
func (m *ShellEmbed) Paint(ctx *PaintContext, origin image.Point) error {
m.Marks.UnmarkNeedsPaint()
if c := m.FirstChild; c != nil {
return c.Wrapper.Paint(ctx, origin.Add(m.Rect.Min))
}
return nil
}
func (m *ShellEmbed) PaintBase(ctx *PaintBaseContext, origin image.Point) error {
m.Marks.UnmarkNeedsPaintBase()
if c := m.FirstChild; c != nil {
return c.Wrapper.PaintBase(ctx, origin.Add(m.Rect.Min))
}
return nil
}
func (m *ShellEmbed) OnChildMarked(child Node, newMarks Marks) {
m.Mark(newMarks)
}
func (m *ShellEmbed) OnLifecycleEvent(e lifecycle.Event) {
if c := m.FirstChild; c != nil {
c.Wrapper.OnLifecycleEvent(e)
}
}
func (m *ShellEmbed) OnInputEvent(e interface{}, origin image.Point) EventHandled {
if c := m.FirstChild; c != nil {
return c.Wrapper.OnInputEvent(e, origin.Add(m.Rect.Min))
}
return NotHandled
}
// ContainerEmbed is designed to be embedded in struct types for nodes with any
// number of children.
type ContainerEmbed struct{ Embed }
func (m *ContainerEmbed) Insert(c, nextSibling Node) { m.insert(c, nextSibling) }
func (m *ContainerEmbed) Remove(c Node) { m.remove(c) }
func (m *ContainerEmbed) Measure(t *theme.Theme, widthHint, heightHint int) {
mSize := image.Point{}
for c := m.FirstChild; c != nil; c = c.NextSibling {
c.Wrapper.Measure(t, NoHint, NoHint)
if mSize.X < c.MeasuredSize.X {
mSize.X = c.MeasuredSize.X
}
if mSize.Y < c.MeasuredSize.Y {
mSize.Y = c.MeasuredSize.Y
}
}
m.MeasuredSize = mSize
}
func (m *ContainerEmbed) Layout(t *theme.Theme) {
for c := m.FirstChild; c != nil; c = c.NextSibling {
c.Rect = image.Rectangle{Max: c.MeasuredSize}
c.Wrapper.Layout(t)
}
}
func (m *ContainerEmbed) Paint(ctx *PaintContext, origin image.Point) error {
m.Marks.UnmarkNeedsPaint()
origin = origin.Add(m.Rect.Min)
for c := m.FirstChild; c != nil; c = c.NextSibling {
if err := c.Wrapper.Paint(ctx, origin); err != nil {
return err
}
}
return nil
}
func (m *ContainerEmbed) PaintBase(ctx *PaintBaseContext, origin image.Point) error {
m.Marks.UnmarkNeedsPaintBase()
origin = origin.Add(m.Rect.Min)
for c := m.FirstChild; c != nil; c = c.NextSibling {
if err := c.Wrapper.PaintBase(ctx, origin); err != nil {
return err
}
}
return nil
}
func (m *ContainerEmbed) OnChildMarked(child Node, newMarks Marks) {
m.Mark(newMarks)
}
func (m *ContainerEmbed) OnLifecycleEvent(e lifecycle.Event) {
for c := m.FirstChild; c != nil; c = c.NextSibling {
c.Wrapper.OnLifecycleEvent(e)
}
}
func (m *ContainerEmbed) OnInputEvent(e interface{}, origin image.Point) EventHandled {
origin = origin.Add(m.Rect.Min)
var p image.Point
switch e := e.(type) {
case gesture.Event:
p = image.Point{
X: int(e.CurrentPos.X) - origin.X,
Y: int(e.CurrentPos.Y) - origin.Y,
}
case mouse.Event:
p = image.Point{
X: int(e.X) - origin.X,
Y: int(e.Y) - origin.Y,
}
}
// Iterate backwards. Later children have priority over earlier children,
// as later ones are usually drawn over earlier ones.
for c := m.LastChild; c != nil; c = c.PrevSibling {
if p.In(c.Rect) && c.Wrapper.OnInputEvent(e, origin) == Handled {
return Handled
}
}
return NotHandled
}
// Embed is the common data structure for each node in a widget tree.
type Embed struct {
// Wrapper is the outer type that wraps (embeds) this type. It should not
// be nil.
Wrapper Node
// Parent, FirstChild, LastChild, PrevSibling and NextSibling describe the
// widget tree structure.
//
// These fields are exported to enable walking the node tree, but they
// should not be modified directly. Instead, call the Insert and Remove
// methods, which keeps the tree structure consistent.
Parent, FirstChild, LastChild, PrevSibling, NextSibling *Embed
// LayoutData is layout-specific data for this node. Its type is determined
// by its parent node's type. For example, each child of a Flow may hold a
// FlowLayoutData in this field.
LayoutData interface{}
// TODO: add commentary about the Measure / Layout / Paint model, and about
// the lifetime of the MeasuredSize and Rect fields, and when user code can
// access and/or modify them. At some point a new cycle begins, a call to
// measure is necessary, and using MeasuredSize is incorrect (unless you're
// trying to recall something about the past).
// MeasuredSize is the widget's natural size, in pixels, as calculated by
// the most recent Measure call.
MeasuredSize image.Point
// Rect is the widget's position and actual (as opposed to natural) size,
// in pixels, as calculated by the most recent Layout call on its parent
// node. A parent may lay out a child at a size different to its natural
// size in order to satisfy a layout constraint, such as a row of buttons
// expanding to fill a panel's width.
//
// The position (Rectangle.Min) is relative to its parent node. This is not
// necessarily the same as relative to the screen's, window's or image
// buffer's origin.
Rect image.Rectangle
// Marks are a bitfield of node state, such as whether it needs measure,
// layout or paint.
Marks Marks
}
func (m *Embed) Wrappee() *Embed { return m }
// TODO: should insert and remove call Mark(MarkNeedsMeasureLayout | MarkNeedsPaint)?
func (m *Embed) insert(c, nextSibling Node) {
n := c.Wrappee()
if n.Parent != nil || n.PrevSibling != nil || n.NextSibling != nil {
panic("node: Insert called for an attached child")
}
n.Parent = m
if nextSibling == nil {
last := m.LastChild
if last != nil {
last.NextSibling = n
} else {
m.FirstChild = n
}
m.LastChild = n
n.PrevSibling = last
return
}
o := nextSibling.Wrappee()
if o.Parent != m {
panic("node: Insert called for a non-sibling nextSibling node")
}
if o.PrevSibling == nil {
o.PrevSibling = n
n.NextSibling = o
m.FirstChild = n
return
}
o.PrevSibling.NextSibling = n
n.PrevSibling = o.PrevSibling
n.NextSibling = o
o.PrevSibling = n
}
func (m *Embed) remove(c Node) {
n := c.Wrappee()
if n.Parent != m {
panic("node: Remove called for a non-child node")
}
if m.FirstChild == n {
m.FirstChild = n.NextSibling
}
if n.NextSibling != nil {
n.NextSibling.PrevSibling = n.PrevSibling
}
if m.LastChild == n {
m.LastChild = n.PrevSibling
}
if n.PrevSibling != nil {
n.PrevSibling.NextSibling = n.NextSibling
}
n.Parent = nil
n.PrevSibling = nil
n.NextSibling = nil
}
func (m *Embed) Mark(marks Marks) {
oldMarks := m.Marks
m.Marks |= marks
changedMarks := m.Marks ^ oldMarks
if changedMarks != 0 && m.Parent != nil {
m.Parent.Wrapper.OnChildMarked(m.Wrapper, changedMarks)
}
}
// Marks are a bitfield of node state, such as whether it needs measure, layout
// or paint.
type Marks uint32
const (
// MarkNeedsMeasureLayout marks this node as needing Measure and Layout
// calls.
MarkNeedsMeasureLayout = Marks(1 << 0)
// TODO: use this.
// MarkNeedsPaint marks this node as needing a Paint call.
MarkNeedsPaint = Marks(1 << 1)
// MarkNeedsPaintBase marks this node as needing a PaintBase call.
MarkNeedsPaintBase = Marks(1 << 2)
)
func (m Marks) NeedsMeasureLayout() bool { return m&MarkNeedsMeasureLayout != 0 }
func (m Marks) NeedsPaint() bool { return m&MarkNeedsPaint != 0 }
func (m Marks) NeedsPaintBase() bool { return m&MarkNeedsPaintBase != 0 }
func (m *Marks) UnmarkNeedsMeasureLayout() { *m &^= MarkNeedsMeasureLayout }
func (m *Marks) UnmarkNeedsPaint() { *m &^= MarkNeedsPaint }
func (m *Marks) UnmarkNeedsPaintBase() { *m &^= MarkNeedsPaintBase }