layout

package
v0.0.23 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 29, 2022 License: Unlicense, MIT, Unlicense Imports: 10 Imported by: 0

Documentation

Overview

Package layout implements layouts common to GUI programs.

Constraints and dimensions

Constraints and dimensions form the interface between layouts and interface child elements. This package operates on Widgets, functions that compute Dimensions from a a set of constraints for acceptable widths and heights. Both the constraints and dimensions are maintained in an implicit Context to keep the Widget declaration short.

For example, to add space above a widget: 

var gtx layout.Context

// Configure a top inset.
inset := layout.Inset{Top: unit.Dp(8), ...}
// Use the inset to lay out a widget.
inset.Layout(gtx, func() {
	// Lay out widget and determine its size given the constraints
	// in gtx.Constraints.
	...
	return layout.Dimensions{...}
})

Note that the example does not generate any garbage even though the Inset is transient. Layouts that don't accept user input are designed to not escape to the heap during their use.

Layout operations are recursive: a child in a layout operation can itself be another layout. That way, complex user interfaces can be created from a few generic layouts.

This example both aligns and insets a child: 

inset := layout.Inset{...}
inset.Layout(gtx, func(gtx layout.Context) layout.Dimensions {
	align := layout.Alignment(...)
	return align.Layout(gtx, func(gtx layout.Context) layout.Dimensions {
		return widget.Layout(gtx, ...)
	})
})

More complex layouts such as Stack and Flex lay out multiple children, and stateful layouts such as List accept user input.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func FPt 

func FPt(p image.Point) f32.Point

FPt converts an point to a f32.Point.

func FRect 

func FRect(r image.Rectangle) f32.Rectangle

FRect converts a rectangle to a f32.Rectangle.

Types

type Alignment 

type Alignment uint8

Alignment is the mutual alignment of a list of widgets. 

const (
	Start Alignment = iota
	End
	Middle
	Baseline
)

func (Alignment) String 

func (a Alignment) String() string

type Axis 

type Axis uint8

Axis is the Horizontal or Vertical direction. 

const (
	Horizontal Axis = iota
	Vertical
)

func (Axis) Convert 

func (a Axis) Convert(pt image.Point) image.Point

Convert a point in (x, y) coordinates to (main, cross) coordinates, or vice versa. Specifically, Convert((x, y)) returns (x, y) unchanged for the horizontal axis, or (y, x) for the vertical axis.

func (Axis) String 

func (a Axis) String() string

type Constraints 

type Constraints struct {
	Min, Max image.Point
}

Constraints represent the minimum and maximum size of a widget.

A widget does not have to treat its constraints as "hard". For example, if it's passed a constraint with a minimum size that's smaller than its actual minimum size, it should return its minimum size dimensions instead. Parent widgets should deal appropriately with child widgets that return dimensions that do not fit their constraints (for example, by clipping).

func Exact 

func Exact(size image.Point) Constraints

Exact returns the Constraints with the minimum and maximum size set to size.

func (Constraints) Constrain 

func (c Constraints) Constrain(size image.Point) image.Point

Constrain a size so each dimension is in the range [min;max].

type Context 

type Context struct {
	// Constraints track the constraints for the active widget or
	// layout.
	Constraints Constraints

	Metric unit.Metric
	// By convention, a nil Queue is a signal to widgets to draw themselves
	// in a disabled state.
	Queue event.Queue
	// Now is the animation time.
	Now time.Time

	*op.Ops
}

Context carries the state needed by almost all layouts and widgets. A zero value Context never returns events, map units to pixels with a scale of 1.0, and returns the zero time from Now.

func NewContext 

func NewContext(ops *op.Ops, e system.FrameEvent) Context

NewContext is a shorthand for 

Context{
  Ops: ops,
  Now: e.Now,
  Queue: e.Queue,
  Config: e.Config,
  Constraints: Exact(e.Size),
}

NewContext calls ops.Reset and adjusts ops for e.Insets.

func (Context) Disabled 

func (c Context) Disabled() Context

Disabled returns a copy of this context with a nil Queue, blocking events to widgets using it.

By convention, a nil Queue is a signal to widgets to draw themselves in a disabled state.

func (Context) Events 

func (c Context) Events(k event.Tag) []event.Event

Events returns the events available for the key. If no queue is configured, Events returns nil.

func (Context) Px 

func (c Context) Px(v unit.Value) int

Px maps the value to pixels.

type Dimensions 

type Dimensions struct {
	Size     image.Point
	Baseline int
}

Dimensions are the resolved size and baseline for a widget.

Baseline is the distance from the bottom of a widget to the baseline of any text it contains (or 0). The purpose is to be able to align text that span multiple widgets.

type Direction 

type Direction uint8

Direction is the alignment of widgets relative to a containing space.

Example 
package main

import (
	"fmt"
	"image"

	"github.com/cybriq/p9/pkg/gel/gio/layout"
	"github.com/cybriq/p9/pkg/gel/gio/op"
)

func main() {
	gtx := layout.Context{
		Ops: new(op.Ops),
		// Rigid constraints with both minimum and maximum set.
		Constraints: layout.Exact(image.Point{X: 100, Y: 100}),
	}

	dims := layout.Center.Layout(
		gtx,
		func(gtx layout.Context) layout.Dimensions {
			// Lay out a 50x50 sized widget.
			dims := layoutWidget(gtx, 50, 50)
			fmt.Println(dims.Size)
			return dims
		},
	)

	fmt.Println(dims.Size)

}

func layoutWidget(ctx layout.Context, width, height int) layout.Dimensions {
	return layout.Dimensions{
		Size: image.Point{
			X: width,
			Y: height,
		},
	}
}

Output:

(50,50)
(100,100)

const (
	NW Direction = iota
	N
	NE
	E
	SE
	S
	SW
	W
	Center
)

func (Direction) Layout 

func (d Direction) Layout(gtx Context, w Widget) Dimensions

Layout a widget according to the direction. The widget is called with the context constraints minimum cleared.

func (Direction) Position 

func (d Direction) Position(widget, bounds image.Point) image.Point

Position calculates widget position according to the direction.

func (Direction) String 

func (d Direction) String() string

type Flex 

type Flex struct {
	// Axis is the main axis, either Horizontal or Vertical.
	Axis Axis
	// Spacing controls the distribution of space left after
	// layout.
	Spacing Spacing
	// Alignment is the alignment in the cross axis.
	Alignment Alignment
	// WeightSum is the sum of weights used for the weighted
	// size of Flexed children. If WeightSum is zero, the sum
	// of all Flexed weights is used.
	WeightSum float32
}

Flex lays out child elements along an axis, according to alignment and weights.

Example 
package main

import (
	"fmt"
	"image"

	"github.com/cybriq/p9/pkg/gel/gio/layout"
	"github.com/cybriq/p9/pkg/gel/gio/op"
)

func main() {
	gtx := layout.Context{
		Ops: new(op.Ops),
		// Rigid constraints with both minimum and maximum set.
		Constraints: layout.Exact(image.Point{X: 100, Y: 100}),
	}

	layout.Flex{WeightSum: 2}.Layout(
		gtx,
		// Rigid 10x10 widget.
		layout.Rigid(
			func(gtx layout.Context) layout.Dimensions {
				fmt.Printf("Rigid: %v\n", gtx.Constraints)
				return layoutWidget(gtx, 10, 10)
			},
		),
		// Child with 50% space allowance.
		layout.Flexed(
			1, func(gtx layout.Context) layout.Dimensions {
				fmt.Printf("50%%: %v\n", gtx.Constraints)
				return layoutWidget(gtx, 10, 10)
			},
		),
	)

}

func layoutWidget(ctx layout.Context, width, height int) layout.Dimensions {
	return layout.Dimensions{
		Size: image.Point{
			X: width,
			Y: height,
		},
	}
}

Output:

Rigid: {(0,100) (100,100)}
50%: {(45,100) (45,100)}

func (Flex) Layout 

func (f Flex) Layout(gtx Context, children ...FlexChild) Dimensions

Layout a list of children. The position of the children are determined by the specified order, but Rigid children are laid out before Flexed children.

type FlexChild 

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

FlexChild is the descriptor for a Flex child.

func Flexed 

func Flexed(weight float32, widget Widget) FlexChild

Flexed returns a Flex child forced to take up weight fraction of the space left over from Rigid children. The fraction is weight divided by either the weight sum of all Flexed children or the Flex WeightSum if non zero.

func Rigid 

func Rigid(widget Widget) FlexChild

Rigid returns a Flex child with a maximal constraint of the remaining space.

type Inset 

type Inset struct {
	Top, Right, Bottom, Left unit.Value
}

Inset adds space around a widget by decreasing its maximum constraints. The minimum constraints will be adjusted to ensure they do not exceed the maximum.

Example 
package main

import (
	"fmt"
	"image"

	"github.com/cybriq/p9/pkg/gel/gio/layout"
	"github.com/cybriq/p9/pkg/gel/gio/op"
	"github.com/cybriq/p9/pkg/gel/gio/unit"
)

func main() {
	gtx := layout.Context{
		Ops: new(op.Ops),
		// Loose constraints with no minimal size.
		Constraints: layout.Constraints{
			Max: image.Point{X: 100, Y: 100},
		},
	}

	// Inset all edges by 10.
	inset := layout.UniformInset(unit.Dp(10))
	dims := inset.Layout(
		gtx, func(gtx layout.Context) layout.Dimensions {
			// Lay out a 50x50 sized widget.
			dims := layoutWidget(gtx, 50, 50)
			fmt.Println(dims.Size)
			return dims
		},
	)

	fmt.Println(dims.Size)

}

func layoutWidget(ctx layout.Context, width, height int) layout.Dimensions {
	return layout.Dimensions{
		Size: image.Point{
			X: width,
			Y: height,
		},
	}
}

Output:

(50,50)
(70,70)

func UniformInset 

func UniformInset(v unit.Value) Inset

UniformInset returns an Inset with a single inset applied to all edges.

func (Inset) Layout 

func (in Inset) Layout(gtx Context, w Widget) Dimensions

Layout a widget.

type List 

type List struct {
	Axis Axis
	// ScrollToEnd instructs the list to stay scrolled to the far end position
	// once reached. A List with ScrollToEnd == true and Position.BeforeEnd ==
	// false draws its content with the last item at the bottom of the list
	// area.
	ScrollToEnd bool
	// Alignment is the cross axis alignment of list elements.
	Alignment Alignment

	// Position is updated during Layout. To save the list scroll position,
	// just save Position after Layout finishes. To scroll the list
	// programmatically, update Position (e.g. restore it from a saved value)
	// before calling Layout.
	Position Position
	// contains filtered or unexported fields
}

List displays a subsection of a potentially infinitely large underlying list. List accepts user input to scroll the subsection.

Example 
package main

import (
	"fmt"
	"image"

	"github.com/cybriq/p9/pkg/gel/gio/layout"
	"github.com/cybriq/p9/pkg/gel/gio/op"
)

func main() {
	gtx := layout.Context{
		Ops: new(op.Ops),
		// Rigid constraints with both minimum and maximum set.
		Constraints: layout.Exact(image.Point{X: 100, Y: 100}),
	}

	// The list is 1e6 elements, but only 5 fit the constraints.
	const listLen = 1e6

	var list layout.List
	list.Layout(
		gtx, listLen,
		func(gtx layout.Context, i int) layout.Dimensions {
			return layoutWidget(gtx, 20, 20)
		},
	)

	fmt.Println(list.Position.Count)

}

func layoutWidget(ctx layout.Context, width, height int) layout.Dimensions {
	return layout.Dimensions{
		Size: image.Point{
			X: width,
			Y: height,
		},
	}
}

Output:

5

func (*List) Dragging 

func (l *List) Dragging() bool

Dragging reports whether the List is being dragged.

func (*List) Layout 

func (l *List) Layout(gtx Context, len int, w ListElement) Dimensions

Layout the List.

type ListElement 

type ListElement func(gtx Context, index int) Dimensions

ListElement is a function that computes the dimensions of a list element.

type Position 

type Position struct {
	// BeforeEnd tracks whether the List position is before the very end. We
	// use "before end" instead of "at end" so that the zero value of a
	// Position struct is useful.
	//
	// When laying out a list, if ScrollToEnd is true and BeforeEnd is false,
	// then First and Offset are ignored, and the list is drawn with the last
	// item at the bottom. If ScrollToEnd is false then BeforeEnd is ignored.
	BeforeEnd bool
	// First is the index of the first visible child.
	First int
	// Offset is the distance in pixels from the top edge to the child at index
	// First.
	Offset int
	// OffsetLast is the signed distance in pixels from the bottom edge to the
	// bottom edge of the child at index First+Count.
	OffsetLast int
	// Count is the number of visible children.
	Count int
}

Position is a List scroll offset represented as an offset from the top edge of a child element.

type Spacer 

type Spacer struct {
	Width, Height unit.Value
}

Spacer adds space between widgets.

func (Spacer) Layout 

func (s Spacer) Layout(gtx Context) Dimensions

type Spacing 

type Spacing uint8

Spacing determine the spacing mode for a Flex. 

const (
	// SpaceEnd leaves space at the end.
	SpaceEnd Spacing = iota
	// SpaceStart leaves space at the start.
	SpaceStart
	// SpaceSides shares space between the start and end.
	SpaceSides
	// SpaceAround distributes space evenly between children,
	// with half as much space at the start and end.
	SpaceAround
	// SpaceBetween distributes space evenly between children,
	// leaving no space at the start and end.
	SpaceBetween
	// SpaceEvenly distributes space evenly between children and
	// at the start and end.
	SpaceEvenly
)

func (Spacing) String 

func (s Spacing) String() string

type Stack 

type Stack struct {
	// Alignment is the direction to align children
	// smaller than the available space.
	Alignment Direction
}

Stack lays out child elements on top of each other, according to an alignment direction.

Example 
package main

import (
	"fmt"
	"image"

	"github.com/cybriq/p9/pkg/gel/gio/layout"
	"github.com/cybriq/p9/pkg/gel/gio/op"
)

func main() {
	gtx := layout.Context{
		Ops: new(op.Ops),
		Constraints: layout.Constraints{
			Max: image.Point{X: 100, Y: 100},
		},
	}

	layout.Stack{}.Layout(
		gtx,
		// Force widget to the same size as the second.
		layout.Expanded(
			func(gtx layout.Context) layout.Dimensions {
				fmt.Printf("Expand: %v\n", gtx.Constraints)
				return layoutWidget(gtx, 10, 10)
			},
		),
		// Rigid 50x50 widget.
		layout.Stacked(
			func(gtx layout.Context) layout.Dimensions {
				return layoutWidget(gtx, 50, 50)
			},
		),
	)

}

func layoutWidget(ctx layout.Context, width, height int) layout.Dimensions {
	return layout.Dimensions{
		Size: image.Point{
			X: width,
			Y: height,
		},
	}
}

Output:

Expand: {(50,50) (100,100)}

func (Stack) Layout 

func (s Stack) Layout(gtx Context, children ...StackChild) Dimensions

Layout a stack of children. The position of the children are determined by the specified order, but Stacked children are laid out before Expanded children.

type StackChild 

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

StackChild represents a child for a Stack layout.

func Expanded 

func Expanded(w Widget) StackChild

Expanded returns a Stack child with the minimum constraints set to the largest Stacked child. The maximum constraints are set to the same as passed to Stack.Layout.

func Stacked 

func Stacked(w Widget) StackChild

Stacked returns a Stack child that is laid out with no minimum constraints and the maximum constraints passed to Stack.Layout.

type Widget 

type Widget func(gtx Context) Dimensions

Widget is a function scope for drawing, processing events and computing dimensions for a user interface element.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.