button

Documentation

Overview

Package button implements an interactive widget that can be pressed to activate.

Index

• Constants
• type Button
  • func New(text string, cFn CallbackFn, opts ...Option) (*Button, error)
  • func NewFromChunks(chunks []*TextChunk, cFn CallbackFn, opts ...Option) (*Button, error)
  • func (b *Button) Draw(cvs *canvas.Canvas, meta *widgetapi.Meta) error
  • func (b *Button) Keyboard(k *terminalapi.Keyboard, meta *widgetapi.EventMeta) error
  • func (b *Button) Mouse(m *terminalapi.Mouse, meta *widgetapi.EventMeta) error
  • func (b *Button) Options() widgetapi.Options
  • func (b *Button) SetCallback(cFn CallbackFn)
• type CallbackFn
• type Option
  • func DisableShadow() Option
  • func FillColor(c cell.Color) Option
  • func FocusedFillColor(c cell.Color) Option
  • func GlobalKey(k keyboard.Key) Option
  • func GlobalKeys(keys ...keyboard.Key) Option
  • func Height(cells int) Option
  • func Key(k keyboard.Key) Option
  • func KeyUpDelay(d time.Duration) Option
  • func Keys(keys ...keyboard.Key) Option
  • func PressedFillColor(c cell.Color) Option
  • func ShadowColor(c cell.Color) Option
  • func TextColor(c cell.Color) Option
  • func TextHorizontalPadding(p int) Option
  • func Width(cells int) Option
  • func WidthFor(text string) Option
• type TextChunk
  • func NewChunk(text string, tOpts ...TextOption) *TextChunk
• type TextOption
  • func FocusedTextCellOpts(opts ...cell.Option) TextOption
  • func PressedTextCellOpts(opts ...cell.Option) TextOption
  • func TextCellOpts(opts ...cell.Option) TextOption

Constants

const DefaultHeight = 3

DefaultHeight is the default for the Height option.

const DefaultKeyUpDelay = 250 * time.Millisecond

DefaultKeyUpDelay is the default value for the KeyUpDelay option.

const DefaultTextHorizontalPadding = 1

DefaultTextHorizontalPadding is the default value for the HorizontalPadding option.

Types

type Button

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

Button can be pressed using a mouse click or a configured keyboard key.

Upon each press, the button invokes a callback provided by the user.

Implements widgetapi.Widget. This object is thread-safe.

func New

func New(text string, cFn CallbackFn, opts ...Option) (*Button, error)

New returns a new Button that will display the provided text. Each press of the button will invoke the callback function. The callback function can be nil in which case pressing the button is a no-op.

func NewFromChunks

func NewFromChunks(chunks []*TextChunk, cFn CallbackFn, opts ...Option) (*Button, error)

NewFromChunks is like New, but allows specifying write options for individual chunks of text displayed in the button.

func (*Button) Draw

func (b *Button) Draw(cvs *canvas.Canvas, meta *widgetapi.Meta) error

Draw draws the Button widget onto the canvas. Implements widgetapi.Widget.Draw.

func (*Button) Keyboard

func (b *Button) Keyboard(k *terminalapi.Keyboard, meta *widgetapi.EventMeta) error

Keyboard processes keyboard events, acts as a button press on the configured Key.

Implements widgetapi.Widget.Keyboard.

func (*Button) Mouse

func (b *Button) Mouse(m *terminalapi.Mouse, meta *widgetapi.EventMeta) error

Mouse processes mouse events, acts as a button press if both the press and the release happen inside the button.

Implements widgetapi.Widget.Mouse.

func (*Button) Options

func (b *Button) Options() widgetapi.Options

Options implements widgetapi.Widget.Options.

func (*Button) SetCallback

func (b *Button) SetCallback(cFn CallbackFn)

SetCallback replaces the callback function of the button with the one provided.

type CallbackFn

type CallbackFn func() error

CallbackFn is the function called when the button is pressed. The callback function must be light-weight, ideally just storing a value and returning, since more button presses might occur.

The callback function must be thread-safe as the mouse or keyboard events that press the button are processed in a separate goroutine.

If the function returns an error, the widget will forward it back to the termdash infrastructure which causes a panic, unless the user provided a termdash.ErrorHandler.

type Option

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

Option is used to provide options.

func DisableShadow

func DisableShadow() Option

DisableShadow when provided the button will not have a shadow area and will have no animation when pressed.

func FillColor

func FillColor(c cell.Color) Option

FillColor sets the fill color of the button.

func FocusedFillColor

func FocusedFillColor(c cell.Color) Option

FocusedFillColor sets the fill color of the button when the widget's container is focused. Defaults to FillColor.

func GlobalKey

func GlobalKey(k keyboard.Key) Option

GlobalKey is like Key, but makes the widget respond to the key even if its container isn't focused.

Clears all keys set by GlobalKey() or GlobalKeys() previously.

func GlobalKeys

func GlobalKeys(keys ...keyboard.Key) Option

GlobalKeys is like GlobalKey, but allows to configure multiple keys.

Clears all keys set by GlobalKey() or GlobalKeys() previously.

func Height

func Height(cells int) Option

Height sets the height of the button in cells. Must be a positive non-zero integer. Defaults to DefaultHeight.

func Key

func Key(k keyboard.Key) Option

Key configures the keyboard key that presses the button. The widget responds to this key only if its container is focused.

Clears all keys set by Key() or Keys() previously.

func KeyUpDelay

func KeyUpDelay(d time.Duration) Option

KeyUpDelay is the amount of time the button will remain "pressed down" after triggered by the configured key. Termbox doesn't emit events for key releases so the button simulates it by timing it. This only works if the manual termdash redraw or the periodic redraw interval are reasonably close to this delay. The duration cannot be negative. Defaults to DefaultKeyUpDelay.

func Keys

func Keys(keys ...keyboard.Key) Option

Keys is like Key, but allows to configure multiple keys.

Clears all keys set by Key() or Keys() previously.

func PressedFillColor

func PressedFillColor(c cell.Color) Option

PressedFillColor sets the fill color of the button when it is pressed. Defaults to FillColor.

func ShadowColor

func ShadowColor(c cell.Color) Option

ShadowColor sets the color of the shadow under the button.

func TextColor

func TextColor(c cell.Color) Option

TextColor sets the color of the text label in the button.

func TextHorizontalPadding

func TextHorizontalPadding(p int) Option

TextHorizontalPadding sets padding on the left and right side of the button's text as the amount of cells.

func Width

func Width(cells int) Option

Width sets the width of the button in cells. Must be a positive non-zero integer. Defaults to the auto-width based on the length of the text label. Not all the width may be available to the text if TextHorizontalPadding is set to a non-zero integer.

func WidthFor

func WidthFor(text string) Option

WidthFor sets the width of the button as if it was displaying the provided text. Useful when displaying multiple buttons with the intention to set all of their sizes equal to the one with the longest text.

type TextChunk

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

TextChunk is a part of or the full text displayed in the button.

func NewChunk

func NewChunk(text string, tOpts ...TextOption) *TextChunk

NewChunk creates a new text chunk. Each chunk of text can have its own cell options.

type TextOption

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

TextOption is used to provide options to NewChunk().

func FocusedTextCellOpts

func FocusedTextCellOpts(opts ...cell.Option) TextOption

FocusedTextCellOpts sets options on the cells that contain the button text when the widget's container is focused. If not specified, TextCellOpts will be used instead.

func PressedTextCellOpts

func PressedTextCellOpts(opts ...cell.Option) TextOption

PressedTextCellOpts sets options on the cells that contain the button text when it is pressed. If not specified, TextCellOpts will be used instead.

func TextCellOpts

func TextCellOpts(opts ...cell.Option) TextOption

TextCellOpts sets options on the cells that contain the button text. If not specified, all cells will just have their foreground color set to the value of TextColor().