smudgy:widgets — Controls

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

Accept clicks, choices, and text from the player. Checkbox and Radio are controlled components: update the value supplied to them from their callback.

For state bindings and complete examples, see Add controls and tables to a widget.

export function Button(props?: ButtonProps, children?: WidgetChildren): SmudgyElement;

A clickable button.

export interface ButtonProps {
    width?: Bindable<WidgetLength>;
    height?: Bindable<WidgetLength>;
    variant?: ButtonVariant;
    onPress?: () => void;
    children?: WidgetChildren;
}

Props for a clickable button. A single non-text child is used as the label element; otherwise the text children are rendered as the label.

• variant — Emphasis style. Default “subtle”.
• onPress — Called when the button is pressed.

export type ButtonVariant = "primary" | "secondary" | "subtle" | "link";

A button emphasis variant, mapping to the theme's named button styles.

export function Checkbox(props?: CheckboxProps, children?: WidgetChildren): SmudgyElement;

A checkbox. Children are the label.

export interface CheckboxProps {
    checked?: Bindable<boolean>;
    onToggle?: (checked: boolean) => void;
    size?: Bindable<number>;
    text_size?: Bindable<number>;
    children?: WidgetChildren;
}

Props for a checkbox. Its children form the label and may include bindings.

A checkbox displays the value supplied through checked. To make it respond visibly to a click, bind checked to state and update that state from onToggle:

 import { createState } from "smudgy:core";
 import { Checkbox } from "smudgy:widgets";
 
 const cfg = createState<{ autoloot: boolean }>("preferences");
 cfg.set({ autoloot: false });
 
 export const autolootControl = (
   <Checkbox checked={cfg.bind("autoloot")}
             onToggle={(checked) => { cfg.value.autoloot = checked; }}>
     Autoloot
   </Checkbox>
 );

Without onToggle, the checkbox is disabled and can be used as a read-only indicator. If checked is a fixed value, a click still calls onToggle, but the displayed value changes only when the caller supplies a different value.

• checked — Whether the box is checked. Default false.
• onToggle — Called with the new state on click. Omitted, the checkbox renders disabled.
• size — Box size in pixels.
• text_size — Label text size in pixels.

export function Radio(props: RadioProps, children?: WidgetChildren): SmudgyElement;

One radio button; radios sharing a selected source form a group.

export interface RadioProps {
    value: string | number;
    selected?: Bindable<string | number>;
    onSelect: (value: string) => void;
    size?: Bindable<number>;
    text_size?: Bindable<number>;
    children?: WidgetChildren;
}

Props for one radio button. Its children form the label.

Smudgy does not provide a separate RadioGroup component. Radios that read and update the same selected state behave as one group, even when they appear in different layouts:

 import { createState } from "smudgy:core";
 import { Radio, Row } from "smudgy:widgets";
 
 const cfg = createState<{ mode: string }>("preferences");
 cfg.set({ mode: "fast" });
 const selectMode = (mode: string) => { cfg.value.mode = mode; };
 
 export const modeControls = (
   <Row>
     <Radio value="fast" selected={cfg.bind("mode")} onSelect={selectMode}>Fast</Radio>
     <Radio value="careful" selected={cfg.bind("mode")} onSelect={selectMode}>Careful</Radio>
   </Row>
 );

• value — This radio's own value. Selection compares it (as a string) against selected.
• selected — The currently selected value. This radio renders selected when it equals value by string spelling (numbers compare as their decimal text).
• onSelect — Called with this radio's value on click. Required – a radio without a handler would render clickable and do nothing; use Text for display-only markers.
• size — Dot size in pixels.
• text_size — Label text size in pixels.

export function TextEditor(props?: TextEditorProps, children?: WidgetChildren): SmudgyElement;

A multi-line text editor. Read its text via the onChange callback.

export interface TextEditorProps {
    id?: string;
    value?: string;
    onChange?: (text: string) => void;
    placeholder?: string;
    height?: WidgetLength;
    padding?: number;
    size?: number;
    children?: WidgetChildren;
}

Props for a multi-line text editor (a leaf – children are ignored).

• id — A stable identity for the editing buffer: two editors with different ids edit independently. Omitted, sibling editors are still kept distinct.
• value — The editor's starting text. In-progress edits are preserved; a script reload resets the editor to value.
• onChange — Called with the full text on each edit (not on cursor/selection movements).
• placeholder — Placeholder shown when empty.
• height — Viewport height. When set, taller text scrolls. Unset, the editor grows to fit its content.
• padding — Padding around the text, in pixels.
• size — Text size in pixels.

export function Tooltip(props: TooltipProps, children?: WidgetChildren): SmudgyElement;

A hover tooltip around its single child.

export type TooltipPosition = "top" | "bottom" | "left" | "right" | "cursor";

Where a tooltip appears relative to its target.

export interface TooltipProps {
    tip: string | number | Binding<any> | SmudgyElement | false | null;
    position?: TooltipPosition;
    gap?: Bindable<number>;
    children?: WidgetChildren;
}

Props for a hover tooltip. The first child is the hover target. A string, number, or binding renders in the standard tooltip style. An element uses the styles declared by that element.

• tip — The tooltip content. A false or null value suppresses the tooltip, so a conditional expression such as tip={cond && "hint"} is supported.
• position — Which side of the target the tip appears on, or "cursor" to follow the pointer. Default “top”.
• gap — Distance between target and tip, in pixels.

Script API reference · ← smudgy:widgets — Layout & overlays · smudgy:widgets — Text & data display → · Scripting manual