container

package
v0.20.0 Latest Latest
Warning

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

 Go to latest Published: Mar 10, 2024 License: Apache-2.0 Imports: 17 Imported by: 103

Documentation

Overview

Package container defines a type that wraps other containers or widgets.

The container supports splitting container into sub containers, defining container styles and placing widgets. The container also creates and manages canvases assigned to the placed widgets.

Example

Example demonstrates how to use the Container API. 

bc, err := barchart.New()
if err != nil {
	panic(err)
}
if _, err := New(
	/* terminal = */ nil,
	SplitVertical(
		Left(
			SplitHorizontal(
				Top(
					Border(linestyle.Light),
				),
				Bottom(
					SplitHorizontal(
						Top(
							Border(linestyle.Light),
						),
						Bottom(
							Border(linestyle.Light),
						),
					),
				),
				SplitPercent(30),
			),
		),
		Right(
			Border(linestyle.Light),
			PlaceWidget(bc),
		),
	),
); err != nil {
	panic(err)
}

Output:

Index

Examples

Constants

View Source 
const DefaultSplitFixed = -1

DefaultSplitFixed is the default value for the SplitFixed option.

View Source 
const DefaultSplitPercent = 50

DefaultSplitPercent is the default value for the SplitPercent option.

View Source 
const DefaultSplitReversed = false

DefaultSplitReversed is the default value for the SplitReversed option.

Variables

This section is empty.

Functions

This section is empty.

Types

type BottomOption 

type BottomOption interface {
	// contains filtered or unexported methods
}

BottomOption is used to provide options to the bottom sub container after a horizontal split of the parent.

func Bottom 

func Bottom(opts ...Option) BottomOption

Bottom applies options to the bottom sub container after a horizontal split of the parent.

type Container 

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

Container wraps either sub containers or widgets and positions them on the terminal. This is thread-safe.

func New 

func New(t terminalapi.Terminal, opts ...Option) (*Container, error)

New returns a new root container that will use the provided terminal and applies the provided options.

func (*Container) Draw 

func (c *Container) Draw() error

Draw draws this container and all of its sub containers.

func (*Container) String 

func (c *Container) String() string

String represents the container metadata in a human readable format. Implements fmt.Stringer.

func (*Container) Subscribe added in v0.7.0 

func (c *Container) Subscribe(eds *event.DistributionSystem)

Subscribe tells the container to subscribe itself and widgets to the provided event distribution system. This method is private to termdash, stability isn't guaranteed and changes won't be backward compatible.

func (*Container) Update added in v0.8.0 

func (c *Container) Update(id string, opts ...Option) error

Update updates container with the specified id by setting the provided options. This can be used to perform dynamic layout changes, i.e. anything between replacing the widget in the container and completely changing the layout and splits. The argument id must match exactly one container with that was created with matching ID() option. The argument id must not be an empty string.

type FocusGroup added in v0.14.0 

type FocusGroup int

FocusGroup represents a group of containers that can have the keyboard focus moved between them sharing the same keyboard key.

type LeftOption 

type LeftOption interface {
	// contains filtered or unexported methods
}

LeftOption is used to provide options to the left sub container after a vertical split of the parent.

func Left 

func Left(opts ...Option) LeftOption

Left applies options to the left sub container after a vertical split of the parent.

type Option 

type Option interface {
	// contains filtered or unexported methods
}

Option is used to provide options to a container.

func AlignHorizontal 

func AlignHorizontal(h align.Horizontal) Option

AlignHorizontal sets the horizontal alignment for the widget placed in the container. Has no effect if the container contains no widget. Defaults to alignment in the center.

func AlignVertical 

func AlignVertical(v align.Vertical) Option

AlignVertical sets the vertical alignment for the widget placed in the container. Has no effect if the container contains no widget. Defaults to alignment in the middle.

func Border 

func Border(ls linestyle.LineStyle) Option

Border configures the container to have a border of the specified style.

func BorderColor 

func BorderColor(color cell.Color) Option

BorderColor sets the color of the border around the container. This option is inherited to sub containers created by container splits.

func BorderTitle 

func BorderTitle(title string) Option

BorderTitle sets a text title within the border.

func BorderTitleAlignCenter 

func BorderTitleAlignCenter() Option

BorderTitleAlignCenter aligns the border title in the center.

func BorderTitleAlignLeft 

func BorderTitleAlignLeft() Option

BorderTitleAlignLeft aligns the border title on the left.

func BorderTitleAlignRight 

func BorderTitleAlignRight() Option

BorderTitleAlignRight aligns the border title on the right.

func Clear added in v0.8.0 

func Clear() Option

Clear clears this container. If the container contains a widget, the widget is removed. If the container had any sub containers or splits, they are removed.

func Focused added in v0.14.0 

func Focused() Option

Focused moves the keyboard focus to this container. If not specified, termdash will start with the root container focused. If specified on multiple containers, the last container with this option will be focused.

func FocusedColor 

func FocusedColor(color cell.Color) Option

FocusedColor sets the color of the border around the container when it has keyboard focus. This option is inherited to sub containers created by container splits.

func ID added in v0.8.0 

func ID(id string) Option

ID sets an identifier for this container. This ID can be later used to perform dynamic layout changes by passing new options to this container. When provided, it must be a non-empty string that is unique among all the containers.

func KeyFocusGroups added in v0.14.0 

func KeyFocusGroups(groups ...FocusGroup) Option

KeyFocusGroups assigns this container to focus groups with the specified numbers.

See either of (KeysFocusGroupNext, KeysFocusGroupPrevious) for a description of focus groups.

If both the pressed key and the currently focused container are configured to be in multiple matching focus groups, focus will follow the first focus group defined on the container, i.e. the order of the supplied groups matters.

If not specified, the container doesn't belong to any focus groups. If called with zero groups, the container will be removed from all focus groups.

func KeyFocusGroupsNext added in v0.14.0 

func KeyFocusGroupsNext(key keyboard.Key, groups ...FocusGroup) Option

KeyFocusGroupsNext configures a key that moves the keyboard focus to the next container within the specified focus groups.

Containers are assigned to focus groups using the KeyFocusGroup option. The group parameter indicates which groups is the key attached to. This option can be specified multiple times to define multiple keys for the same focus groups.

A key configured using KeyFocusGroupsNext only moves focus if the container that is currently focused is part of the same focus group as one of the group specified in this option. The keyboard focus only gets moved to the next container in the same focus group, other containers are ignored.

The order in which the containers in the group are visited is the same as with the KeyFocusNext option.

This option is global and applies to all created containers. Pressing either of (KeyFocusNext, KeyFocusPrevious) still moves the focus to any container regardless of its focus group.

func KeyFocusGroupsPrevious added in v0.14.0 

func KeyFocusGroupsPrevious(key keyboard.Key, groups ...FocusGroup) Option

KeyFocusGroupsPrevious configures a key that moves the keyboard focus to the previous container within the specified focus groups.

Containers are assigned to focus groups using the KeyFocusGroup option. The group parameter indicates which groups is the key attached to. This option can be specified multiple times to define multiple keys for the same focus groups.

A key configured using KeyFocusGroupsPrevious only moves focus if the container that is currently focused is part of the same focus group as one of the group specified in this option. The keyboard focus only gets moved to the previous container in the same focus group, other containers are ignored.

The order in which the containers in the group are visited is the same as with the KeyFocusPrevious option.

This option is global and applies to all created containers. Pressing either of (KeyFocusNext, KeyFocusPrevious) still moves the focus to any container regardless of its focus group.

func KeyFocusNext added in v0.14.0 

func KeyFocusNext(key keyboard.Key) Option

KeyFocusNext configures a key that moves the keyboard focus to the next container when pressed.

Containers are organized in a binary tree, when the focus moves to the next container, it targets the next leaf container in a DFS (Depth-first search) traversal. Non-leaf containers are skipped. If the currently focused container is the last container, the focus moves back to the first container.

This option is global and applies to all created containers. If neither of (KeyFocusNext, KeyFocusPrevious) is specified, the keyboard focus can only be changed by using the mouse.

func KeyFocusPrevious added in v0.14.0 

func KeyFocusPrevious(key keyboard.Key) Option

KeyFocusPrevious configures a key that moves the keyboard focus to the previous container when pressed.

Containers are organized in a binary tree, when the focus moves to the previous container, it targets the previous leaf container in a DFS (Depth-first search) traversal. Non-leaf containers are skipped. If the currently focused container is the first container, the focus moves back to the last container.

This option is global and applies to all created containers. If neither of (KeyFocusNext, KeyFocusPrevious) is specified, the keyboard focus can only be changed by using the mouse.

func KeyFocusSkip added in v0.14.0 

func KeyFocusSkip() Option

KeyFocusSkip indicates that this container should never receive the keyboard focus when KeyFocusNext or KeyFocusPrevious is pressed.

A container configured like this would still receive the keyboard focus when directly clicked on with a mouse or when via KeysFocusGroupNext or KeysFocusGroupPrevious.

func MarginBottom added in v0.8.0 

func MarginBottom(cells int) Option

MarginBottom sets reserved space outside of the container at its bottom. The provided number is the absolute margin in cells and must be zero or a positive integer. Only one of MarginBottom or MarginBottomPercent can be specified.

func MarginBottomPercent added in v0.8.0 

func MarginBottomPercent(perc int) Option

MarginBottomPercent sets reserved space outside of the container at its bottom. The provided number is a relative margin defined as percentage of the container's height. Only one of MarginBottom or MarginBottomPercent can be specified. The value must be in range 0 <= value <= 100.

func MarginLeft added in v0.8.0 

func MarginLeft(cells int) Option

MarginLeft sets reserved space outside of the container at its left. The provided number is the absolute margin in cells and must be zero or a positive integer. Only one of MarginLeft or MarginLeftPercent can be specified.

func MarginLeftPercent added in v0.8.0 

func MarginLeftPercent(perc int) Option

MarginLeftPercent sets reserved space outside of the container at its left. The provided number is a relative margin defined as percentage of the container's height. Only one of MarginLeft or MarginLeftPercent can be specified. The value must be in range 0 <= value <= 100.

func MarginRight added in v0.8.0 

func MarginRight(cells int) Option

MarginRight sets reserved space outside of the container at its right. The provided number is the absolute margin in cells and must be zero or a positive integer. Only one of MarginRight or MarginRightPercent can be specified.

func MarginRightPercent added in v0.8.0 

func MarginRightPercent(perc int) Option

MarginRightPercent sets reserved space outside of the container at its right. The provided number is a relative margin defined as percentage of the container's height. Only one of MarginRight or MarginRightPercent can be specified. The value must be in range 0 <= value <= 100.

func MarginTop added in v0.8.0 

func MarginTop(cells int) Option

MarginTop sets reserved space outside of the container at its top. The provided number is the absolute margin in cells and must be zero or a positive integer. Only one of MarginTop or MarginTopPercent can be specified.

func MarginTopPercent added in v0.8.0 

func MarginTopPercent(perc int) Option

MarginTopPercent sets reserved space outside of the container at its top. The provided number is a relative margin defined as percentage of the container's height. Only one of MarginTop or MarginTopPercent can be specified. The value must be in range 0 <= value <= 100.

func PaddingBottom added in v0.8.0 

func PaddingBottom(cells int) Option

PaddingBottom sets reserved space between container and the bottom side of its widget. The widget's area size is decreased to accommodate the padding. The provided number is the absolute padding in cells and must be zero or a positive integer. Only one of PaddingBottom or PaddingBottomPercent can be specified.

func PaddingBottomPercent added in v0.8.0 

func PaddingBottomPercent(perc int) Option

PaddingBottomPercent sets reserved space between container and the bottom side of its widget. The widget's area size is decreased to accommodate the padding. The provided number is a relative padding defined as percentage of the container's height. The value must be in range 0 <= value <= 100. Only one of PaddingBottom or PaddingBottomPercent can be specified.

func PaddingLeft added in v0.8.0 

func PaddingLeft(cells int) Option

PaddingLeft sets reserved space between container and the left side of its widget. The widget's area size is decreased to accommodate the padding. The provided number is the absolute padding in cells and must be zero or a positive integer. Only one of PaddingLeft or PaddingLeftPercent can be specified.

func PaddingLeftPercent added in v0.8.0 

func PaddingLeftPercent(perc int) Option

PaddingLeftPercent sets reserved space between container and the left side of its widget. The widget's area size is decreased to accommodate the padding. The provided number is a relative padding defined as percentage of the container's width. The value must be in range 0 <= value <= 100. Only one of PaddingLeft or PaddingLeftPercent can be specified.

func PaddingRight added in v0.8.0 

func PaddingRight(cells int) Option

PaddingRight sets reserved space between container and the right side of its widget. The widget's area size is decreased to accommodate the padding. The provided number is the absolute padding in cells and must be zero or a positive integer. Only one of PaddingRight or PaddingRightPercent can be specified.

func PaddingRightPercent added in v0.8.0 

func PaddingRightPercent(perc int) Option

PaddingRightPercent sets reserved space between container and the right side of its widget. The widget's area size is decreased to accommodate the padding. The provided number is a relative padding defined as percentage of the container's width. The value must be in range 0 <= value <= 100. Only one of PaddingRight or PaddingRightPercent can be specified.

func PaddingTop added in v0.8.0 

func PaddingTop(cells int) Option

PaddingTop sets reserved space between container and the top side of its widget. The widget's area size is decreased to accommodate the padding. The provided number is the absolute padding in cells and must be zero or a positive integer. Only one of PaddingTop or PaddingTopPercent can be specified.

func PaddingTopPercent added in v0.8.0 

func PaddingTopPercent(perc int) Option

PaddingTopPercent sets reserved space between container and the top side of its widget. The widget's area size is decreased to accommodate the padding. The provided number is a relative padding defined as percentage of the container's height. The value must be in range 0 <= value <= 100. Only one of PaddingTop or PaddingTopPercent can be specified.

func PlaceWidget 

func PlaceWidget(w widgetapi.Widget) Option

PlaceWidget places the provided widget into the container. The use of this option removes any sub containers. Containers with sub containers cannot have widgets.

func SplitHorizontal 

func SplitHorizontal(t TopOption, b BottomOption, opts ...SplitOption) Option

SplitHorizontal splits the container along the horizontal axis into two sub containers. The use of this option removes any widget placed at this container, containers with sub containers cannot contain widgets.

func SplitVertical 

func SplitVertical(l LeftOption, r RightOption, opts ...SplitOption) Option

SplitVertical splits the container along the vertical axis into two sub containers. The use of this option removes any widget placed at this container, containers with sub containers cannot contain widgets.

func TitleColor added in v0.15.0 

func TitleColor(color cell.Color) Option

TitleColor sets the color of the title around the container. This option is inherited to sub containers created by container splits.

func TitleFocusedColor added in v0.15.0 

func TitleFocusedColor(color cell.Color) Option

TitleFocusedColor sets the color of the container title when it has keyboard focus. This option is inherited to sub containers created by container splits.

type RightOption 

type RightOption interface {
	// contains filtered or unexported methods
}

RightOption is used to provide options to the right sub container after a vertical split of the parent. 

func Right(opts ...Option) RightOption

Right applies options to the right sub container after a vertical split of the parent.

type SplitOption added in v0.4.0 

type SplitOption interface {
	// contains filtered or unexported methods
}

SplitOption is used when splitting containers.

func SplitFixed added in v0.10.0 

func SplitFixed(cells int) SplitOption

SplitFixed sets the size of the first container to be a fixed value and makes the second container take up the remaining space. When using SplitVertical, the provided size is applied to the new left container, the new right container gets the reminder of the size. When using SplitHorizontal, the provided size is applied to the new top container, the new bottom container gets the reminder of the size. The provided value must be a positive number in the range 0 <= cells. If SplitFixed* or SplitPercent* is not specified, it defaults to SplitPercent() and its given value. Only one SplitFixed* or SplitPercent* may be specified per container.

func SplitFixedFromEnd added in v0.20.0 

func SplitFixedFromEnd(cells int) SplitOption

SplitFixedFromEnd sets the size of the second container to be a fixed value and makes the first container take up the remaining space. When using SplitVertical, the provided size is applied to the new right container, the new left container gets the reminder of the size. When using SplitHorizontal, the provided size is applied to the new bottom container, the new top container gets the reminder of the size. The provided value must be a positive number in the range 0 <= cells. If SplitFixed* or SplitPercent* is not specified, it defaults to SplitPercent() and its given value. Only one SplitFixed* or SplitPercent* may be specified per container.

func SplitPercent added in v0.4.0 

func SplitPercent(p int) SplitOption

SplitPercent sets the relative size of the split as percentage of the available space. When using SplitVertical, the provided size is applied to the new left container, the new right container gets the reminder of the size. When using SplitHorizontal, the provided size is applied to the new top container, the new bottom container gets the reminder of the size. The provided value must be a positive number in the range 0 < p < 100. If not provided, defaults to DefaultSplitPercent.

func SplitPercentFromEnd added in v0.20.0 

func SplitPercentFromEnd(p int) SplitOption

SplitPercentFromEnd sets the relative size of the split as percentage of the available space. When using SplitVertical, the provided size is applied to the new right container, the new left container gets the reminder of the size. When using SplitHorizontal, the provided size is applied to the new bottom container, the new top container gets the reminder of the size. The provided value must be a positive number in the range 0 < p < 100. If not provided, defaults to using SplitPercent with DefaultSplitPercent.

type TopOption 

type TopOption interface {
	// contains filtered or unexported methods
}

TopOption is used to provide options to the top sub container after a horizontal split of the parent.

func Top 

func Top(opts ...Option) TopOption

Top applies options to the top sub container after a horizontal split of the parent.

Source Files

View all Source files

Directories

Path Synopsis
Package grid helps to build grid layouts.
 Package grid helps to build grid layouts.

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.