ink-cartridge
    Preparing search index...

    Interface SequenceOptions

    Options for KeyboardEngine.boundSequence.

    Extends BoundKeyboardOptions with sequence-specific settings: a per-sequence timeout and an exclusive flag that controls behavior when a mismatched key is pressed during a pending sequence.

    interface SequenceOptions {
        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, the binding stops responding once any layer is present on screen; it only takes effect while no layers are open.

    Enabling this on a binding registered inside a layer has no effect — it only works when enabled on the page. Note that when a page exists without any layers and no elementId is passed, the option takes effect and the binding data is placed on the current page.

    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