README
¶
Ncurses
=======
Installation
------------
This package can be installed using the ``go get`` command::
go get seehuhn.de/go/ncurses
Usage
-----
Documentation is available via the package's online help, either on
pkg.go.dev_ or on the command line::
godoc seehuhn.de/go/ncurses
.. _pkg.go.dev: https://pkg.go.dev/seehuhn.de/go/ncurses
Documentation
¶
Overview ¶
Package ncurses is a unicode-aware wrapper for the ncurses library.
If only a single window is required, the library can be initialized as follows:
win := ncurses.Init() defer ncurses.EndWin() // use methods of win for input and output
If more than one window is required, the window returned by term.Init() can be ignored and (non-overlapping) windows can be allocated using term.NewWin() instead:
win := ncurses.Init() defer ncurses.EndWin() height, width := win.GetMaxYX() win1 := ncurses.NewWin(5, width, 0, 0) win2 := ncurses.NewWin(height-5, width, 5, 0) // Use methods of win1 and win2 for input and output. // Do NOT use win after this point.
Screen coordinates follow the ncurses conventions: in argument lists, the row y is given first, followed by the column x. The top left corner of a window coresponds to y=0, x=0.
Index ¶
- Constants
- Variables
- func Beep()
- func EndWin()
- func NumColorPairs() int
- func NumColors() int
- type AttrType
- type Color
- type ColorPair
- type CursorVisibility
- type Window
- func (w *Window) AddStr(s string)
- func (w *Window) AttrGet() AttrType
- func (w *Window) AttrOff(attrs AttrType)
- func (w *Window) AttrOn(attrs AttrType)
- func (w *Window) AttrSet(attrs AttrType)
- func (w *Window) ClrToBot()
- func (w *Window) ClrToEol()
- func (w *Window) Erase()
- func (w *Window) GetBegYX() (int, int)
- func (w *Window) GetCh() rune
- func (w *Window) GetMaxYX() (int, int)
- func (w *Window) GetTimeout() int
- func (w *Window) GetYX() (int, int)
- func (w *Window) IdlOk(bf bool)
- func (w *Window) Move(y, x int)
- func (w *Window) MvAddStr(y, x int, s string)
- func (w *Window) Print(a ...interface{})
- func (w *Window) Printf(format string, a ...interface{})
- func (w *Window) Println(a ...interface{})
- func (w *Window) Readline(maxLen int) string
- func (w *Window) Refresh()
- func (w *Window) ScrollOk(bf bool)
- func (w *Window) SetBackground(char string, attrs AttrType, colorPair ColorPair)
- func (w *Window) SetTimeout(delay int)
Constants ¶
const ( KeyRangeStart rune = '\uE000' KeyA1 = KeyRangeStart + iota // upper left of keypad KeyA3 // upper right of keypad KeyB2 // center of keypad KeyBackspace // backspace key KeyBeg // begin key KeyBreak // Break key (unreliable) KeyBtab // back-tab key KeyC1 // lower left of keypad KeyC3 // lower right of keypad KeyCancel // cancel key KeyCatab // clear-all-tabs key KeyClear // clear-screen or erase key KeyClose // close key KeyCommand // command key KeyCopy // copy key KeyCreate // create key KeyCtab // clear-tab key KeyDc // delete-character key KeyDl // delete-line key KeyDown // down-arrow key KeyEic // sent by rmir or smir in insert mode KeyEnd // end key KeyEnter // enter/send key KeyEol // clear-to-end-of-line key KeyEos // clear-to-end-of-screen key KeyEvent // We were interrupted by an event KeyExit // exit key KeyFind // find key KeyHelp // help key KeyHome // home key KeyIc // insert-character key KeyIl // insert-line key KeyLeft // left-arrow key KeyLl // lower-left key (home down) KeyMark // mark key KeyMessage // message key KeyMouse // Mouse event has occurred KeyMove // move key KeyNext // next key KeyNpage // next-page key KeyOpen // open key KeyOptions // options key KeyPpage // previous-page key KeyPrevious // previous key KeyPrint // print key KeyRedo // redo key KeyReference // reference key KeyRefresh // refresh key KeyReplace // replace key KeyReset // Reset or hard reset (unreliable) KeyResize // Terminal resize event KeyRestart // restart key KeyResume // resume key KeyRight // right-arrow key KeySave // save key KeySelect // select key KeySf // scroll-forward key KeySr // scroll-backward key KeySreset // Soft (partial) reset (unreliable) KeyStab // set-tab key KeySuspend // suspend key KeyUndo // undo key KeyUp // up-arrow key KeySBeg // shifted begin key KeySCancel // shifted cancel key KeySCommand // shifted command key KeySCopy // shifted copy key KeySCreate // shifted create key KeySDc // shifted delete-character key KeySDl // shifted delete-line key KeySEnd // shifted end key KeySEol // shifted clear-to-end-of-line key KeySExit // shifted exit key KeySFind // shifted find key KeySHelp // shifted help key KeySHome // shifted home key KeySIc // shifted insert-character key KeySLeft // shifted left-arrow key KeySMessage // shifted message key KeySMove // shifted move key KeySNext // shifted next key KeySOptions // shifted options key KeySPrevious // shifted previous key KeySPrint // shifted print key KeySRedo // shifted redo key KeySReplace // shifted replace key KeySRight // shifted right-arrow key KeySRsume // shifted resume key KeySSave // shifted save key KeySSuspend // shifted suspend key KeySUndo // shifted undo key KeyTimeout // (no input available at timeout) KeyF1 // function key F1 KeyF2 // function key F2 KeyF3 // function key F3 KeyF4 // function key F4 KeyF5 // function key F5 KeyF6 // function key F6 KeyF7 // function key F7 KeyF8 // function key F8 KeyF9 // function key F9 KeyF10 // function key F10 KeyF11 // function key F11 KeyF12 // function key F12 KeyF13 // function key F13 KeyF14 // function key F14 KeyF15 // function key F15 KeyF16 // function key F16 KeyF17 // function key F17 KeyF18 // function key F18 KeyF19 // function key F19 KeyF20 // function key F20 KeyF21 // function key F21 KeyF22 // function key F22 KeyF23 // function key F23 KeyF24 // function key F24 KeyRangeEnd )
Codes in the "unicode private use area" denote function keys.
Variables ¶
var ( ErrNotSupported = errors.New("setting not supported") ErrColorFailed = errors.New("color setting failed") )
Errors returned by the ncurses routines.
Functions ¶
func Beep ¶
func Beep()
Beep is used to alert the terminal user. The function sounds an audible alarm on the terminal, if possible; otherwise it flashes the screen.
func EndWin ¶
func EndWin()
EndWin must be called before the program exits, in order to restore the terminal to a usable state.
func NumColorPairs ¶
func NumColorPairs() int
NumColorPairs returns the maximum number of color-pairs the terminal can support.
Types ¶
type AttrType ¶
type AttrType int
AttrType describes display attributes (like bold face or blinking) for text printed on the screen.
var ( AttrNormal AttrType = C.A_NORMAL // Normal display (no highlight) AttrStandout AttrType = C.A_STANDOUT // Best highlighting mode of the terminal. AttrUnderline AttrType = C.A_UNDERLINE // Underlining AttrReverse AttrType = C.A_REVERSE // Reverse video AttrBlink AttrType = C.A_BLINK // Blinking AttrDim AttrType = C.A_DIM // Half bright AttrBold AttrType = C.A_BOLD // Extra bright or bold AttrProtect AttrType = C.A_PROTECT // Protected mode AttrInvis AttrType = C.A_INVIS // Invisible or blank mode AttrAltcharset AttrType = C.A_ALTCHARSET // Alternate character set )
These constants list the display attributes supported by ncurses. Attributes can be combined by taking the bitwise or of individual attributes.
type Color ¶
type Color int
Color describes the text and background colors supported by ncurses.
var ( ColorBlack Color = C.COLOR_BLACK ColorRed Color = C.COLOR_RED ColorGreen Color = C.COLOR_GREEN ColorYellow Color = C.COLOR_YELLOW ColorBlue Color = C.COLOR_BLUE ColorMagenta Color = C.COLOR_MAGENTA ColorCyan Color = C.COLOR_CYAN ColorWhite Color = C.COLOR_WHITE )
These constants define default colors, corresponding to color values 0, 1, ..., 7. Additional color values in the range 8, ..., NumColors()-1 can be used after initializing them with Color.Init().
func (Color) Init ¶
Init changes the definition of a Color. The value color must be in the range from 0 to NumColors()-1. The three arguments are RGB values (for the amounts of red, green, and blue components) in the range from 0 to 1000. When Init() is used, all occurrences of that color on the screen immediately change to the new definition.
type ColorPair ¶
type ColorPair int
A ColorPair represents a combination of foreground and background color. The default color-pair corresponds to the value 0. Additional color-pairs in the range 1, ..., NumColorPairs()-1 can be initialized using ColorPair.Init().
type CursorVisibility ¶
type CursorVisibility int
CursorVisibility describes the state of the cursor.
const ( CursorOff CursorVisibility = iota CursorOn CursorStrong )
These constants give the possible values for CursorVisibility.
func CursSet ¶
func CursSet(visibility CursorVisibility) (CursorVisibility, error)
CursSet sets the cursor state to invisible, normal, or very visible, depending on the value of `visibility`. If the terminal supports the visibility requested, the previous cursor state is returned; otherwise an error is returned.
type Window ¶
type Window struct {
// contains filtered or unexported fields
}
A Window is the central data structure in the ncurses library. Most functionality is implemented as methods of Window objects.
func Init ¶
func Init() *Window
Init initialises the curses library and returns a Window corresponding to the whole screen. You can either use this window, or allocate your own, smaller windows using NewWin().
func NewWin ¶
NewWin creates a new window at screen position (beginY, beginX). The newly created window has `nLines' lines and `nCols' columns. Do not use overlapping windows.
func (*Window) AttrOff ¶
AttrOff turns off the named attributes without turning any other attributes on or off.
func (*Window) AttrSet ¶
AttrSet sets the current attributes of the given window to `attrs`. All attributes can be turned off using AttrSet(AttrNormal).
func (*Window) ClrToBot ¶
func (w *Window) ClrToBot()
ClrToBot erases from the cursor to the end of screen. That is, the functions all lines below the cursor in the window. Also, the current line to the right of the cursor, inclusive, is erased.
func (*Window) ClrToEol ¶
func (w *Window) ClrToEol()
ClrToEol erases the current line to the right of the cursor, inclusive, to the end of the current line.
func (*Window) Erase ¶
func (w *Window) Erase()
Erase copies blanks to every position in the window, thus clearing the window. The blanks created by Erase() have the current background rendition, as set by SetBackground(), merged into them.
func (*Window) GetBegYX ¶
GetBegYX returns the coordinates of the top-left corner of the window in screen coordinates. The returned values are the current row y and column x, relative to the top-left corner of the screen.
func (*Window) GetCh ¶
GetCh reads a character from the window. Input is expected to be utf-8 encoded and is converted to `rune`.
Function key presses (e.g. cursor keys) are reported as runes in the "unicode private use area". The constants KeyA1, ..., KeyF24 give all supported function keys.
Refresh() is called before any character is read.
func (*Window) GetTimeout ¶
GetTimeout returns the currently used timeout for input. See `SetTimeout()` for the meaning of the returned value.
func (*Window) GetYX ¶
GetYX returns the current cursor position in the given window. The returned values are the current row y and column x, relative to the top-left corner of the window.
func (*Window) IdlOk ¶
IdlOk can be used to allow curses to use the insert/delete line feature of terminals so equipped. If IdlOk() is called with `true` as the argument, curses considers using insert/delete line. Calling IdlOk() with `false` as the argument disables use of line insertion and deletion. This option should be enabled only if the application needs insert/delete line, for example, for a screen editor. It is disabled by default because insert/delete line tends to be visually annoying when used in applications where it is not really needed. If insert/delete line cannot be used, curses redraws the changed portions of all lines.
func (*Window) Move ¶
Move changes the current cursor position of the window. The arguments indicate the row y and column x of the new cursor position.
func (*Window) MvAddStr ¶
MvAddStr moves the cursor to row y, column x, and then prints a string to the window at the new cursor position.
func (*Window) Print ¶
func (w *Window) Print(a ...interface{})
Print formats the arguments using their default formats and writes the resulting string to the window. Spaces are added between operands when neither is a string.
func (*Window) Printf ¶
Printf formats the arguments according to a format specifier and writes the resulting string to the window.
func (*Window) Println ¶
func (w *Window) Println(a ...interface{})
Println formats its arguments using their default formats and writes the resulting string to the window. Spaces are always added between operands and a newline is appended.
func (*Window) Readline ¶
Readline allows the user to enter a line of text. Simple line-editing is provided and up to `maxLen` (unicode) characters of text can be entered.
Refresh() is called before any character is read.
func (*Window) Refresh ¶
func (w *Window) Refresh()
Refresh must be called to get actual output to the terminal, as other routines merely manipulate data structures. The routine copies the named window to the physical terminal screen, taking into account what is already there to do optimizations.
Note that methods waiting for keyboard input call Refresh() before waiting for input.
func (*Window) ScrollOk ¶
ScrollOk controls what happens when the cursor of a window is moved off the edge of the window or scrolling region, either as a result of a newline action on the bottom line, or typing the last character of the last line. If disabled (bf is `false`), the cursor is left on the bottom line. If enabled (bf is `true`), the window is scrolled up one line. Note that to get the physical scrolling effect on the terminal, it is also necessary to call IdlOk().
func (*Window) SetBackground ¶
SetBackground manipulates the background of the named window. The window background consists of a combination of attributes (i.e., rendition) and a complex character. The attribute part of the background is combined with all non-blank characters that are written into the window. Both the character and attribute parts of the background are combined with blank characters. The background becomes a property of the character and moves with the character through any scrolling and insert/delete line/character operations.
To the extent possible on a particular terminal, the attribute part of the background is displayed as the graphic rendition of the character put on the screen.
func (*Window) SetTimeout ¶
SetTimeout sets blocking or non-blocking read for a given window. If `delay` is negative, blocking read is used (i.e., waits indefinitely for input). If `delay` is zero, then non-blocking read is used (i.e., `GetCh()` returns `KeyTimeout` if no input is waiting). If `delay` is positive, then read blocks for `delay` milliseconds, and returns `KeyTimeout` if there is still no input.
Source Files