@teaui/core/.dist/Viewport.d.ts

A high-level terminal UI library for Node

import type { Terminal } from './terminal.js';
import { Style } from './Style.js';
import { Rect, Point, Size } from './geometry.js';
import { Screen } from './Screen.js';
import { View } from './View.js';
import type { Modal } from './components/Modal.js';
import type { HotKeyDef, MouseEventListenerName } from './events/index.js';
/**
 * Defines a region (contentSize) in which to draw, and a subset (visibleRect) that
 * is on-screen. Anything not in the visibleRect is considered invisible (and any
 * drawing outside the rect will be clipped)
 */
export declare class Viewport {
    #private;
    /**
     * For modals, this is the Rect of the view that presented the modal, in absolute
     * coordinates
     */
    parentRect: Rect;
    constructor(screen: Screen, terminal: Terminal, contentSize: Size);
    /**
     * during render, `contentSize` is what you should use for laying out your
     * rectangles. in most cases this is synonymous with "visible" area, but not
     * always.
     */
    get contentSize(): Size;
    /**
     * In most cases, `availableRect` is synonymous with `contentRect`, but in some
     * rare cases (e.g. drawing on top of box borders) the `availableRect` is larger.
     * The available Rect will always be positioned outside or overlapping the
     * `contentRect`, i.e.
     *     availableRect.origin.x <= 0
     *     availableRect.origin.y <= 0
     *     availableRect.size.width >= contentRect.size.width
     *     availableRect.size.height >= contentRect.size.height
     */
    get availableRect(): Rect;
    get visibleRect(): Rect;
    get contentRect(): Rect;
    get isEmpty(): boolean;
    /**
     * Request that a modal be presented above the current view tree.
     * The modal receives `presentedRect` (this view's absolute rect) and
     * `windowSize` (the full screen size) before rendering.
     *
     * @return boolean Whether the modal creation was successful
     */
    requestModal(modal: Modal): boolean;
    registerHotKey(key: HotKeyDef): void;
    /**
     * Registers the current view as a fallback keyboard listener. Key events that
     * aren't consumed by hotkeys or a focused view are sent to the innermost
     * (last registered) keyboard listener.
     */
    registerKeyboard(): void;
    /**
     * @return boolean Whether the current render target is the focus view
     */
    registerFocus(opts?: {
        isDefault?: boolean;
    }): boolean;
    /**
     * @see MouseManager.registerMouse
     */
    registerMouse(eventNames: MouseEventListenerName | MouseEventListenerName[], rect?: Rect): void;
    registerTick(): void;
    /**
     * Clears out, and optionally "paints" default foreground/background colors. If no
     * region is provided, the entire visibleRect is painted.
     */
    paint(defaultStyle: Style, region?: Point | Rect): void;
    /**
     * Replaces the style of existing cells without changing their text content.
     * Useful for dimming background content (e.g. modal overlays).
     * If no region is provided, the entire visibleRect is restyled.
     */
    restyle(style: Style, region?: Rect): void;
    /**
     * Does not support newlines (no default wrapping behavior),
     * always prints left-to-right.
     */
    write(input: string, to: Point, style?: Style): void;
    /**
     * Forwards 'meta' ANSI sequences (see ITerm) to the terminal
     */
    writeMeta(str: string): void;
    /**
     * Assigns a drawing style and starts drawing using it.
     */
    usingPen(style: Style | undefined, draw: (pen: Pen) => void): void;
    /**
     * Starts a drawing session, inheriting the current style as the default.
     * The drawing callback receives the 'pen', and can use
     * 'pen.replacePen(style)' to update the current style.
     */
    usingPen(draw: (pen: Pen) => void): void;
    _render(view: View, clip: Rect, draw: (viewport: Viewport) => void): void;
    clipped(clip: Rect, draw: (viewport: Viewport) => void): void;
    clipped(clip: Rect, style: Style, draw: (viewport: Viewport) => void): void;
    /**
     * Shifts the viewport origin inward (to `rect.origin`) and sets contentSize to
     * `rect.size`, without changing the clip boundary. This makes `availableRect`
     * extend beyond `contentRect` so children can draw "on top of" the surrounding
     * area (e.g. box borders).
     *
     * Must be called inside a `clipped()` callback — the enclosing `clipped` will
     * restore the previous state.
     *
     *     viewport.clipped(outerRect, inside => {
     *       inside.inset(innerRect)
     *       super.render(inside)
     *     })
     */
    inset(rect: Rect, draw: (viewport: Viewport) => void): void;
}
declare class Pen {
    #private;
    constructor(initialStyle: Style, setter: (style?: Style) => void);
    /**
     * Used in Text drawing components - the component usually defines a starting
     * style (`viewport.usingPen(style, pen => {})`), and as it prints characters
     * (`char of unicode.printableChars(line)`) it will detect 0-width SGR codes
     * (`unicode.charWidth(char) === 0`). These codes can be used to create a `Style`
     * object (`Style.fromSGR(char)`).
     *
     * SGR codes do support turn-on/turn-off, but this doesn't work well when, say, the
     * default style already has certain features turned on. For instance, if the
     * string specifies one region to be bold, but the entire Text component is meant
     * to be bold, the behaviour of "turn-off-bold" is actually incorrect here.
     *
     * This is why the `fromSGR` method accepts the default style - it can be compared
     * with the SGR state to determine what to do.
     */
    mergePen(style: Style): void;
    /**
     * replacePen is better when you need to control the drawing style, but you will
     * assign the entire desired style.
     */
    replacePen(style: Style): void;
}
export {};