8f17163a13a0da73271e256b9e31aa6e8e08c232 — Elias Naur a month ago 6d13397
ui/layout: rename List.Elem to End to match Stack and Flex

Add more documentation while we're here.

Signed-off-by: Elias Naur <mail@eliasnaur.com>
2 files changed, 27 insertions(+), 13 deletions(-)

M ui/layout/flex.go
M ui/layout/list.go
M ui/layout/flex.go => ui/layout/flex.go +15 -4
@@ 9,7 9,7 @@ "gioui.org/ui/f32"
  )
  
- // Flex lays out interface elements along an axis,
+ // Flex lays out child elements along an axis,
  // according to alignment and weights.
  type Flex struct {
  	// Axis is the main axis, either Horizontal or Vertical.


@@ 30,11 30,14 @@ maxBaseline int
  }
  
+ // FlexChild is the layout result of a call to Rigid or
+ // Flexible.
  type FlexChild struct {
  	macro ui.MacroOp
  	dims  Dimens
  }
  
+ // Spacing determine the spacing mode for a Flex.
  type Spacing uint8
  
  type flexMode uint8


@@ 46,13 49,13 @@ SpaceStart
  	// SpaceSides shares space between the start and end.
  	SpaceSides
- 	// SpaceAround distributes space evenly between elements,
+ 	// SpaceAround distributes space evenly between children,
  	// with half as much space at the start and end.
  	SpaceAround
- 	// SpaceBetween distributes space evenly between elements,
+ 	// SpaceBetween distributes space evenly between children,
  	// leaving no space at the start and end.
  	SpaceBetween
- 	// SpaceEvenly distributes space evenly between elements and
+ 	// SpaceEvenly distributes space evenly between children and
  	// at the start and end.
  	SpaceEvenly
  )


@@ 89,6 92,8 @@ f.macro.Record(f.ops)
  }
  
+ // Rigid begins a child and return its constraints. The main axis is constrained
+ // to the range from 0 to the remaining space.
  func (f *Flex) Rigid() Constraints {
  	f.begin(modeRigid)
  	mainc := axisMainConstraint(f.Axis, f.cs)


@@ 99,6 104,8 @@ return axisConstraints(f.Axis, Constraint{Max: mainMax}, axisCrossConstraint(f.Axis, f.cs))
  }
  
+ // Flexible is like Rigid, where the main axis size is also constrained to a
+ // fraction of the space not taken up by Rigid children.
  func (f *Flex) Flexible(weight float32) Constraints {
  	f.begin(modeFlex)
  	mainc := axisMainConstraint(f.Axis, f.cs)


@@ 115,6 122,8 @@ return axisConstraints(f.Axis, submainc, axisCrossConstraint(f.Axis, f.cs))
  }
  
+ // End a child by specifying its dimensions. Pass the returned layout result
+ // to Layout.
  func (f *Flex) End(dims Dimens) FlexChild {
  	if f.mode <= modeBegun {
  		panic("End called without an active child")


@@ 135,6 144,8 @@ return FlexChild{f.macro, dims}
  }
  
+ // Layout a list of children. The order of the children determines their laid
+ // out order.
  func (f *Flex) Layout(children ...FlexChild) Dimens {
  	mainc := axisMainConstraint(f.Axis, f.cs)
  	crossSize := axisCrossConstraint(f.Axis, f.cs).Constrain(f.maxCross)

M ui/layout/list.go => ui/layout/list.go +12 -9
@@ 58,10 58,10 @@   const inf = 1e6
  
- // Init prepares the list for iterating through its elements with Next.
+ // Init prepares the list for iterating through its children with Next.
  func (l *List) Init(cfg ui.Config, q input.Queue, ops *ui.Ops, cs Constraints, len int) {
  	if l.more {
- 		panic("unfinished element")
+ 		panic("unfinished child")
  	}
  	l.config = cfg
  	l.queue = q


@@ 80,6 80,7 @@ l.Next()
  }
  
+ // Dragging reports whether the List is being dragged.
  func (l *List) Dragging() bool {
  	return l.scroll.Dragging()
  }


@@ 95,7 96,7 @@ l.offset += d
  }
  
- // Next advances the list to the next element.
+ // Next advances to the next child.
  func (l *List) Next() {
  	if !l.more {
  		panic("end of list reached")


@@ 112,16 113,17 @@ l.child.Record(l.ops)
  }
  
- // Index is the current element index.
+ // Index is current child's position in the underlying list.
  func (l *List) Index() int {
  	return l.index
  }
  
- // Constraints is the constraints for the current element.
+ // Constraints is the constraints for the current child.
  func (l *List) Constraints() Constraints {
  	return axisConstraints(l.Axis, Constraint{Max: inf}, axisCrossConstraint(l.Axis, l.cs))
  }
  
+ // More reports whether more children are needed.
  func (l *List) More() bool {
  	return l.more
  }


@@ 150,8 152,8 @@ return 0, false
  }
  
- // Elem completes an element.
- func (l *List) Elem(dims Dimens) {
+ // End the current child by specifying its dimensions.
+ func (l *List) End(dims Dimens) {
  	l.child.Stop()
  	child := scrollChild{dims.Size, l.child}
  	switch l.dir {


@@ 166,14 168,15 @@ l.maxSize += mainSize
  		l.children = append([]scrollChild{child}, l.children...)
  	default:
- 		panic("call Next before Elem")
+ 		panic("call Next before End")
  	}
  	l.dir = iterateNone
  }
  
+ // Layout the List and return its dimensions.
  func (l *List) Layout() Dimens {
  	if l.more {
- 		panic("unfinished element")
+ 		panic("unfinished child")
  	}
  	mainc := axisMainConstraint(l.Axis, l.cs)
  	for len(l.children) > 0 {