textinput

Documentation

Overview

Package textinput implements a widget that accepts text input.

Index

• Constants
• type ChangeFn
• type FilterFn
• type Option
  • func Border(ls linestyle.LineStyle) Option
  • func BorderColor(c cell.Color) Option
  • func ClearOnSubmit() Option
  • func CursorColor(c cell.Color) Option
  • func DefaultText(text string) Option
  • func ExclusiveKeyboardOnFocus() Option
  • func FillColor(c cell.Color) Option
  • func Filter(fn FilterFn) Option
  • func HideTextWith(r rune) Option
  • func HighlightedColor(c cell.Color) Option
  • func Label(label string, cOpts ...cell.Option) Option
  • func LabelAlign(la align.Horizontal) Option
  • func MaxWidthCells(cells int) Option
  • func OnChange(fn ChangeFn) Option
  • func OnSubmit(fn SubmitFn) Option
  • func PlaceHolder(text string) Option
  • func PlaceHolderColor(c cell.Color) Option
  • func TextColor(c cell.Color) Option
  • func WidthPerc(perc int) Option
• type SubmitFn
• type TextInput
  • func New(opts ...Option) (*TextInput, error)
  • func (ti *TextInput) Draw(cvs *canvas.Canvas, meta *widgetapi.Meta) error
  • func (ti *TextInput) Keyboard(k *terminalapi.Keyboard, meta *widgetapi.EventMeta) error
  • func (ti *TextInput) Mouse(m *terminalapi.Mouse, meta *widgetapi.EventMeta) error
  • func (ti *TextInput) Options() widgetapi.Options
  • func (ti *TextInput) Read() string
  • func (ti *TextInput) ReadAndClear() string

Constants

const DefaultCursorColorNumber = 250

DefaultCursorColorNumber is the default color number for the CursorColor option.

const DefaultFillColorNumber = 33

DefaultFillColorNumber is the default color number for the FillColor option.

const DefaultHighlightedColorNumber = 0

DefaultHighlightedColorNumber is the default color number for the HighlightedColor option.

const DefaultLabelAlign = align.HorizontalLeft

DefaultLabelAlign is the default value for the LabelAlign option.

const DefaultPlaceHolderColorNumber = 194

DefaultPlaceHolderColorNumber is the default color number for the PlaceHolderColor option.

Types

type ChangeFn

type ChangeFn func(data string)

ChangeFn when passed to OnChage will be called with all the text in the text input each time it gets modified.

This function must be thread-safe as the keyboard event that triggers the submission comes from a separate goroutine.

type FilterFn

type FilterFn func(rune) bool

FilterFn if provided can be used to filter runes that are allowed in the text input field. Any rune for which this function returns false will be rejected.

type Option

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

Option is used to provide options.

func Border

func Border(ls linestyle.LineStyle) Option

Border adds a border around the text input field.

func BorderColor

func BorderColor(c cell.Color) Option

BorderColor sets the color of the border. Defaults to the default terminal color.

func ClearOnSubmit

func ClearOnSubmit() Option

ClearOnSubmit sets the text input to be cleared when a submit of the content is triggered by the user pressing the Enter key.

func CursorColor

func CursorColor(c cell.Color) Option

CursorColor sets the color of the cursor. Defaults to DefaultCursorColorNumber.

func DefaultText

func DefaultText(text string) Option

DefaultText sets the text to be present in a newly created input field. The text must not contain any control or space characters other than ' '. The user can edit this text as normal.

func ExclusiveKeyboardOnFocus

func ExclusiveKeyboardOnFocus() Option

ExclusiveKeyboardOnFocus when set ensures that when this widget is focused, no other widget receives any keyboard events.

func FillColor

func FillColor(c cell.Color) Option

FillColor sets the fill color for the text input field. Defaults to DefaultFillColorNumber.

func Filter

func Filter(fn FilterFn) Option

Filter sets a function that will be used to filter characters the user can input.

func HideTextWith

func HideTextWith(r rune) Option

HideTextWith sets the rune that should be displayed instead of displaying the text. Useful for fields that accept sensitive information like passwords. The rune must be a printable rune with cell width of one.

func HighlightedColor

func HighlightedColor(c cell.Color) Option

HighlightedColor sets the color of the text rune directly under the cursor. Defaults to the default terminal color.

func Label

func Label(label string, cOpts ...cell.Option) Option

Label adds a text label to the left of the input field.

func LabelAlign

func LabelAlign(la align.Horizontal) Option

LabelAlign sets the alignment of the label within its area. The label is placed to the left of the input field. The width of this area can be specified using the LabelWidthPerc option. Defaults to DefaultLabelAlign.

func MaxWidthCells

func MaxWidthCells(cells int) Option

MaxWidthCells sets the maximum width of the text input field as an absolute value in cells. Must be a value in the range 4 <= cells. This doesn't limit the text that the user can input, if the text overflows the width of the input field, it scrolls to the left. Defaults to using all available width in the container.

func OnChange

func OnChange(fn ChangeFn) Option

OnChange sets a function that will be called when the content of the text input field changes.

func OnSubmit

func OnSubmit(fn SubmitFn) Option

OnSubmit sets a function that will be called with the text typed by the user when they submit the content by pressing the Enter key. The SubmitFn must not attempt to read from or modify the TextInput instance in any way as while the SubmitFn is executing, the TextInput is mutex locked. If the intention is to clear the content on submission, use the ClearOnSubmit() option.

func PlaceHolder

func PlaceHolder(text string) Option

PlaceHolder sets text to be displayed in the input field when it is empty. This text disappears when the text input field becomes focused.

func PlaceHolderColor

func PlaceHolderColor(c cell.Color) Option

PlaceHolderColor sets the color of the placeholder text. Defaults to DefaultPlaceHolderColorNumber.

func TextColor

func TextColor(c cell.Color) Option

TextColor sets the color of the text in the input field. Defaults to the default terminal color.

func WidthPerc

func WidthPerc(perc int) Option

WidthPerc sets the width for the text input field as a percentage of the container width. Must be a value in the range 0 < perc <= 100. Defaults to the width adjusted automatically base on the label length.

type SubmitFn

type SubmitFn func(text string) error

SubmitFn if provided is called when the user submits the content of the text input field, the argument text contains all the text in the field. Submitting the input field clears its content.

The callback function must be thread-safe as the keyboard event that triggers the submission comes from a separate goroutine.

type TextInput

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

TextInput accepts text input from the user.

Displays an input field and an optional text label. The input field allows the user to edit and submit text.

The text can be submitted by pressing enter or read at any time by calling Read. The text input field can be navigated using arrows, the Home and End button and using mouse.

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

func New

func New(opts ...Option) (*TextInput, error)

New returns a new TextInput.

func (*TextInput) Draw

func (ti *TextInput) Draw(cvs *canvas.Canvas, meta *widgetapi.Meta) error

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

func (*TextInput) Keyboard

func (ti *TextInput) Keyboard(k *terminalapi.Keyboard, meta *widgetapi.EventMeta) error

Keyboard processes keyboard events. Implements widgetapi.Widget.Keyboard.

func (*TextInput) Mouse

func (ti *TextInput) Mouse(m *terminalapi.Mouse, meta *widgetapi.EventMeta) error

Mouse processes mouse events. Implements widgetapi.Widget.Mouse.

func (*TextInput) Options

func (ti *TextInput) Options() widgetapi.Options

Options implements widgetapi.Widget.Options.

func (*TextInput) Read

func (ti *TextInput) Read() string

Read reads the content of the text input field.

func (*TextInput) ReadAndClear

func (ti *TextInput) ReadAndClear() string

ReadAndClear reads the content of the text input field and clears it.