Cli-Canvas

A no-dependency package for rendering terminal graphics efficiently

What cli-canvas ISN'T

cli-canvas is not an implementation of the Canvas API, don't expect it to do the same things the same way

What it IS

cli-canvas is used to render graphics using buffers, so as to reduce reduce redraws, lowering the 'flicker' that terminal graphics often have.

Documentation

Setup

const cliCanves = require("cli-canvas");

let ctx = new cliCanvas.Context();
ctx.begin();
// All rendering goes between begin() and end()
ctx.end();

Rendering Primitives

Note, (0, 0) is top left, and (width, height) is bottom right.

ctx.point(x, y, character)

• character can be any string, but only the first character will be drawn

ctx.line(x, y, width, height[, character])

• character defaults to ctx.style.line

ctx.rect(x, y, width, height[, character])

• character defaults to ctx.style.line

ctx.filledRect(x, y, width, height[, fillCharacter, lineCharacter])

• fillCharacter defaults to ctx.style.fill
• lineCharacter defaults to ctx.style.line

ctx.text(x, y, string)

Working With Style & Color

Render characters are controlled by the ctx.style object (Class cliCanvas.Style)

Examples

// Render in (243, 54, 190) on black, change line symbol to 'M'
ctx.style.line = "M";
ctx.style.foreground = cliCanvas.Color.rgb(243, 54, 190);
ctx.style.background = cliCanvas.Color.Black;

Default Style Values:

line = "X";
fill = "O";
empty = " ";

// Borders & Corers
top = "\u2550";
bottom = "\u2550";
left = "\u2551";
right = "\u2551";

topLeft = "\u2554";
topRight = "\u2557";
bottomLeft = "\u255A";
bottomRight = "\u255D";

// Colors
foreground = Color.DefaultFG;
Background = Color.DefaultBG;

Events

Event handlers can be set through ctx.on("event", callback)

Current Events

• resize: calls callback on terminal resize

Public Variables

• ctx.width Width of canvas
• ctx.height Height of canvas
• ctx.style Style properties
• cliCanvas.Style.Color terminal color object, has some predefined colors
• cliCanvas.Style.Color.rgb(0-255, 0-255, 0-255) returns a terminal color
• cliCanvas.Style(params) Style object constructor, params is object with values

Changelog

v0.6.0

• Added floating point support
• Added transform support

v0.5.0

• Updated color support to accommodate 256 colors

v0.4.2

• Fixed bug with passing non strings to point()

v0.4.1

• Improved documentation

v0.4.0

• Improved color API

v0.3.0

• Early color support, expect it to change

v0.2.0

• Style object
• Rectangle
• Filled Rectangle
• Text

Fixed:

• Gaps in line()