@cartridge-engine/keyboard-engine
    Preparing search index...

    Interface PageSequenceOptions

    Sequence options for bindings registered on a page (screen) layer.

    Extends SequenceOptions with the page-only stopsWorkingAfterLayerAppearing option.

    interface PageSequenceOptions {
        elementId?: string;
        exclusive?: boolean;
        focusId?: string | FocusRef;
        mode?: string;
        observer?: (remaining: number) => void;
        once?: boolean;
        stopsWorkingAfterLayerAppearing: boolean;
        timeout?: number;
        times?: number;
        when?: string | (() => boolean);
    }

    Hierarchy (View Summary)

    Index
    elementId? exclusive? focusId? mode? observer? once? stopsWorkingAfterLayerAppearing timeout? times? when?
    elementId?: string

    When set, binds the keyboard data to the element with this ID on the current layer.

    exclusive?: boolean

    Controls behaviour when a key is pressed that does NOT match the next key expected by a pending sequence.

    • false (default): the mismatched key cancels the pending sequence and falls through to normal boundKeyboard bindings.
    • true: the mismatched key is silently consumed — the sequence keeps waiting until the timeout expires or the correct key arrives. This allows the user to correct a mistaken key without triggering side effects from normal bindings.
    focusId?: string | FocusRef

    Focus target in which the binding must be active to take effect. A plain string binds the key to the default focus layer; an explicit group binds it to that group.

    mode?: string

    Restrict this binding to a specific mode set via KeyboardEngine.setMode.

    When the active mode (read from the pipeline context) does not match this value, the binding is skipped as if it does not exist — the event continues to the next binding or layer. When omitted, the binding fires in all modes (including no-mode, i.e. currentMode === null).

    Modes must be registered before use — via EngineProps.modes or KeyboardEngine.addMode.

    // Only active in insert mode
    boundKeyboard('*', handleInput, { mode: 'insert' });

    // Only active in normal mode
    boundKeyboard('j', moveDown, { mode: 'normal' });

    // Active in all modes (default)
    boundKeyboard('ctrl+q', quit);
    observer?: (remaining: number) => void

    Callback invoked on every key press while counting toward times. Receives the number of remaining presses before the handler fires. Requires times to be set; throws at registration otherwise.

    Type Declaration

      • (remaining: number): void

      • Parameters

        • remaining: number

          How many more presses are needed before the handler fires.

        Returns void

    once?: boolean

    When true, the binding is automatically removed after its first invocation. The unbind happens before the handler executes, so even if the handler throws, the binding is consumed.

    Useful for one-shot key bindings (e.g. "press any key to continue").

    stopsWorkingAfterLayerAppearing: boolean

    When true, this binding stops responding after its owning layer has appeared on screen. The binding is only active before the layer renders for the first time — once the layer becomes visible, any subsequent key presses matching this entry are silently ignored.

    timeout?: number

    Maximum time in milliseconds between key presses within a sequence. The timer starts when the first key is pressed and resets on each matching key. If it expires before the full sequence is entered, the pending state is cancelled.

    500
    times?: number

    Number of times the bound key(s) must be pressed before the handler fires. Defaults to undefined (fire immediately on every press).

    The counter is per-binding (all keys in the keys array share the same counter) and never auto-resets. When the counter reaches times, the handler fires and the counter resets to 0.

    When combined with once: true, the binding is removed after the handler fires (i.e. after times presses).

    Must be >= 1. Throws if 0 or negative.

    Examples:

    • times: 2 → handler fires on the 2nd, 4th, 6th… press.
    • times: 3, once: true → handler fires on the 3rd press and unbinds.
    when?: string | (() => boolean)

    Optional condition callback. When provided, the binding only fires if this callback returns true at the moment of the key press.

    When false, the binding is skipped — the event continues to the next binding or layer. This is an AND relationship with elementId / focusId.

    Examples:

    • when: () => isEditing — binding only active during editing
    • when: () => isEditing && !isReadOnly

    Settings
    Member Visibility

    On This Page
    Properties