smudgy:widgets — Overview

Generated from smudgy v0.4.2-dev (smudgy-widgets.d.ts @ e96061b683ea). Index: scriptref.

Mount script-created interfaces, work with shared widget types, and use JSX from a .tsx module. Import the runtime functions and components from smudgy:widgets.

Choose a component reference by purpose:

• Layout & overlays
• Controls
• Text & data display
• Canvas

For a guided introduction, see Build on-screen widgets.

export function createWidget(
    name: string,
    element: SmudgyElement,
    options?: CreateWidgetOptions,
): void;

Put a widget on screen (or replace the one already mounted under name). Re-mounting an existing name keeps its enabled state, and moves the widget when options.pane changes.

export function removeWidget(name: string): void;

Remove a previously-mounted named widget.

export interface CreateWidgetOptions {
    pane?: Pane | string;
}

Options for createWidget.

• pane — The session pane to mount into: a Pane handle from smudgy:core, or a pane name ("main" is the main pane). Defaults to the main pane.

export type Element = SmudgyElement;

An element returned by a widget component.

export type Length = WidgetLength;

A widget size: pixels, "fill", or "shrink".

export type Children = WidgetChildren;

The values accepted as component children.

export type Bindable<T> = T | Binding<T>;

A prop that takes a value or a live state binding (handle.bind(...) from smudgy:core). Bound props track the published value on their own – the widget repaints on each update, with no handler and no re-mount.

export type HorizontalAlign = "left" | "start" | "center" | "right" | "end";

Horizontal alignment within a container.

export type VerticalAlign = "top" | "start" | "center" | "bottom" | "end";

Vertical alignment within a container.

interface SmudgyElement {
    readonly __smudgyWidgetElement: true;
}

One piece of on-screen UI, returned by every component below. Build it, nest it as a child of another component, or mount it with createWidget; it is not inspectable from JS.

type WidgetLength = number | "fill" | "shrink";

A size: a number of pixels, "fill" (take all available space), or "shrink" (hug the contents).

type WidgetChild =
| SmudgyElement
| string
| number
| boolean
| null
| undefined
| import("smudgy:core").Binding<any>;

Anything a component accepts as a child: another element, text (a string or number), a state binding (rendered as live text – see bind() in smudgy:core), or null/undefined/false (dropped, so cond && <Text/> works), plus arrays of the above (flattened).

type WidgetChildren = WidgetChild | WidgetChild[];

One child or a flat array of children accepted by a widget component.

export function jsx(type: unknown, props: Record<string, unknown>, key?: unknown): SmudgyElement;

The automatic-JSX factory for elements.

export function jsxs(type: unknown, props: Record<string, unknown>, key?: unknown): SmudgyElement;

The automatic-JSX factory for elements with multiple children.

export function Fragment(props: { children?: WidgetChildren }): SmudgyElement;

Groups children with no wrapper element (<>...</>).

export namespace JSX {
    type Element = SmudgyElement;
    // No host string tags -- every JSX tag must be a widget component function.
    interface IntrinsicElements {}
    interface ElementChildrenAttribute {
        children: {};
    }
}

The JSX namespace TypeScript resolves for jsxImportSource: "smudgy:widgets".

Support type used by signatures on this page.

interface WidgetsApi {
    Column: typeof Column;
    Row: typeof Row;
    Stack: typeof Stack;
    Container: typeof Container;
    Text: typeof Text;
    ProgressBar: typeof ProgressBar;
    Scrollable: typeof Scrollable;
    Markdown: typeof Markdown;
    Modal: typeof Modal;
    TextEditor: typeof TextEditor;
    Button: typeof Button;
    MapView: typeof MapView;
    Canvas: typeof Canvas;
    Space: typeof Space;
    Checkbox: typeof Checkbox;
    Radio: typeof Radio;
    Tooltip: typeof Tooltip;
    Table: typeof Table;
    createWidget: typeof createWidget;
    removeWidget: typeof removeWidget;
    extractMarkdownLinks: typeof extractMarkdownLinks;
}

The default export bundles every member above.

The module's default export (api).

const api: WidgetsApi;

Script API reference · ← smudgy:core — Panes · smudgy:widgets — Layout & overlays → · Scripting manual