Class: Screen

Defined in: packages/core/src/widgets/screen.ts:90

Screen - The top-level container and rendering engine for terminal UI applications.

Remarks

Screen manages the terminal, handles rendering, processes input, and serves as the root container for all widgets. It provides:

• Terminal management: Alt screen buffer, cursor control, raw mode
• Rendering engine: Efficient screen updates with smart CSR
• Input handling: Keyboard and mouse events
• Widget container: Root of the widget tree
• Focus management: Tracks and manages widget focus

Examples

import { Screen, Box } from '@unblessed/node';

const screen = new Screen({
  smartCSR: true,
  title: 'My App'
});

const box = new Box({
  parent: screen,
  top: 'center',
  left: 'center',
  width: '50%',
  height: '50%',
  content: 'Hello World!',
  border: { type: 'line' }
});

screen.key(['q', 'C-c'], () => {
  screen.destroy();
  process.exit(0);
});

screen.render();

const screen = new Screen({
  smartCSR: true,
  sendFocus: true
});

const box = new Box({
  parent: screen,
  mouse: true,
  // ...
});

box.on('click', () => {
  box.setContent('Clicked!');
  screen.render();
});

screen.render();

See

• ScreenOptions for all available configuration options
• Program for low-level terminal control
• Runtime for platform abstraction

Extends

• Node

Constructors

Constructor

new Screen(options): Screen

Defined in: packages/core/src/widgets/screen.ts:144

Parameters

options

ScreenOptions = {}

Returns

Screen

Overrides

Node.constructor

Properties

_events

_events: any

Defined in: packages/core/src/lib/events.ts:10

Inherited from

Node._events

---

_maxListeners?

optional _maxListeners: number

Defined in: packages/core/src/lib/events.ts:11

Inherited from

Node._maxListeners

---

uid

static uid: number = 0

Defined in: packages/core/src/widgets/node.ts:30

Inherited from

Node.uid

---

ScreenRegistry

static ScreenRegistry: any

Defined in: packages/core/src/widgets/node.ts:31

Inherited from

Node.ScreenRegistry

---

screen

screen: any

Defined in: packages/core/src/widgets/node.ts:47

Reference to the parent Screen instance. Type: Screen (subclass of Node)

Kept as any due to circular dependency between Node and Screen, and to preserve access to Screen-specific methods like clearRegion(), render(), and the program property without complex generic typing.

Inherited from

Node.screen

---

parent

parent: any

Defined in: packages/core/src/widgets/node.ts:56

Reference to the parent element in the widget tree. Type: Node (can be any Element/Box/List/etc subclass)

Kept as any to avoid complex generic typing and preserve access to subclass-specific methods. Attempting to type as Node loses methods from subclasses like Box, List, Form, etc.

Inherited from

Node.parent

---

children

children: any[]

Defined in: packages/core/src/widgets/node.ts:63

Array of child elements. Type: Node[] (can contain any Node subclasses)

Kept as any[] to preserve flexibility with mixed widget types.

Inherited from

Node.children

---

$

$: Record<string, unknown>

Defined in: packages/core/src/widgets/node.ts:68

An object for any miscellaneous user data.

Inherited from

Node.$

---

_

_: Record<string, unknown>

Defined in: packages/core/src/widgets/node.ts:73

An object for any miscellaneous user data.

Inherited from

Node._

---

data

data: Record<string, unknown>

Defined in: packages/core/src/widgets/node.ts:78

An object for any miscellaneous user data.

Inherited from

Node.data

---

uid

uid: number

Defined in: packages/core/src/widgets/node.ts:80

Inherited from

Node.uid

---

index

index: number = -1

Defined in: packages/core/src/widgets/node.ts:86

Render index (document order index) of the last render call. Indicates the order in which this element was rendered relative to others. Set to -1 initially, updated during rendering.

Inherited from

Node.index

---

detached?

optional detached: boolean

Defined in: packages/core/src/widgets/node.ts:87

Inherited from

Node.detached

---

destroyed?

optional destroyed: boolean

Defined in: packages/core/src/widgets/node.ts:88

Inherited from

Node.destroyed

---

runtime

runtime: Runtime

Defined in: packages/core/src/widgets/node.ts:90

Inherited from

Node.runtime

---

options

options: ScreenOptions

Defined in: packages/core/src/widgets/screen.ts:91

Overrides

Node.options

---

program

program: any

Defined in: packages/core/src/widgets/screen.ts:92

---

tput

tput: any

Defined in: packages/core/src/widgets/screen.ts:93

---

autoPadding

autoPadding: boolean

Defined in: packages/core/src/widgets/screen.ts:94

---

tabc

tabc: string

Defined in: packages/core/src/widgets/screen.ts:95

---

dockBorders

dockBorders: any

Defined in: packages/core/src/widgets/screen.ts:96

---

ignoreLocked

ignoreLocked: any[]

Defined in: packages/core/src/widgets/screen.ts:97

---

_unicode

_unicode: boolean

Defined in: packages/core/src/widgets/screen.ts:98

---

fullUnicode

fullUnicode: boolean

Defined in: packages/core/src/widgets/screen.ts:99

---

dattr

dattr: number

Defined in: packages/core/src/widgets/screen.ts:100

---

renders

renders: number

Defined in: packages/core/src/widgets/screen.ts:101

---

position

position: any

Defined in: packages/core/src/widgets/screen.ts:102

---

left

left: number

Defined in: packages/core/src/widgets/screen.ts:103

---

aleft

aleft: number

Defined in: packages/core/src/widgets/screen.ts:104

---

rleft

rleft: number

Defined in: packages/core/src/widgets/screen.ts:105

---

right

right: number

Defined in: packages/core/src/widgets/screen.ts:106

---

aright

aright: number

Defined in: packages/core/src/widgets/screen.ts:107

---

rright

rright: number

Defined in: packages/core/src/widgets/screen.ts:108

---

top

top: number

Defined in: packages/core/src/widgets/screen.ts:109

---

atop

atop: number

Defined in: packages/core/src/widgets/screen.ts:110

---

rtop

rtop: number

Defined in: packages/core/src/widgets/screen.ts:111

---

bottom

bottom: number

Defined in: packages/core/src/widgets/screen.ts:112

---

abottom

abottom: number

Defined in: packages/core/src/widgets/screen.ts:113

---

rbottom

rbottom: number

Defined in: packages/core/src/widgets/screen.ts:114

---

ileft

ileft: number

Defined in: packages/core/src/widgets/screen.ts:115

---

itop

itop: number

Defined in: packages/core/src/widgets/screen.ts:116

---

iright

iright: number

Defined in: packages/core/src/widgets/screen.ts:117

---

ibottom

ibottom: number

Defined in: packages/core/src/widgets/screen.ts:118

---

iheight

iheight: number

Defined in: packages/core/src/widgets/screen.ts:119

---

iwidth

iwidth: number

Defined in: packages/core/src/widgets/screen.ts:120

---

padding

padding: any

Defined in: packages/core/src/widgets/screen.ts:121

---

hover

hover: any

Defined in: packages/core/src/widgets/screen.ts:122

---

history

history: any[]

Defined in: packages/core/src/widgets/screen.ts:123

---

clickable

clickable: any[]

Defined in: packages/core/src/widgets/screen.ts:124

---

keyable

keyable: any[]

Defined in: packages/core/src/widgets/screen.ts:125

---

grabKeys

grabKeys: boolean

Defined in: packages/core/src/widgets/screen.ts:126

---

lockKeys

lockKeys: boolean

Defined in: packages/core/src/widgets/screen.ts:127

---

_buf

_buf: string

Defined in: packages/core/src/widgets/screen.ts:128

---

_ci

_ci: number

Defined in: packages/core/src/widgets/screen.ts:129

---

cursor

cursor: any

Defined in: packages/core/src/widgets/screen.ts:130

---

_listenedMouse?

optional _listenedMouse: boolean

Defined in: packages/core/src/widgets/screen.ts:131

---

_listenedKeys?

optional _listenedKeys: boolean

Defined in: packages/core/src/widgets/screen.ts:132

---

_needsClickableSort?

optional _needsClickableSort: boolean

Defined in: packages/core/src/widgets/screen.ts:133

---

mouseDown?

optional mouseDown: any

Defined in: packages/core/src/widgets/screen.ts:134

---

lines

lines: any[] = []

Defined in: packages/core/src/widgets/screen.ts:135

---

olines

olines: any[] = []

Defined in: packages/core/src/widgets/screen.ts:136

---

_borderStops?

optional _borderStops: any

Defined in: packages/core/src/widgets/screen.ts:137

---

debugLog?

optional debugLog: any

Defined in: packages/core/src/widgets/screen.ts:138

---

_hoverText?

optional _hoverText: any

Defined in: packages/core/src/widgets/screen.ts:139

---

_savedFocus?

optional _savedFocus: any

Defined in: packages/core/src/widgets/screen.ts:140

---

_cursorBlink?

optional _cursorBlink: any

Defined in: packages/core/src/widgets/screen.ts:141

---

type

type: string = "screen"

Defined in: packages/core/src/widgets/screen.ts:142

Type of the node (e.g. box, list, form, etc.). Used to identify the widget type at runtime.

Overrides

Node.type

---

resetCursor

static resetCursor: any

Defined in: packages/core/src/widgets/screen.ts:2765

---

_exceptionHandler

static _exceptionHandler: any

Defined in: packages/core/src/widgets/screen.ts:2766

---

_sigtermHandler

static _sigtermHandler: any

Defined in: packages/core/src/widgets/screen.ts:2767

---

_sigintHandler

static _sigintHandler: any

Defined in: packages/core/src/widgets/screen.ts:2768

---

_sigquitHandler

static _sigquitHandler: any

Defined in: packages/core/src/widgets/screen.ts:2769

---

_exitHandler

static _exitHandler: any

Defined in: packages/core/src/widgets/screen.ts:2770

---

_bound

static _bound: any

Defined in: packages/core/src/widgets/screen.ts:2771

---

bind()

static bind: (screen) => void

Defined in: packages/core/src/widgets/screen.ts:2772

For a given function, creates a bound function that has the same body as the original function. The this object of the bound function is associated with the specified object, and has the specified initial parameters.

Parameters

screen

any

Returns

void

Accessors

title

Get Signature

get title(): string

Defined in: packages/core/src/widgets/screen.ts:318

Set or get window title.

Returns

string

Set Signature

set title(title): void

Defined in: packages/core/src/widgets/screen.ts:322

Parameters

title

string

Returns

void

---

terminal

Get Signature

get terminal(): string

Defined in: packages/core/src/widgets/screen.ts:329

Set or get terminal name. Set calls screen.setTerminal() internally.

Returns

string

Set Signature

set terminal(terminal): void

Defined in: packages/core/src/widgets/screen.ts:333

Parameters

terminal

string

Returns

void

---

cols

Get Signature

get cols(): number

Defined in: packages/core/src/widgets/screen.ts:340

Same as screen.width.

Returns

number

---

rows

Get Signature

get rows(): number

Defined in: packages/core/src/widgets/screen.ts:347

Same as screen.height.

Returns

number

---

width

Get Signature

get width(): number

Defined in: packages/core/src/widgets/screen.ts:354

Width of the screen (same as program.cols).

Returns

number

---

height

Get Signature

get height(): number

Defined in: packages/core/src/widgets/screen.ts:361

Height of the screen (same as program.rows).

Returns

number

---

focused

Get Signature

get focused(): any

Defined in: packages/core/src/widgets/screen.ts:368

Top of the focus history stack.

Returns

any

Set Signature

set focused(el): void

Defined in: packages/core/src/widgets/screen.ts:372

Parameters

el

any

Returns

void

Methods

setMaxListeners()

setMaxListeners(n): void

Defined in: packages/core/src/lib/events.ts:19

Parameters

n

number

Returns

void

Inherited from

Node.setMaxListeners

---

addListener()

addListener(type, listener): void

Defined in: packages/core/src/lib/events.ts:23

Parameters

type

string

listener

Function

Returns

void

Inherited from

Node.addListener

---

on()

on(type, listener): any

Defined in: packages/core/src/lib/events.ts:34

Parameters

type

string

listener

Function

Returns

any

Inherited from

Node.on

---

removeListener()

removeListener(type, listener): void

Defined in: packages/core/src/lib/events.ts:38

Parameters

type

string

listener

Function

Returns

void

Inherited from

Node.removeListener

---

off()

off(type, listener): any

Defined in: packages/core/src/lib/events.ts:57

Parameters

type

string

listener

Function

Returns

any

Inherited from

Node.off

---

removeAllListeners()

removeAllListeners(type?): void

Defined in: packages/core/src/lib/events.ts:61

Parameters

type?

string

Returns

void

Inherited from

Node.removeAllListeners

---

once()

once(type, listener): any

Defined in: packages/core/src/lib/events.ts:69

Parameters

type

string

listener

Function

Returns

any

Inherited from

Node.once

---

listeners()

listeners(type): Function[]

Defined in: packages/core/src/lib/events.ts:79

Parameters

type

string

Returns

Function[]

Inherited from

Node.listeners

---

_emit()

_emit(type, args): any

Defined in: packages/core/src/lib/events.ts:85

Parameters

type

string

args

any[]

Returns

any

Inherited from

Node._emit

---

emit()

emit(type, ...rest): boolean

Defined in: packages/core/src/lib/events.ts:113

Parameters

type

string

rest

...any[]

Returns

boolean

Inherited from

Node.emit

---

insert()

insert(element, i): void

Defined in: packages/core/src/widgets/node.ts:154

Insert a node to this node's children at index i.

Parameters

element

any

i

number

Returns

void

Inherited from

Node.insert

---

prepend()

prepend(element): void

Defined in: packages/core/src/widgets/node.ts:191

Prepend a node to this node's children.

Parameters

element

any

Returns

void

Inherited from

Node.prepend

---

append()

append(element): void

Defined in: packages/core/src/widgets/node.ts:198

Append a node to this node's children.

Parameters

element

any

Returns

void

Inherited from

Node.append

---

insertBefore()

insertBefore(element, other): void

Defined in: packages/core/src/widgets/node.ts:205

Insert a node to this node's children before the reference node.

Parameters

element

any

other

any

Returns

void

Inherited from

Node.insertBefore

---

insertAfter()

insertAfter(element, other): void

Defined in: packages/core/src/widgets/node.ts:213

Insert a node from node after the reference node.

Parameters

element

any

other

any

Returns

void

Inherited from

Node.insertAfter

---

remove()

remove(element): void

Defined in: packages/core/src/widgets/node.ts:221

Remove child node from node.

Parameters

element

any

Returns

void

Inherited from

Node.remove

---

detach()

detach(): void

Defined in: packages/core/src/widgets/node.ts:255

Remove node from its parent.

Returns

void

Inherited from

Node.detach

---

free()

free(): void

Defined in: packages/core/src/widgets/node.ts:263

Free up the element. Automatically unbind all events that may have been bound to the screen object. This prevents memory leaks.

Returns

void

Inherited from

Node.free

---

forDescendants()

forDescendants(iter, s?): void

Defined in: packages/core/src/widgets/node.ts:283

Iterate over all descendants, calling iter(el) for each.

Parameters

iter

(el) => void

s?

any

Returns

void

Inherited from

Node.forDescendants

---

forAncestors()

forAncestors(iter, s?): void

Defined in: packages/core/src/widgets/node.ts:294

Iterate over all ancestors, calling iter(el) for each.

Parameters

iter

(el) => void

s?

any

Returns

void

Inherited from

Node.forAncestors

---

collectDescendants()

collectDescendants(s?): any[]

Defined in: packages/core/src/widgets/node.ts:305

Collect all descendants into an array.

Parameters

s?

any

Returns

any[]

Inherited from

Node.collectDescendants

---

collectAncestors()

collectAncestors(s?): any[]

Defined in: packages/core/src/widgets/node.ts:316

Collect all ancestors into an array.

Parameters

s?

any

Returns

any[]

Inherited from

Node.collectAncestors

---

emitDescendants()

emitDescendants(...args): void

Defined in: packages/core/src/widgets/node.ts:327

Emit event for element, and recursively emit same event for all descendants.

Parameters

args

...any[]

Returns

void

Inherited from

Node.emitDescendants

---

emitAncestors()

emitAncestors(...args): void

Defined in: packages/core/src/widgets/node.ts:343

Emit event for element, and recursively emit same event for all ancestors.

Parameters

args

...any[]

Returns

void

Inherited from

Node.emitAncestors

---

hasDescendant()

hasDescendant(target): boolean

Defined in: packages/core/src/widgets/node.ts:359

Check if target is a descendant of this node.

Parameters

target

any

Returns

boolean

Inherited from

Node.hasDescendant

---

hasAncestor()

hasAncestor(target): boolean

Defined in: packages/core/src/widgets/node.ts:377

Check if target is an ancestor of this node.

Parameters

target

any

Returns

boolean

Inherited from

Node.hasAncestor

---

get()

get(name, value?): any

Defined in: packages/core/src/widgets/node.ts:388

Get user property with a potential default value.

Parameters

name

string

value?

any

Returns

any

Inherited from

Node.get

---

set()

set(name, value): any

Defined in: packages/core/src/widgets/node.ts:398

Set user property to value.

Parameters

name

string

value

any

Returns

any

Inherited from

Node.set

---

setTerminal()

setTerminal(terminal): void

Defined in: packages/core/src/widgets/screen.ts:379

Reset the terminal to term. Reloads terminfo.

Parameters

terminal

string

Returns

void

---

enter()

enter(): void

Defined in: packages/core/src/widgets/screen.ts:397

Enter the alternate screen buffer and initialize the screen. Automatically called when the screen is created.

Returns

void

---

leave()

leave(): void

Defined in: packages/core/src/widgets/screen.ts:431

Leave the alternate screen buffer and restore the terminal to its original state. Automatically called when the screen is destroyed.

Returns

void

---

postEnter()

postEnter(): void

Defined in: packages/core/src/widgets/screen.ts:464

Perform post-enter initialization. Sets up debug log and warnings if enabled. Automatically called after enter().

Returns

void

---

destroy()

destroy(): void

Defined in: packages/core/src/widgets/screen.ts:543

Destroy the screen object and remove it from the global list. Also remove all global events relevant to the screen object. If all screen objects are destroyed, the node process is essentially reset to its initial state.

Returns

void

Overrides

Node.destroy

---

log()

log(...args): any

Defined in: packages/core/src/widgets/screen.ts:585

Write string to the log file if one was created.

Parameters

args

...any[]

Returns

any

---

debug()

debug(...args): any

Defined in: packages/core/src/widgets/screen.ts:592

Same as the log method, but only gets called if the debug option was set.

Parameters

args

...any[]

Returns

any

---

_listenMouse()

_listenMouse(el?): void

Defined in: packages/core/src/widgets/screen.ts:603

Internal method to set up mouse event handling for the screen and optionally an element.

Parameters

el?

any

Element to register as clickable (optional)

Returns

void

---

enableMouse()

enableMouse(el?): void

Defined in: packages/core/src/widgets/screen.ts:716

Enable mouse events for the screen and optionally an element (automatically called when a form of on('mouse') is bound).

Parameters

el?

any

Returns

void

---

_listenKeys()

_listenKeys(el?): void

Defined in: packages/core/src/widgets/screen.ts:724

Internal method to set up keypress event handling for the screen and optionally an element.

Parameters

el?

any

Element to register as keyable (optional)

Returns

void

---

enableKeys()

enableKeys(el?): void

Defined in: packages/core/src/widgets/screen.ts:780

Enable keypress events for the screen and optionally an element (automatically called when a form of on('keypress') is bound).

Parameters

el?

any

Element to enable keys for (optional)

Returns

void

---

enableInput()

enableInput(el?): void

Defined in: packages/core/src/widgets/screen.ts:788

Enable key and mouse events. Calls both enableMouse() and enableKeys().

Parameters

el?

any

Element to enable input for (optional)

Returns

void

---

_initHover()

_initHover(): void

Defined in: packages/core/src/widgets/screen.ts:797

Internal method to initialize the hover text box used by element.setHover(). Creates a floating box that follows the mouse cursor.

Returns

void

---

alloc()

alloc(dirty?): void

Defined in: packages/core/src/widgets/screen.ts:856

Allocate a new pending screen buffer and a new output screen buffer.

Parameters

dirty?

boolean

Returns

void

---

realloc()

realloc(): void

Defined in: packages/core/src/widgets/screen.ts:882

Reallocate the screen buffers and clear the screen.

Returns

void

---

render()

render(): void

Defined in: packages/core/src/widgets/screen.ts:889

Render all child elements, writing all data to the screen buffer and drawing the screen.

Returns

void

---

blankLine()

blankLine(ch?, dirty?): any[]

Defined in: packages/core/src/widgets/screen.ts:935

Create a blank line array for the screen buffer.

Parameters

ch?

string

Character to fill the line with (default: space)

dirty?

boolean

Whether to mark the line as dirty (requires redraw)

Returns

any[]

Array representing a blank line in the screen buffer

---

insertLine()

insertLine(n, y, top, bottom): void

Defined in: packages/core/src/widgets/screen.ts:952

Insert a line into the screen (using CSR: this bypasses the output buffer). Uses change_scroll_region to optimize scrolling for elements with uniform sides.

Parameters

n

number

Number of lines to insert

y

number

Y position to insert at

top

number

Top of scroll region

bottom

number

Bottom of scroll region

Returns

void

---

deleteLine()

deleteLine(n, y, top, bottom): void

Defined in: packages/core/src/widgets/screen.ts:985

Delete a line from the screen (using CSR: this bypasses the output buffer). Uses change_scroll_region to optimize scrolling for elements with uniform sides.

Parameters

n

number

Number of lines to delete

y

number

Y position to delete from

top

number

Top of scroll region

bottom

number

Bottom of scroll region

Returns

void

---

insertLineNC()

insertLineNC(n, y, top, bottom): void

Defined in: packages/core/src/widgets/screen.ts:1018

Insert lines using ncurses method (scroll down, up cursor-wise). This will only work for top line deletion as opposed to arbitrary lines.

Parameters

n

number

Number of lines to insert

y

number

Y position to insert at

top

number

Top of scroll region

bottom

number

Bottom of scroll region

Returns

void

---

deleteLineNC()

deleteLineNC(n, y, top, bottom): void

Defined in: packages/core/src/widgets/screen.ts:1048

Delete lines using ncurses method (scroll up, down cursor-wise). This will only work for bottom line deletion as opposed to arbitrary lines.

Parameters

n

number

Number of lines to delete

y

number

Y position to delete from

top

number

Top of scroll region

bottom

number

Bottom of scroll region

Returns

void

---

insertBottom()

insertBottom(top, bottom): void

Defined in: packages/core/src/widgets/screen.ts:1075

Insert a line at the bottom of the screen.

Parameters

top

number

Top of scroll region

bottom

number

Bottom of scroll region

Returns

void

---

insertTop()

insertTop(top, bottom): void

Defined in: packages/core/src/widgets/screen.ts:1084

Insert a line at the top of the screen.

Parameters

top

number

Top of scroll region

bottom

number

Bottom of scroll region

Returns

void

---

deleteBottom()

deleteBottom(_top, bottom): void

Defined in: packages/core/src/widgets/screen.ts:1093

Delete a line at the bottom of the screen.

Parameters

_top

number

Top of scroll region (unused)

bottom

number

Bottom of scroll region

Returns

void

---

deleteTop()

deleteTop(top, bottom): void

Defined in: packages/core/src/widgets/screen.ts:1102

Delete a line at the top of the screen.

Parameters

top

number

Top of scroll region

bottom

number

Bottom of scroll region

Returns

void

---

cleanSides()

cleanSides(el): boolean

Defined in: packages/core/src/widgets/screen.ts:1115

Parse the sides of an element to determine whether an element has uniform cells on both sides. If it does, we can use CSR to optimize scrolling on a scrollable element. Checks if cells to the left and right of the element are all identical, allowing for optimized scrolling using change_scroll_region (CSR).

Parameters

el

any

Element to check

Returns

boolean

True if the element has clean sides (uniform cells on both sides)

---

_dockBorders()

_dockBorders(): void

Defined in: packages/core/src/widgets/screen.ts:1200

Internal method to dock borders with adjacent elements. Processes border stops to determine which border characters should connect with adjacent borders, replacing corner and T-junction characters as appropriate.

Returns

void

---

_getAngle()

_getAngle(lines, x, y): string

Defined in: packages/core/src/widgets/screen.ts:1246

Internal method to determine the correct border angle character for a given position. Examines adjacent cells to determine which directions have borders, then returns the appropriate Unicode box-drawing character.

Parameters

lines

any[]

Screen buffer lines

x

number

X coordinate

y

number

Y coordinate

Returns

string

Unicode box-drawing character for this position

---

draw()

draw(start, end): void

Defined in: packages/core/src/widgets/screen.ts:1307

Draw the screen based on the contents of the screen buffer. Compares the pending buffer (lines) with the output buffer (olines) and writes only the changes to minimize terminal output. Handles SGR codes, cursor positioning, double-width characters, and terminal-specific optimizations.

Parameters

start

number

Starting line number

end

number

Ending line number

Returns

void

---

_reduceColor()

_reduceColor(color): number

Defined in: packages/core/src/widgets/screen.ts:1664

Internal method to reduce color values to the number of colors supported by the terminal.

Parameters

color

number

Color value to reduce

Returns

number

Reduced color value

---

attrCode()

attrCode(code, cur, def): number

Defined in: packages/core/src/widgets/screen.ts:1677

Convert an SGR escape code string to blessed's internal attribute format. Parses SGR sequences like "\x1b[1;31m" and returns a packed integer containing flags (bold, underline, etc.), foreground color, and background color.

Parameters

code

string

SGR escape code string

cur

number

Current attribute value

def

number

Default attribute value

Returns

number

Packed attribute integer

---

codeAttr()

codeAttr(code): string

Defined in: packages/core/src/widgets/screen.ts:1797

Convert blessed's internal attribute format to an SGR escape code string. Unpacks the attribute integer and generates the appropriate SGR sequence for terminal output.

Parameters

code

number

Packed attribute integer

Returns

string

SGR escape code string

---

focusOffset()

focusOffset(offset): any

Defined in: packages/core/src/widgets/screen.ts:1902

Focus element by offset of focusable elements. Moves focus forward or backward through the list of focusable elements in tab order, skipping detached or hidden elements.

Parameters

offset

number

Number of elements to move (positive for forward, negative for backward)

Returns

any

The newly focused element, or undefined if no element was found

---

focusPrev()

focusPrev(): any

Defined in: packages/core/src/widgets/screen.ts:1950

Focus previous element in the index. Shorthand for focusOffset(-1).

Returns

any

The newly focused element

---

focusPrevious()

focusPrevious(): any

Defined in: packages/core/src/widgets/screen.ts:1959

Focus previous element in the index. Alias for focusPrev().

Returns

any

The newly focused element

---

focusNext()

focusNext(): any

Defined in: packages/core/src/widgets/screen.ts:1968

Focus next element in the index. Shorthand for focusOffset(1).

Returns

any

The newly focused element

---

focusPush()

focusPush(el): void

Defined in: packages/core/src/widgets/screen.ts:1977

Push element on the focus stack (equivalent to screen.focused = el). Maintains a history of up to 10 focused elements for focus management.

Parameters

el

any

Element to focus

Returns

void

---

focusPop()

focusPop(): any

Defined in: packages/core/src/widgets/screen.ts:1992

Pop element off the focus stack. Removes the current element from focus and returns focus to the previous element.

Returns

any

The element that was popped from the focus stack

---

saveFocus()

saveFocus(): any

Defined in: packages/core/src/widgets/screen.ts:2005

Save the focused element. Stores the currently focused element for later restoration via restoreFocus().

Returns

any

The saved focused element

---

restoreFocus()

restoreFocus(): any

Defined in: packages/core/src/widgets/screen.ts:2014

Restore the saved focused element. Returns focus to the element saved by saveFocus().

Returns

any

The newly focused element

---

rewindFocus()

rewindFocus(): any

Defined in: packages/core/src/widgets/screen.ts:2027

"Rewind" focus to the last visible and attached element. Walks backward through the focus history to find an element that is still visible and attached to the screen.

Returns

any

The element that received focus, or undefined if none found

---

_focus()

_focus(self, old): void

Defined in: packages/core/src/widgets/screen.ts:2052

Internal method to handle focus changes. Automatically scrolls scrollable ancestors to bring the focused element into view, and emits focus/blur events.

Parameters

self

any

Element receiving focus

old

any

Element losing focus

Returns

void

---

clearRegion()

clearRegion(xi, xl, yi, yl, override?): void

Defined in: packages/core/src/widgets/screen.ts:2098

Clear any region on the screen. Fills the region with spaces using the default attribute.

Parameters

xi

number

Left X coordinate

xl

number

Right X coordinate

yi

number

Top Y coordinate

yl

number

Bottom Y coordinate

override?

boolean

If true, always write even if cell hasn't changed

Returns

void

---

fillRegion()

fillRegion(attr, ch, xi, xl, yi, yl, override?): void

Defined in: packages/core/src/widgets/screen.ts:2119

Fill any region with a character of a certain attribute. Used for clearing regions, drawing backgrounds, etc.

Parameters

attr

number

Attribute to fill with

ch

string

Character to fill with

xi

number

Left X coordinate

xl

number

Right X coordinate

yi

number

Top Y coordinate

yl

number

Bottom Y coordinate

override?

boolean

If true, always write even if cell hasn't changed

Returns

void

---

key()

key(...args): any

Defined in: packages/core/src/widgets/screen.ts:2154

Bind a key event handler.

Parameters

args

...any[]

Arguments to pass to program.key()

Returns

any

The bound key handler

---

onceKey()

onceKey(...args): any

Defined in: packages/core/src/widgets/screen.ts:2163

Bind a key event handler that fires only once.

Parameters

args

...any[]

Arguments to pass to program.onceKey()

Returns

any

The bound key handler

---

unkey()

unkey(...args): any

Defined in: packages/core/src/widgets/screen.ts:2172

Unbind a key event handler.

Parameters

args

...any[]

Arguments to pass to program.unkey()

Returns

any

Result of unbinding

---

removeKey()

removeKey(...args): any

Defined in: packages/core/src/widgets/screen.ts:2182

Remove a key event handler. Alias for unkey().

Parameters

args

...any[]

Arguments to pass to program.removeKey()

Returns

any

Result of removing

---

spawn()

spawn(file, args?, options?): any

Defined in: packages/core/src/widgets/screen.ts:2194

Spawn a process in the foreground, return to blessed app after exit. Temporarily leaves the alternate screen buffer and restores it after the process exits.

Parameters

file

string

Command to execute

args?

any

Arguments to pass to the command

options?

any

Options to pass to child_process.spawn

Returns

any

ChildProcess instance

---

exec()

exec(file, args?, options?, callback?): any

Defined in: packages/core/src/widgets/screen.ts:2265

Spawn a process in the foreground, return to blessed app after exit. Executes callback on error or exit.

Parameters

file

string

Command to execute

args?

any

Arguments to pass to the command

options?

any

Options to pass to child_process.spawn

callback?

any

Callback function (err, success)

Returns

any

ChildProcess instance

---

readEditor()

readEditor(options, callback?): any

Defined in: packages/core/src/widgets/screen.ts:2288

Read data from text editor. Spawns the user's $EDITOR (or vi) to edit a temporary file, then returns the contents.

Parameters

options

any

Options object or callback function

callback?

any

Callback function (err, data)

Returns

any

Result of the editor operation

---

displayImage()

displayImage(file, callback?): any

Defined in: packages/core/src/widgets/screen.ts:2344

Display an image in the terminal using w3m. Experimental feature that spawns w3m to render images.

Parameters

file

string

Path to image file

callback?

any

Callback function (err, success)

Returns

any

Result of the display operation

---

setEffects()

setEffects(el, fel, over, out, effects, temp?): void

Defined in: packages/core/src/widgets/screen.ts:2398

Set effects based on two events and attributes. Used to apply hover and focus effects to elements. When the 'over' event fires, the effects are applied; when the 'out' event fires, the effects are removed.

Parameters

el

any

Element to apply effects to (or function returning element)

fel

any

Element to listen for events on

over

any

Event name to trigger effects (e.g., 'mouseover')

out

any

Event name to remove effects (e.g., 'mouseout')

effects

any

Style object with effects to apply

temp?

any

Property name to store temporary state in

Returns

void

---

sigtstp()

sigtstp(callback?): void

Defined in: packages/core/src/widgets/screen.ts:2465

Handle SIGTSTP signal (Ctrl+Z). Sets up a handler to properly restore the screen after the process is resumed.

Parameters

callback?

any

Optional callback to execute after resume

Returns

void

---

copyToClipboard()

copyToClipboard(text): boolean

Defined in: packages/core/src/widgets/screen.ts:2480

Attempt to copy text to clipboard using iTerm2's proprietary sequence. Returns true if successful. Only works in iTerm2 with the proper terminal sequences enabled.

Parameters

text

string

Text to copy to clipboard

Returns

boolean

True if successful

---

cursorShape()

cursorShape(shape?, blink?): boolean

Defined in: packages/core/src/widgets/screen.ts:2491

Attempt to change cursor shape. Will not work in all terminals (see artificial cursors for a solution to this). Returns true if successful.

Parameters

shape?

string

Cursor shape ('block', 'underline', 'line', or style object)

blink?

boolean

Whether the cursor should blink

Returns

boolean

True if successful

---

cursorColor()

cursorColor(color): boolean

Defined in: packages/core/src/widgets/screen.ts:2537

Attempt to change cursor color. Returns true if successful. Only works in terminals that support the cursor color escape sequence.

Parameters

color

any

Color name or code

Returns

boolean

True if successful

---

cursorReset()

cursorReset(): boolean

Defined in: packages/core/src/widgets/screen.ts:2553

Attempt to reset cursor. Returns true if successful. Restores cursor to default shape, color, and blink state.

Returns

boolean

True if successful

---

resetCursor()

resetCursor(): boolean

Defined in: packages/core/src/widgets/screen.ts:2583

Reset cursor (alias for cursorReset() for backward compatibility).

Returns

boolean

True if successful

---

_cursorAttr()

_cursorAttr(cursor, dattr?): any

Defined in: packages/core/src/widgets/screen.ts:2594

Internal method to calculate cursor attribute for artificial cursor rendering. Determines the correct attribute and character for rendering the cursor at a given position.

Parameters

cursor

any

Cursor configuration object

dattr?

number

Default attribute (optional)

Returns

any

Object with 'ch' (character) and 'attr' (attribute) properties

---

screenshot()

screenshot(xi?, xl?, yi?, yl?, term?): string

Defined in: packages/core/src/widgets/screen.ts:2661

Take an SGR screenshot of the screen within the region. Returns a string containing only characters and SGR codes. Can be displayed by simply echoing it in a terminal.

Parameters

xi?

number

Left X coordinate (default: 0)

xl?

number

Right X coordinate (default: screen width)

yi?

number

Top Y coordinate (default: 0)

yl?

number

Bottom Y coordinate (default: screen height)

term?

any

Terminal object to screenshot from (default: this screen)

Returns

string

SGR-encoded screenshot string

---

_getPos()

_getPos(): any

Defined in: packages/core/src/widgets/screen.ts:2761

Internal method to get position coordinates. For Screen, this always returns itself since Screen is the root container.

Returns

any

This screen instance