From d4b9ffb04616988926389f8508f363716bee7d49 Mon Sep 17 00:00:00 2001 From: Sasha Koshka Date: Thu, 20 Apr 2023 01:37:06 -0400 Subject: [PATCH] Improved documentation (and added missing methods) --- elements/box.go | 14 ++++++++++---- elements/container.go | 6 ++++++ elements/document.go | 12 ++++++++++++ elements/scroll.go | 26 ++++++++++++++++++++++---- elements/scrollbar.go | 1 + 5 files changed, 51 insertions(+), 8 deletions(-) diff --git a/elements/box.go b/elements/box.go index dab9117..cdfcc21 100644 --- a/elements/box.go +++ b/elements/box.go @@ -9,10 +9,10 @@ import "git.tebibyte.media/sashakoshka/tomo/default/theme" // Space is a list of spacing configurations that can be passed to some // containers. type Space int; const ( - SpaceNone = 0 - SpacePadding = 1 - SpaceMargin = 2 - SpaceBoth = SpacePadding | SpaceMargin + SpaceNone Space = 0 + SpacePadding Space = 1 + SpaceMargin Space = 2 + SpaceBoth Space = SpacePadding | SpaceMargin ) // Includes returns whether a spacing value has been or'd with another spacing @@ -62,6 +62,7 @@ func NewVBox (space Space, children ...tomo.Element) (element *Box) { return } +// Draw causes the element to draw to the specified destination canvas. func (element *Box) Draw (destination canvas.Canvas) { rocks := make([]image.Rectangle, element.entity.CountChildren()) for index := 0; index < element.entity.CountChildren(); index ++ { @@ -74,6 +75,7 @@ func (element *Box) Draw (destination canvas.Canvas) { } } +// Layout causes this element to perform a layout operation. func (element *Box) Layout () { margin := element.theme.Margin(tomo.PatternBackground) padding := element.theme.Padding(tomo.PatternBackground) @@ -118,10 +120,14 @@ func (element *Box) Layout () { } } +// AdoptExpand adds one or more elements to the box. These elements will be +// expanded to fill in empty space. func (element *Box) AdoptExpand (children ...tomo.Element) { element.adopt(true, children...) } +// DrawBackground draws this element's background pattern to the specified +// destination canvas. func (element *Box) DrawBackground (destination canvas.Canvas) { element.entity.DrawBackground(destination) } diff --git a/elements/container.go b/elements/container.go index 49d2c88..b8a7f61 100644 --- a/elements/container.go +++ b/elements/container.go @@ -14,10 +14,12 @@ type container struct { minimumSize func () } +// Entity returns this element's entity. func (container *container) Entity () tomo.Entity { return container.entity } +// Adopt adds one or more elements to the container. func (container *container) Adopt (children ...tomo.Element) { container.adopt(false, children...) } @@ -36,6 +38,7 @@ func (container *container) adopt (expand bool, children ...tomo.Element) { container.entity.InvalidateLayout() } +// Disown removes one or more elements from the container. func (container *container) Disown (children ...tomo.Element) { for _, child := range children { index := container.entity.IndexOf(child) @@ -48,6 +51,7 @@ func (container *container) Disown (children ...tomo.Element) { container.entity.InvalidateLayout() } +// DisownAll removes all elements from the container. func (container *container) DisownAll () { func () { for index := 0; index < container.entity.CountChildren(); index ++ { @@ -61,11 +65,13 @@ func (container *container) DisownAll () { container.entity.InvalidateLayout() } +// Child returns the child at the specified index. func (container *container) Child (index int) tomo.Element { if index < 0 || index >= container.entity.CountChildren() { return nil } return container.entity.Child(index) } +// CountChildren returns the amount of children in this container. func (container *container) CountChildren () int { return container.entity.CountChildren() } diff --git a/elements/document.go b/elements/document.go index 9954322..30a368a 100644 --- a/elements/document.go +++ b/elements/document.go @@ -11,6 +11,9 @@ type documentEntity interface { tomo.ScrollableEntity } +// Document is a scrollable container capcable of laying out flexible child +// elements. Children can be added either inline (similar to an HTML/CSS inline +// element), or expanding (similar to an HTML/CSS block element). type Document struct { container entity documentEntity @@ -23,6 +26,7 @@ type Document struct { onScrollBoundsChange func () } +// NewDocument creates a new document container. func NewDocument (children ...tomo.Element) (element *Document) { element = &Document { } element.theme.Case = tomo.C("tomo", "document") @@ -34,6 +38,7 @@ func NewDocument (children ...tomo.Element) (element *Document) { return } +// Draw causes the element to draw to the specified destination canvas. func (element *Document) Draw (destination canvas.Canvas) { rocks := make([]image.Rectangle, element.entity.CountChildren()) for index := 0; index < element.entity.CountChildren(); index ++ { @@ -46,6 +51,7 @@ func (element *Document) Draw (destination canvas.Canvas) { } } +// Layout causes this element to perform a layout operation. func (element *Document) Layout () { if element.scroll.Y > element.maxScrollHeight() { element.scroll.Y = element.maxScrollHeight() @@ -112,10 +118,14 @@ func (element *Document) Layout () { } } +// Adopt adds one or more elements to the container, placing each on its own +// line. func (element *Document) Adopt (children ...tomo.Element) { element.adopt(true, children...) } +// AdoptInline adds one or more elements to the container, packing multiple +// elements onto the same line(s). func (element *Document) AdoptInline (children ...tomo.Element) { element.adopt(false, children...) } @@ -126,6 +136,8 @@ func (element *Document) HandleChildFlexibleHeightChange (child tomo.Flexible) { element.entity.InvalidateLayout() } +// DrawBackground draws this element's background pattern to the specified +// destination canvas. func (element *Document) DrawBackground (destination canvas.Canvas) { element.entity.DrawBackground(destination) } diff --git a/elements/scroll.go b/elements/scroll.go index c7a7eb6..6f0de70 100644 --- a/elements/scroll.go +++ b/elements/scroll.go @@ -7,11 +7,12 @@ import "git.tebibyte.media/sashakoshka/tomo/canvas" import "git.tebibyte.media/sashakoshka/tomo/default/theme" import "git.tebibyte.media/sashakoshka/tomo/default/config" +// ScrollMode specifies which sides of a Scroll have scroll bars. type ScrollMode int; const ( - ScrollNeither ScrollMode = 0 - ScrollVertical = 1 - ScrollHorizontal = 2 - ScrollBoth = ScrollVertical | ScrollHorizontal + ScrollNeither ScrollMode = 0 + ScrollVertical ScrollMode = 1 + ScrollHorizontal ScrollMode = 2 + ScrollBoth ScrollMode = ScrollVertical | ScrollHorizontal ) // Includes returns whether a scroll mode has been or'd with another scroll @@ -20,6 +21,8 @@ func (mode ScrollMode) Includes (sub ScrollMode) bool { return (mode & sub) > 0 } +// Scroll adds scroll bars to any scrollable element. It also captures scroll +// wheel input. type Scroll struct { entity tomo.ContainerEntity @@ -31,6 +34,7 @@ type Scroll struct { theme theme.Wrapped } +// NewScroll creates a new scroll element. func NewScroll (mode ScrollMode, child tomo.Scrollable) (element *Scroll) { element = &Scroll { } element.theme.Case = tomo.C("tomo", "scroll") @@ -69,10 +73,12 @@ func NewScroll (mode ScrollMode, child tomo.Scrollable) (element *Scroll) { return } +// Entity returns this element's entity. func (element *Scroll) Entity () tomo.Entity { return element.entity } +// Draw causes the element to draw to the specified destination canvas. func (element *Scroll) Draw (destination canvas.Canvas) { if element.horizontal != nil && element.vertical != nil { bounds := element.entity.Bounds() @@ -85,6 +91,7 @@ func (element *Scroll) Draw (destination canvas.Canvas) { } } +// Layout causes this element to perform a layout operation. func (element *Scroll) Layout () { bounds := element.entity.Bounds() child := bounds @@ -125,10 +132,13 @@ func (element *Scroll) Layout () { } } +// DrawBackground draws this element's background pattern to the specified +// destination canvas. func (element *Scroll) DrawBackground (destination canvas.Canvas) { element.entity.DrawBackground(destination) } +// Adopt sets this element's child. If nil is passed, any child is removed. func (element *Scroll) Adopt (child tomo.Scrollable) { if element.child != nil { element.entity.Disown(element.entity.IndexOf(element.child)) @@ -144,6 +154,12 @@ func (element *Scroll) Adopt (child tomo.Scrollable) { element.entity.InvalidateLayout() } +// Child returns this element's child. If there is no child, this method will +// return nil. +func (element *Scroll) Child () tomo.Scrollable { + return element.child +} + func (element *Scroll) HandleChildMinimumSizeChange (tomo.Element) { element.updateMinimumSize() element.entity.Invalidate() @@ -172,6 +188,7 @@ func (element *Scroll) HandleScroll ( element.scrollChildBy(int(deltaX), int(deltaY)) } +// SetTheme sets the element's theme. func (element *Scroll) SetTheme (theme tomo.Theme) { if theme == element.theme.Theme { return } element.theme.Theme = theme @@ -180,6 +197,7 @@ func (element *Scroll) SetTheme (theme tomo.Theme) { element.entity.InvalidateLayout() } +// SetConfig sets the element's configuration. func (element *Scroll) SetConfig (config tomo.Config) { element.config.Config = config } diff --git a/elements/scrollbar.go b/elements/scrollbar.go index 255922b..bded941 100644 --- a/elements/scrollbar.go +++ b/elements/scrollbar.go @@ -37,6 +37,7 @@ type ScrollBar struct { onScroll func (viewport image.Point) } +// NewVScrollBar creates a new vertical scroll bar. func NewVScrollBar () (element *ScrollBar) { element = &ScrollBar { vertical: true,