ncurses

package module
v0.0.0-...-6594ed5 Latest Latest
Warning

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

 Go to latest Published: Aug 31, 2019 License: GPL-3.0 Imports: 6 Imported by: 0

README

go-ncurses

GoDoc

go-ncurses is a wrapper for go of the famous ncurses library.

package ncurses

import ( 
	"fmt"
)

main() {
  w,_ := ncurses.Initscr()
  
    // Ensure, that ncurses will be properly exited
  defer ncurses.Endwin()
  defer func() {
    if r := recover(); r != nil {
      ncurses.Endwin()
      fmt.Printf("panic:\n%s\n", r)
      os.Exit(-1)
    }
  }()

  // Enable color mode
  ncurses.StartColor()

  // Define color pairs
  ncurses.AddColorPair("bw", ncurses.ColorGreen,ncurses.ColorBlack)
  ncurses.AddColorPair("wb",ncurses.ColorWhite, ncurses.ColorBlue)

  // Set cursor visiblity to hidden
  ncurses.SetCursor(ncurses.CURSOR_HIDDEN)

  // Automatically refresh after each command
  w.AutoRefresh = true

  // Set color for stdscr-window to system defaults.
  w.Wbkgd("std")

  // Draw a border around main window (stdscr)
  w.Box()

  // Create a new window for greeting-text at cell (x=20,y=5) with a size of 25 x 5 cells.
  w2,err := ncurses.NewWindow("dialog",ncurses.Position{20,5},ncurses.Size{25,5})

  // This can fail if the terminal is too small.
  if err != nil {
    panic(err)
  }
  w2.AutoRefresh = true

  // Use color pair wb (2)
  w2.Wbkgd("wb")

  // Draw a border around our "Greeting Window".
  w2.Box()

  // Move cursor relative to the window borders of w2
  w2.Move(2,3)

  // Output our greeting text
  fmt.Fprintf(w2, "Hello from Go\u2122-Lang!") 

  // Move cursor relative to the beginning of our main window
  w.Move(17,19)

  // Output exit instruction for the user
  fmt.Fprintf(w," => Press a key to exit <=")

  // Wait for user input (e.g. keypress)
  w.Getch()
}

Documentation

Overview

Provides an API binding for the TUI-Library libncurses. The binding is designed to be used in multithreaded environments and therefore uses an command channel to communicate with the ncurses library.

Example (GoTMDialog) 
w, _ := ncurses.Initscr()

// Ensure, that ncurses will be properly exited
defer ncurses.Endwin()
defer func() {
	if r := recover(); r != nil {
		ncurses.Endwin()
		fmt.Printf("panic:\n%s\n", r)
		os.Exit(-1)
	}
}()

// Enable color mode
ncurses.StartColor()

// Define color pairs
ncurses.AddColorPair("bw", ncurses.ColorGreen, ncurses.ColorBlack)
ncurses.AddColorPair("wb", ncurses.ColorWhite, ncurses.ColorBlue)

// Set cursor visiblity to hidden
ncurses.SetCursor(ncurses.CURSOR_HIDDEN)

// Automatically refresh after each command
w.AutoRefresh = true

// Set color for stdscr-window to system defaults.
w.Wbkgd("std")

// Draw a border around main window (stdscr)
w.Box()

// Create a new window for greeting-text at cell (x=20,y=5) with a size of 25 x 5 cells.
w2, err := ncurses.NewWindow("dialog", ncurses.Position{20, 5}, ncurses.Size{25, 5})

// This can fail if the terminal is too small.
if err != nil {
	panic(err)
}
w2.AutoRefresh = true

// Use color pair wb (2)
w2.Wbkgd("wb")

// Draw a border around our "Greeting Window".
w2.Box()

// Move cursor relative to the window borders of w2
w2.Move(2, 3)

// Output our greeting text
fmt.Fprintf(w2, "Hello from Go\u2122-Lang!")

// Move cursor relative to the beginning of our main window
w.Move(17, 19)

// Output exit instruction for the user
fmt.Fprintf(w, " => Press a key to exit <=")

// Wait for user input (e.g. keypress)
w.Getch()

Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddColorPair 

func AddColorPair(name string, fg, bg Color)

Adds a new pair of colors, which can be used to manipulate the color of terminal outputs. Choose one color of type Color.

Example 
w, _ := Initscr()
defer Endwin()
AddColorPair("mypair", ColorWhite, ColorBlue)
SetColor("mypair")
fmt.Fprintf(w, "Hello in White and Blue")

Output:

Hello in White and Blue

func Endwin 

func Endwin() error

Closes an initialized terminal. Must be called before the program is about to exit.

func GetComChannel 

func GetComChannel() chan<- Command

Returns the command channel associated with stdscr (see ncurses documentation for information about stdscr)

func SetColor 

func SetColor(name string) error

Selects a font foreground/background color pair. Every write uses the new color pair.

Use AddColorPair to create ncurses Color-Pairs. There is one default color-pair which defaults to the terminal color-set for foreground and background.

func SetCursor 

func SetCursor(choice CursorVisibility) error

Sets visiblity of the terminal cursor.

func SetEcho 

func SetEcho(on bool) error

If enabled, typed runes are printed to terminal.

func StartColor 

func StartColor() error

Changes terminal to color mode. If the terminal does not support colors. StartColor returns an error.

Types

type Attribute 

type Attribute int
const (
	// Normal text
	AttrNormal Attribute = C.A_NORMAL
	// Hightlighted text
	AttrHighlighted Attribute = C.A_STANDOUT
	// Underlined text
	AttrUnderline Attribute = C.A_UNDERLINE
	AttrReversed  Attribute = C.A_REVERSE
	// Blinking text
	AttrBlink Attribute = C.A_BLINK
	// Dimmed text
	AttrDim Attribute = C.A_DIM
	// Bold text
	AttrBold Attribute = C.A_BOLD
	// Protected text
	AttrProtect Attribute = C.A_PROTECT
	// Hidden text
	AttrInvisible Attribute = C.A_INVIS
	// Alternative Charset
	AttrAltcharset Attribute = C.A_ALTCHARSET
)

type Color 

type Color int

A ncurses base color 

const (
	ColorBlack Color = iota
	ColorRed
	ColorGreen
	ColorYellow
	ColorBlue
	ColorMagenta
	ColorCyan
	ColorWhite
)

type Command 

type Command struct {
	// Name of the command
	Name CommandName
	// Window on which the command should be executed
	Window *Window
	// Scope of command
	Scope CommandScope
	// Data which should be passed along with the command
	Value CommandValue
}

Ncurse related commands

func (Command) String 

func (c Command) String() string

Implements Stringer interface for 'type Command'.

type CommandName 

type CommandName uint8

Name of a ncurses command 

const (
	MOVE     CommandName = iota // Move the terminal cursor
	ADD                         // Add string at current cursor location
	INSERT                      // Insert string at current cursor location
	DELETE                      // Delete string at current cursor locatio
	REFRESH                     // Flush buffer to video memory
	CLEAR                       // Clear the entire window
	SCROLLOK                    // Enables scrolling
	SCROLL                      // Scrolls current window
	SETCOLOR                    // Sets the color for text and background
	WBKGD                       // Sets fg and bg of entire window
	ATTRSET                     // Sets font attributes for follwing output
	START_TA                    // UNIMPL(sebi2020) Initiates a transaction
	END_TA                      // UNIMPL(sebi2020) Finalizes a transaction
)

All available commands, which can be passed to the command channel

func (CommandName) String 

func (cn CommandName) String() string

TODO(sebi2020): Use generator for this

type CommandScope 

type CommandScope int

Scope of Command 

const (
	GLOBAL CommandScope = iota // not a window specific command
	LOCAL                      // a window specific command
)

type CommandValue 

type CommandValue interface{}

Data of a ncurses command

type CursorVisibility 

type CursorVisibility uint8

Defines visibility of the terminal cursor. 

const (
	// Cursor is hidden
	CURSOR_HIDDEN CursorVisibility = iota
	// Cursor is visible
	CURSOR_VISIBLE
	// Cursor is visible and highlighted (not supported on all terminals)
	CURSOR_HIGHTLIGHTED
)

type Position 

type Position struct {
	X uint16
	Y uint16
}

Type which holds information about the current cursor position

func (Position) String 

func (p Position) String() string

Implementation of the Stringer Interface for type Position

type Size 

type Size Position

Alias for position which holds information about terminal size

func (Size) String 

func (s Size) String() string

Implementation of the Stringer Interface for type Size

type Window 

type Window struct {

	// Set to true, if you want to automatically refresh the window after it recieved a command
	AutoRefresh bool
	// contains filtered or unexported fields
}

Holds information about the currently used Terminal and works as a handle for all ncurses related function calls.

func Initscr 

func Initscr() (*Window, error)

Initializes the ncurses library and install cleanup functions. The function returns a new Term struct. After calling this method no outputs should be done with fmt.Print*. Make sure to call Term.Endwin() before making any output with fmt.Print*.

Example (DoThis) 
fmt.Println("Before: This is okay!")
w, _ := Initscr()

// Normally, you could use defer Endwin()
fmt.Fprintf(w, "While: This is also okay!")

Endwin()
fmt.Printf("After: This is also okay!")
// do some things

Output:
Example (DontDoThis) 
w, _ := Initscr()
// Make sure, to call Endwin() before exiting
defer Endwin()
fmt.Println("Don't do this after you've called ncurses.InitScr()")
// do some things

Output:

func NewWindow 

func NewWindow(name string, begin Position, end Size) (*Window, error)

Creates a new window. Make sure the windows do not overlap. 

Notice: Fields for position and Size are swapped. The first parameter sets the column count, not the line count.

TODO(sebi2020): Add DelWindow method

Example 
w, _ := Initscr()
defer Endwin()
w2, err := NewWindow("MyWindow", Position{4, 4}, Size{20, 4})
if err != nil {
	panic(err)
}
fmt.Fprintf(w2, "Hello from MyWindow")

Output:

func (*Window) Box 

func (w *Window) Box()

Draws a border around w *Window.

func (*Window) Clear 

func (w *Window) Clear()

Deletes all content of w *Window.

func (*Window) GetMaxYX 

func (w *Window) GetMaxYX() (Size, error)

Retrieves the terminal height and width (gathered through Terminfo & Termcap DB)

func (*Window) GetName 

func (w *Window) GetName() string

Returns name of the window from which this method is called.

func (*Window) Getch 

func (w *Window) Getch() rune

Retrieves one Rune from user.

func (*Window) Insert 

func (w *Window) Insert(format string, val ...interface{})

Inserts a string at the current position.

func (*Window) Move 

func (w *Window) Move(y, x uint16)

Moves the the cursor relative to the beginning of w *Window.

func (*Window) Refresh 

func (w *Window) Refresh()

Refreshes terminal screen. Outputs all content written since last call to Refresh()

func (*Window) Scroll 

func (w *Window) Scroll(n int)

func (*Window) SetAttribute 

func (w *Window) SetAttribute(att ...Attribute)

Sets char attributes for following output in Window w.

func (*Window) SetScrolling 

func (w *Window) SetScrolling(enable bool)

Allow you to enable window scrolling. Must be called before calling Scroll(n int)

func (*Window) String 

func (w *Window) String() string

Implementation of the Stringer Interface for type Window

func (*Window) Wbkgd 

func (w *Window) Wbkgd(pairName string) error

Changes foreground/background color-pair of the associated window.

func (*Window) Write 

func (w *Window) Write(p []byte) (n int, err error)

Implements the Writer interface. Allows you to write strings with fmt.Fprintf(window, format,...args) to the associated window.

Source Files

View all Source files

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.