termboxUI

package module
v0.0.0-...-bad9d33 Latest Latest
Warning

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

 Go to latest Published: Jan 21, 2015 License: MIT Imports: 6 Imported by: 0

README

termboxUI

A set of tools for creating UI fields on top of termbox-go.

Documentation

Overview

Package termboxUI is a ui library built for termbox-go! The fields and tools contained herein help to streamline graphics drawing and user input handling from a terminal.

Index

Constants

View Source 
const (
	MenuList MenuMode = iota
	MenuGrid

	// If this is used in place of an index, the MenuOption will be appended to the list.
	MenuInsertLast int = -1
)

Values associated with the Menu field.

View Source 
const (
	// These are the different types of popups.
	// All of these types allow for a title and content text.
	InputPopup   uint16 = iota // editbox for user text input.
	OKPopup                    // a single 'ok' button. Press any key to hide the popup.
	YesNoPopup                 // 'yes' and 'no' buttons
	DefaultPopup               // default. Does not handle any user input and is always drawn when it is part of a UI.

	// These indicate on which side, top or bottom, the popup will be drawn. Default will draw the popup centered on the terminal window.
	PopupBottom uint16 = iota
	PopupTop
	PopupDefault
)

Values associated with the Popup field.

View Source 
const (
	TextAlignmentLeft uint16 = iota
	TextAlignmentRight
	TextAlignmentCenter
	TextAlignmentTop
	TextAlignmentBottom

	TextAlignmentDefault
)

Values for passing in text alignment for text boxes. TexAlignmentDefault can be used in both vertical and horizontal cases when drawing the text box to the terminal.

Variables

This section is empty.

Functions

func DrawHorizontalLine 

func DrawHorizontalLine(x, y, w int, fg, bg termbox.Attribute)

Draws a line to the terminal starting with the cell located at 'x' and continuing to the cell at 'w' Cells 'x' and 'w' are included.

func DrawRectangle 

func DrawRectangle(x, y, h, w int, fg, bg termbox.Attribute)

Like FillArea, but it also draws a border around the area using the 'fg' attribute as the color.

func DrawText 

func DrawText(x, y int, line string, fg, bg termbox.Attribute) (int, int)

This is the most basic text drawing function. It writes a single line of text to the terminal with the specified settings.

func DrawVerticalLine 

func DrawVerticalLine(x, y, h int, fg, bg termbox.Attribute)

Draws a line to the terminal starting with the cell located at 'y' and continuing to the cell at 'h' Cells 'y' and 'h' are included.

func FillArea 

func FillArea(x, y, w, h int, fg, bg termbox.Attribute)

This fills all of the cells of the terminal within a given rectangle to the specified attributes.

func HorizontalCenterString 

func HorizontalCenterString(text string, dimension, offset int) int

This returns the termbox x coordinate to center the given string within the described area. That coordinate value returned should be referenced before drawing the text. Note that this doesn't actually draw the text string to the terminal.

func StartUI 

func StartUI(buildUserInterface func() *UI, arg ...interface{}) error

This gets the whole ball rolling. The input function is where the ui is defined.

Types

type Button 

type Button struct {
	Text   string
	Height int
	Width  int
	Event  UIEvent
	Fg     termbox.Attribute
	Bg     termbox.Attribute
	Active bool
}

A button is a simple button field that can be cast to a command.

func CreateButton 

func CreateButton(width, height int, text string, fg, bg termbox.Attribute) *Button

Creates an instance of a Button

func (*Button) Draw 

func (b *Button) Draw(x, y int)

func (*Button) HandleKey 

func (b *Button) HandleKey(key termbox.Key, ch rune, event chan UIEvent) bool

type DrawHandler 

type DrawHandler interface {
	Draw(x, y int)
	HandleKey(key termbox.Key, ch rune, event chan UIEvent) bool
}

DrawHandler is the basic interface that all ui fields must implement. A UI calls Draw to display the DrawHandler at the given x, y location on the terminal. A UI sends termbox input data to the DrawHandler through HandleKey to process any user input on a field. It returns 'true' if the message was used.

type EditBox 

type EditBox struct {
	Width       int
	Height      int
	Value       []rune
	Fg          termbox.Attribute
	Bg          termbox.Attribute
	CursorIndex int
	CustomType  uint16
}

An edit box or input box is a field that allows the user to input text. A custom type can be set to help indicate the nature of the text being input. For example, an input box could be for a first name or last name.

func CreateEditBox 

func CreateEditBox(width int, value string, customMessageCode uint16, fg, bg termbox.Attribute) *EditBox

Creates a new instance of an edit box. When width is -1, the text box will be the width of the terminal window.

func (*EditBox) Draw 

func (eb *EditBox) Draw(x, y int)

func (*EditBox) HandleKey 

func (eb *EditBox) HandleKey(key termbox.Key, ch rune, ev chan UIEvent) (eventConsumed bool)

Handles a termbox key or character input 'Enter' or 'Return' will end the string editing and signal that editing is complete. 'Backspace' removes the character before the currently selected character. 'Delete' removes the currently selected character. Left and right arrow keys will move the cursor along the edit string. 'Tab' inserts four spaces to the run array. 'Space' inserts a single space. Otherwise the character input is added to the string.

type Field 

type Field struct {
	X        int
	Y        int
	Element  DrawHandler
	HasFocus bool
}

All ui fields should adhere to this interface. 

type Menu struct {
	Width       int
	Height      int
	Header      string
	Mode        MenuMode
	DrawHelpBox bool
	Fg          termbox.Attribute
	Bg          termbox.Attribute

	Options []MenuOption
	// contains filtered or unexported fields
}

A Menu is a fully-featured menu for the termbox-go platform! This consists of an array of options, each one capable executing its own command to handle user interaction A user can either use the arrow keys or a number to highlight a menu option. Use the 'enter' or 'return' key to select that option and execute its command.

func CreateMenu 

func CreateMenu(width, height int, header string, mode MenuMode, drawHelpBox bool, fg, bg termbox.Attribute) *Menu

This creates an instance of a new Menu. If drawHelpBox is true then the F1 key will display the description of the menu option using a pop up at the bottom of the screen. 

func (m *Menu) Draw(x, y int)

Draws the menu to the terminal at the specified indices. 

func (m *Menu) HandleKey(key termbox.Key, ch rune, results chan UIEvent) (eventConsumed bool)

Handles input termbox key or character. The arrow keys will change the active or highlighted menu option. A number key will select the option at the specified index. If help text is enabled, 'F1' will toggle the help text as a popup from the bottom of the terminal. Any other user input is ignored. 

func (m *Menu) InsertMenuOption(index int, newOption MenuOption)

this adds a new menu option Either use MenuInsertLast to add the new option to the bottom of the options list or specify the index of the new menu option. 

func (m *Menu) RemoveMenuOption(index int)

Remove the menu option at the specified index from the menu 

func (m *Menu) ReplaceMenuOption(index int, newOption MenuOption)

Replace the menu option at the specified index with a new option Does nothing if the index is not within the current range of indices. Todo: only use valid options 

type MenuMode int

Menus can be displayed as either a grid or in a list. 

type MenuOption struct {
	Title    string
	HelpText string
	Command  func() UIEvent
}

MenuOption represents a single menu item. The Title value will be the text displayed for that option and must be populated. HelpText is optional text. This will show in a popup when 'F1' is pressed if menu help text is supported. 

func (mo *MenuOption) ExecuteCommand(ev chan UIEvent)

Executes the function represented by the menu option and returns the result on an event channel. 

type Popup struct {
	Title    string
	Content  string
	Position uint16
	Button1  Button
	Button2  Button
	Type     uint16
	Width    int
	Height   int
	Fg       termbox.Attribute
	Bg       termbox.Attribute
}

A popup is a simple text box that can be justified to the top, bottom or centered It can be just a title or a title with a line break and limited text

func CreatePopup 

func CreatePopup(title, content string, position uint16, height, width int, fg, bg termbox.Attribute) *Popup

func (*Popup) Draw 

func (pu *Popup) Draw(x, y int)

This will draw the popup to the terminal. Note that because popups are static fields, the x and y input values are ignored when drawing. They are included as input options so that the Popup struct is a DrawHandler interface.

func (*Popup) HandleKey 

func (pu *Popup) HandleKey(key termbox.Key, ch rune, event chan UIEvent) bool

Currently, the popup does not take any input

type ResultType 

type ResultType uint16

Any data reported from a user interaction with a field is sent using a buffer, so ResultType is used so that the resulting data can be converted to something usable. 

const (
	UIResultBool ResultType = iota
	UIResultByte
	UIResultComplex128
	UIResultComplex64
	UIResultError
	UIResultFloat64
	UIResultFloat32
	UIResultInt
	UIResultInt8
	UIResultInt16
	UIResultInt32
	UIResultInt64
	UIResultRune
	UIResultString
	UIResultUint
	UIResultUint8
	UIResultUint16
	UIResultUint32
	UIResultUint64
	UIResultUintptr

	UIResultJSON
	UIResultXML

	UIResultMap
	UIResultSlice

	UIResultNone
)

These are the possible default types returned from a user interaction.

type Table 

type Table struct {
	Height       int
	Width        int
	Columns      int
	Rows         int
	Fg           termbox.Attribute
	Bg           termbox.Attribute
	ColumnLabels []string
	RowLabels    []string
	ShowGrid     bool
	ShowNumbers  bool
	ActiveRow    int
	ActiveColumn int
	// contains filtered or unexported fields
}

This is a spreadsheet/table for the termbox-go library. If ActiveRow and ActiveColumn are both set, the table coordinate they represent will be the only one highlighted. If that location does not lay within the table definitions, only the valid row or column if either with be highlighted.

func CreateTable 

func CreateTable(width, height, columns, rows int, columnLabels, rowLabels []string, showGrid, showNumbers bool, fg, bg termbox.Attribute) *Table

Creates an instance of a new table or spreadsheet. If the number of rows exceeds the height of the table, the row count is set to the height.

func (*Table) Draw 

func (t *Table) Draw(x, y int)

Draws the table to the terminal. Note that the normal textbox rules for border and dimensions apply to the table.

func (*Table) HandleKey 

func (t *Table) HandleKey(key termbox.Key, ch rune, event chan UIEvent) bool

Currently the table does not take any input directly.

func (*Table) SetCell 

func (t *Table) SetCell(column, row int, text string) bool

Sets the value of the cell at the specified column and row. The return value is 'false' if the column and row coordinates are not within the table parameters.

type TextBox 

type TextBox struct {
	HasBorder                   bool
	WrapText                    bool
	TextHorizontalJustification uint16
	TextVerticalJustification   uint16
	Width                       int
	Height                      int
	Default_fg                  termbox.Attribute
	Default_bg                  termbox.Attribute
	// contains filtered or unexported fields
}

Basic text box for displaying text in a termbox window. HasBorder indicates that the border around the text box should be included when drawing. Note that the borders are drawn within the defined text box's area, effectively losing two columns and two rows of text writing area.

func CreateTextBox 

func CreateTextBox(width, height int, withBorder, wrapText bool, justification_h, justification_v uint16, fg, bg termbox.Attribute) *TextBox

This will create a new text box definition. If the width or height exceed the dimensions of the termbox, then the screen dimension will be used in place of 'width' or 'height'

func (*TextBox) AddText 

func (tb *TextBox) AddText(text string)

This adds a single line of text to the text box. The '\n' rune is translated to a new line and the '\t' rune is treated as four spaces.

func (*TextBox) AddTextFrom 

func (tb *TextBox) AddTextFrom(strReader io.Reader) error

This lets a text box accept a reader instead of an explicit string. The assumption is that the type of data from the read source is always 'string', at least for now...

func (*TextBox) Draw 

func (tb *TextBox) Draw(x, y int)

This will write the text box to the terminal. 'x' and 'y' are the upper-left coordinates from which the box will be drawn. The cell at that location is included when drawing. If the number of lines of the text box after wrapping is applied is larger than the height of the box, scrolling is automatically applied.

func (*TextBox) HandleKey 

func (tb *TextBox) HandleKey(key termbox.Key, ch rune, results chan UIEvent) bool

Handle the termbox key or character input. The up and down keys will scroll the text within the text box area. Any other input is ignored by text box.

type UI 

type UI struct {
	Fg           termbox.Attribute
	Bg           termbox.Attribute
	Events       map[ResultType]func(UIEvent)
	CustomEvents map[uint16]func(UIEvent)
	// contains filtered or unexported fields
}

This is the definition of all of the fields in the current termbox GUI.

func (*UI) AddField 

func (ui *UI) AddField(element DrawHandler, x, y int, hasFocus bool)

AddField adds a new ui field to the defined UI The field with draw starting at the specified termbox coordinates hasFocus will give the input handling priority to the new field.

func (*UI) Draw 

func (ui *UI) Draw()

Draw clears the terminal and then calls the Draw method for all of its fields at their set locations.

func (*UI) HandleCustomEvent 

func (ui *UI) HandleCustomEvent(event UIEvent)

func (*UI) HandleInput 

func (ui *UI) HandleInput(key termbox.Key, ch rune, event chan UIEvent) (eventConsumed bool)

Send the termbox key and character input to the UI's fields. As soon as the event is consumed by a field, this returns. This way only one field can handle that input at a time.

func (*UI) PollEvent 

func (ui *UI) PollEvent() chan termbox.Event

type UIEvent 

type UIEvent struct {
	Error      error
	Type       ResultType
	CustomType uint16
	Data       *bytes.Buffer
}

This represents the results from a user interaction with a field. The CustomType is a developer-defined type which helps when determining between different

Source Files

View all Source files

Directories

Path Synopsis
examples
menu
textEntry

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.