cursor/API.md at dev · kittikjs/cursor · GitHub

760 lines (583 loc) · 24 KB

Classes

Cell: Cell responsible for mapping separate cells in the real terminal to the virtual one.
Cursor: Cursor implements low-level API to terminal cursor.

Constants

COLORS : Object: Dictionary of colors which can be used in cursor.
DISPLAY_MODES : Object: Dictionary of the display modes and VT100 control sequences. There are the most commonly supported control sequences for formatting text and their resetting.
encodeToVT100 ⇒ String: Encode control sequence to VT100 compatible control sequence.

Cell

Cell responsible for mapping separate cells in the real terminal to the virtual one.

Kind: global class
Since: 3.1.0

Cell
- new Cell([char], [options])
- instance
  - .getChar() ⇒ String
  - .setChar([char]) ⇒ Cell
  - .getX() ⇒ Number
  - .setX([x]) ⇒ Cell
  - .getY() ⇒ Number
  - .setY([y]) ⇒ Cell
  - .getBackground() ⇒ String
  - .setBackground([colorName]) ⇒ Cell
  - .getForeground() ⇒ String
  - .setForeground([colorName]) ⇒ Cell
  - .getDisplay() ⇒ Object
  - .setDisplay([bold], [dim], [underlined], [blink], [reverse], [hidden]) ⇒ Cell
  - .setModified([isModified]) ⇒ Cell
  - .isModified() ⇒ Boolean
  - .reset() ⇒ Cell
  - .toString() ⇒ String
- static
  - .create() ⇒ Cell

new Cell([char], [options])

Create Cell instance which are able to convert itself to ASCII control sequence.

Param	Type	Description
[char]	`String`	Char that you want to wrap with control sequences
[options]	`Object`	Options object where you can set additional style to char
[options.x]	`Number`	X coordinate
[options.y]	`Number`	Y coordinate
[options.background]	`String`	Background color name, `none` to disable color
[options.foreground]	`String`	Foreground color name, `none` to disable color
[options.display]	`Object`	Object with display modes
[options.display.bold]	`Boolean`	Bold style
[options.display.dim]	`Boolean`	Dim style
[options.display.underlined]	`Boolean`	Underlined style
[options.display.blink]	`Boolean`	Blink style
[options.display.reverse]	`Boolean`	Reverse style
[options.display.hidden]	`Boolean`	Hidden style

cell.getChar() ⇒ `String`

Get current char.

Kind: instance method of Cell

cell.setChar([char]) ⇒ `Cell`

Set new char to cell. If char is longer than 1 char, it slices string to 1 char.

Kind: instance method of Cell

Param	Type	Default
[char]	`String`	`' '`

cell.getX() ⇒ `Number`

Get X coordinate of this cell.

Kind: instance method of Cell

cell.setX([x]) ⇒ `Cell`

Set new X coordinate for cell.

Kind: instance method of Cell

Param	Type	Default
[x]	`Number`	`0`

cell.getY() ⇒ `Number`

Get Y coordinate.

Kind: instance method of Cell

cell.setY([y]) ⇒ `Cell`

Set new Y coordinate for cell.

Kind: instance method of Cell

Param	Type	Default
[y]	`Number`	`0`

cell.getBackground() ⇒ `String`

Get current background color.

Kind: instance method of Cell

cell.setBackground([colorName]) ⇒ `Cell`

Set new background color.

Kind: instance method of Cell

Param	Type	Default	Description
[colorName]	`String`	`none`	Color name from COLORS dictionary.

cell.getForeground() ⇒ `String`

Get current foreground color.

Kind: instance method of Cell

cell.setForeground([colorName]) ⇒ `Cell`

Set new foreground color.

Kind: instance method of Cell

Param	Type	Default	Description
[colorName]	`String`	`none`	Color name from COLORS dictionary.

cell.getDisplay() ⇒ `Object`

Get current display modes.

Kind: instance method of Cell

cell.setDisplay([bold], [dim], [underlined], [blink], [reverse], [hidden]) ⇒ `Cell`

Set new display modes to cell.

Kind: instance method of Cell

Param	Type	Default	Description
[bold]	`Boolean`	`false`	Bold style
[dim]	`Boolean`	`false`	Dim style
[underlined]	`Boolean`	`false`	Underlined style
[blink]	`Boolean`	`false`	Blink style
[reverse]	`Boolean`	`false`	Reverse style
[hidden]	`Boolean`	`false`	Hidden style

cell.setModified([isModified]) ⇒ `Cell`

Mark cell as modified or not.

Kind: instance method of Cell

Param	Type	Default	Description
[isModified]	`Boolean`	`true`	Flag shows if cell is modified

cell.isModified() ⇒ `Boolean`

Check if cell has been modified.

Kind: instance method of Cell

cell.reset() ⇒ `Cell`

Reset display settings. It resets char, background, foreground and display mode.

Kind: instance method of Cell

cell.toString() ⇒ `String`

Convert cell to VT100 compatible control sequence.

Kind: instance method of Cell

Cell.create() ⇒ `Cell`

Wrapper around new Cell().

Kind: static method of Cell

Cursor

Cursor implements low-level API to terminal cursor.

Kind: global class
See

Since: 1.0.0

Cursor
- new Cursor([options])
- instance
  - .write(data) ⇒ Cursor
  - .flush() ⇒ Cursor
  - .getPointerFromXY([x], [y]) ⇒ Number
  - .getXYFromPointer(index) ⇒ Array
  - .up([y]) ⇒ Cursor
  - .down([y]) ⇒ Cursor
  - .right([x]) ⇒ Cursor
  - .left([x]) ⇒ Cursor
  - .moveBy(x, y) ⇒ Cursor
  - .moveTo(x, y) ⇒ Cursor
  - .foreground(color) ⇒ Cursor
  - .background(color) ⇒ Cursor
  - .bold([isBold]) ⇒ Cursor
  - .dim([isDim]) ⇒ Cursor
  - .underlined([isUnderlined]) ⇒ Cursor
  - .blink([isBlink]) ⇒ Cursor
  - .reverse([isReverse]) ⇒ Cursor
  - .hidden([isHidden]) ⇒ Cursor
  - .erase(x1, y1, x2, y2) ⇒ Cursor
  - .eraseToEnd() ⇒ Cursor
  - .eraseToStart() ⇒ Cursor
  - .eraseToDown() ⇒ Cursor
  - .eraseToUp() ⇒ Cursor
  - .eraseLine() ⇒ Cursor
  - .eraseScreen() ⇒ Cursor
  - .saveScreen() ⇒ Cursor
  - .restoreScreen() ⇒ Cursor
  - .hideCursor() ⇒ Cursor
  - .showCursor() ⇒ Cursor
  - .reset() ⇒ Cursor
- static
  - .create() ⇒ Cursor

new Cursor([options])

Creates cursor that writes direct to stdout. You can override target stream with another one. Also, you can specify custom width and height of viewport where cursor will render the frame.

Param	Type	Default	Description
[options]	`Object`		Object with options
[options.stream]	`Stream`	`process.stdout`	Writable stream
[options.width]	`Number`	`stream.columns`	Number of columns (width)
[options.height]	`Number`	`stream.rows`	Number of rows (height)

Example

new Cursor(); // creates cursor with viewport in process.stdout

// creates cursor with file as a target source and custom sizes of the viewport
new Cursor({
  stream: fs.createWriteStream('./test'),
  width: 60,
  height: 20
});

cursor.write(data) ⇒ `Cursor`

Write to the stream. It doesn't applies immediately but stores in virtual terminal that represented as array of Cell instances. For applying changes you need to flush changes.

Kind: instance method of Cursor

Param	Type	Description
data	`String`	Data to write to the terminal

Example

cursor.write('Hello, World'); // write Hello, World at current position of the cursor
cursor.flush(); // apply changes to the real terminal

cursor.flush() ⇒ `Cursor`

Takes only modified cells from virtual terminal and flush changes to the real terminal. Before flush the changes, it checks if this modified cell was actually changed. If so, writes to the stream, otherwise ignore this cell.

Kind: instance method of Cursor
Example

cursor.moveTo(10, 10); // Make some changes
cursor.write('Hello'); // One more change
cursor.write('World'); // The last one
cursor.flush(); // When changes is ready, call flush()

cursor.getPointerFromXY([x], [y]) ⇒ `Number`

Get index in the virtual terminal representation from (x, y) coordinates.

Kind: instance method of Cursor
Returns: Number - Returns index in the buffer array

Param	Type	Description
[x]	`Number`	X coordinate on the terminal
[y]	`Number`	Y coordinate on the terminal

Example

cursor.getPointerFromXY(0, 0); // returns 0
cursor.getPointerFromXY(10, 0); // returns 10

cursor.getXYFromPointer(index) ⇒ `Array`

Get (x, y) coordinate from the index in the virtual terminal representation.

Kind: instance method of Cursor
Returns: Array - Returns an array [x, y]

Param	Type	Description
index	`Number`	Index in the buffer which represents terminal

Example

const [x, y] = cursor.getXYFromPointer(0); // returns [0, 0]
const [x, y] = cursor.getXYFromPointer(10); // returns [10, 0]

cursor.up([y]) ⇒ `Cursor`

Move the cursor up.

Kind: instance method of Cursor

Param	Type	Default
[y]	`Number`	`1`

Example

cursor.up(); // move cursor up by 1 cell
cursor.up(5); // move cursor up by 5 cells

cursor.down([y]) ⇒ `Cursor`

Move the cursor down.

Kind: instance method of Cursor

Param	Type	Default
[y]	`Number`	`1`

Example

cursor.down(); // move cursor down by 1 cell
cursor.down(5); // move cursor down by 5 cells

cursor.right([x]) ⇒ `Cursor`

Move the cursor right.

Kind: instance method of Cursor

Param	Type	Default
[x]	`Number`	`1`

Example

cursor.right(); // move cursor right by 1 cell
cursor.right(5); // move cursor right by 5 cells

cursor.left([x]) ⇒ `Cursor`

Move the cursor left.

Kind: instance method of Cursor

Param	Type	Default
[x]	`Number`	`1`

Example

cursor.left(); // move cursor left by 1 cell
cursor.left(5); // move cursor left by 5 cells

cursor.moveBy(x, y) ⇒ `Cursor`

Move the cursor position relative current coordinates.

Kind: instance method of Cursor

Param	Type	Description
x	`Number`	Offset by X coordinate
y	`Number`	Offset by Y coordinate

Example

cursor.moveBy(10, 10); // moves cursor down and right by 10 cells
cursor.moveBy(-10, -10); // moves cursor up and left by 10 cells

cursor.moveTo(x, y) ⇒ `Cursor`

Set the cursor position by absolute coordinates.

Kind: instance method of Cursor

Param	Type	Description
x	`Number`	X coordinate
y	`Number`	Y coordinate

Example

cursor.moveTo(5, 10); // Move cursor to (5, 10) point in the terminal

cursor.foreground(color) ⇒ `Cursor`

Set the foreground color. This color is used when text is rendering.

Kind: instance method of Cursor

Param	Type	Description
color	`String`	Color name or `none` if you want to disable foreground filling

Example

cursor.foreground('black');
cursor.foreground('none');

cursor.background(color) ⇒ `Cursor`

Set the background color. This color is used for filling the whole cell in the TTY.

Kind: instance method of Cursor

Param	Type	Description
color	`String`	Color name or `none` if you want to disable background filling

Example

cursor.background('black');
cursor.background('none');

cursor.bold([isBold]) ⇒ `Cursor`

Toggle bold display mode.

Kind: instance method of Cursor

Param	Type	Default	Description
[isBold]	`Boolean`	`true`	If false, disables bold mode

Example

cursor.bold(); // enables bold mode
cursor.bold(false); // disables bold mode

cursor.dim([isDim]) ⇒ `Cursor`

Toggle dim display mode.

Kind: instance method of Cursor

Param	Type	Default	Description
[isDim]	`Boolean`	`true`	If false, disables dim mode

Example

cursor.dim(); // enables dim mode
cursor.dim(false); // disables dim mode

cursor.underlined([isUnderlined]) ⇒ `Cursor`

Toggle underlined display mode.

Kind: instance method of Cursor

Param	Type	Default	Description
[isUnderlined]	`Boolean`	`true`	If false, disables underlined mode

Example

cursor.underlined(); // enables underlined mode
cursor.underlined(false); // disables underlined mode

cursor.blink([isBlink]) ⇒ `Cursor`

Toggle blink display mode.

Kind: instance method of Cursor

Param	Type	Default	Description
[isBlink]	`Boolean`	`true`	If false, disables blink mode

Example

cursor.blink(); // enables blink mode
cursor.blink(false); // disables blink mode

cursor.reverse([isReverse]) ⇒ `Cursor`

Toggle reverse display mode.

Kind: instance method of Cursor

Param	Type	Default	Description
[isReverse]	`Boolean`	`true`	If false, disables reverse display mode

Example

cursor.reverse(); // enables reverse mode
cursor.reverse(false); // disables reverse mode

cursor.hidden([isHidden]) ⇒ `Cursor`

Toggle hidden display mode.

Kind: instance method of Cursor

Param	Type	Default	Description
[isHidden]	`Boolean`	`true`	If false, disables hidden display mode

Example

cursor.hidden(); // enables hidden mode
cursor.hidden(false); // disables hidden mode

cursor.erase(x1, y1, x2, y2) ⇒ `Cursor`

Erase the specified region. The region describes the rectangle shape which need to erase.

Kind: instance method of Cursor

Param	Type
x1	`Number`
y1	`Number`
x2	`Number`
y2	`Number`

Example

cursor.erase(0, 0, 5, 5); // erase the specified rectangle (0, 0, 5, 5)

cursor.eraseToEnd() ⇒ `Cursor`

Erase from current position to end of the line.

Kind: instance method of Cursor
Example

cursor.eraseToEnd();

cursor.eraseToStart() ⇒ `Cursor`

Erase from current position to start of the line.

Kind: instance method of Cursor
Example

cursor.eraseToStart();

cursor.eraseToDown() ⇒ `Cursor`

Erase from current line to down.

Kind: instance method of Cursor
Example

cursor.eraseToDown();

cursor.eraseToUp() ⇒ `Cursor`

Erase from current line to up.

Kind: instance method of Cursor
Example

cursor.eraseToUp();

cursor.eraseLine() ⇒ `Cursor`

Erase current line.

Kind: instance method of Cursor
Example

cursor.eraseLine();

cursor.eraseScreen() ⇒ `Cursor`

Erase the entire screen.

Kind: instance method of Cursor
Example

cursor.eraseScreen();

cursor.saveScreen() ⇒ `Cursor`

Save current terminal contents into the buffer. Applies immediately without calling flush.

Kind: instance method of Cursor
Example

cursor.saveScreen();

cursor.restoreScreen() ⇒ `Cursor`

Restore terminal contents to previously saved via saveScreen. Applies immediately without calling flush.

Kind: instance method of Cursor
Example

cursor.restoreScreen();

cursor.hideCursor() ⇒ `Cursor`

Set the terminal cursor invisible. Applies immediately without calling flush.

Kind: instance method of Cursor
Example

cursor.hideCursor();

cursor.showCursor() ⇒ `Cursor`

Set the terminal cursor visible. Applies immediately without calling flush.

Kind: instance method of Cursor
Example

cursor.showCursor();

cursor.reset() ⇒ `Cursor`

Reset all terminal settings. Applies immediately without calling flush.

Kind: instance method of Cursor
Example

cursor.reset();

Cursor.create() ⇒ `Cursor`

Wrapper around new Cursor().

Kind: static method of Cursor

COLORS : `Object`

Dictionary of colors which can be used in cursor.

Kind: global constant

DISPLAY_MODES : `Object`

Dictionary of the display modes and VT100 control sequences. There are the most commonly supported control sequences for formatting text and their resetting.

Kind: global constant

encodeToVT100 ⇒ `String`

Encode control sequence to VT100 compatible control sequence.

Kind: global constant
Returns: String - Returns encoded string

Param	Type	Description
code	`String`	Control sequence that you want to encode