@snap/camera-kit/dist/session/LensKeyboard.d.ts

Camera Kit Web

import { TypedCustomEvent } from "../events/TypedCustomEvent";
import type { TypedEventListener, TypedEventListenerOptions } from "../events/TypedEventTarget";
import type { UriHandler } from "../uri-handlers/UriHandlers";
import type { Lens } from "../lens/Lens";
import type { LensState } from "./lensState";
/**
 * "active" event payload.
 *
 * This event is emitted when a lens requests a keyboard to be shown or dismissed.
 * The application should listen for this event and display or remove its keyboard UI accordingly.
 */
export interface KeyboardActiveEvent {
    /**
     * Indicates whether the keyboard should be displayed (`true`) or hidden (`false`).
     */
    active: boolean;
    /**
     * The current text input associated with the keyboard.
     */
    text: string;
    /**
     * The lens that initiated the keyboard request.
     */
    lens: Lens;
    /**
     * @deprecated Clients apps are responsible to create keyboard UI.
     */
    element: HTMLTextAreaElement;
}
/**
 * Defines events emitted by the `Keyboard` API.
 */
export type KeyboardEvents = TypedCustomEvent<"active", KeyboardActiveEvent>;
/**
 * Listener of {@link KeyboardEvents} events.
 */
export type KeyboardEventListener = TypedEventListener<KeyboardEvents>;
/**
 * The `Keyboard` API enables applications to handle text input requests triggered by lenses.
 *
 * Lenses can request a keyboard display by emitting an `active` event. The application is responsible for displaying
 * a keyboard UI in response to this event.
 *
 * As users type, the application sends the typed text back to the lens using {@link Keyboard.sendInputToLens},
 * allowing the lens to display the text accordingly.
 *
 * Lenses can also request the keyboard to be dismissed. When this happens, the application receives an event
 * and should remove the displayed keyboard UI.
 *
 * @example
 * ```ts
 * cameraKitSession.keyboard.addEventListener('active', ({ detail }) => {
 *   const { active, text } = detail;
 *   if (active) {
 *     showKeyboard(text, (newText) => cameraKitSession.keyboard.sendInputToLens(newText));
 *   } else {
 *     hideKeyboard();
 *   }
 * });
 * ```
 *
 * @category Lenses
 */
export interface Keyboard {
    /**
     * Adds an event listener for keyboard-related events.
     *
     * @param type - The type of event to listen for (e.g., "active").
     * @param callback - Function that handles the event.
     * @param options - Additional options for event listener behavior (optional).
     */
    addEventListener: (type: "active", callback: KeyboardEventListener, options?: TypedEventListenerOptions) => void;
    /**
     * Removes a previously added event listener.
     *
     * @param type - The type of event to remove.
     * @param callback - The event listener function to remove.
     */
    removeEventListener: (type: "active", callback: KeyboardEventListener) => void;
    /**
     * Sends a string of text to the active lens. The application should use this method
     * to provide user-typed input to the lens for display.
     *
     * @param text - The text to send to the lens. Supports escape sequences (e.g., `\n` for multiline input).
     */
    sendInputToLens: (text: string) => void;
    /**
     * Dismisses the keyboard, clears the text input, and triggers an `active` event with `active: false`.
     * Applications can use this to remove on-screen text input elements when input is no longer needed.
     */
    dismiss: () => void;
    /**
     * @deprecated Clients apps are responsible to create keyboard UI.
     */
    getElement: () => HTMLTextAreaElement;
}
/** @internal */
export declare class LensKeyboard {
    private readonly lensState;
    readonly uriHandler: UriHandler;
    private readonly events;
    private readonly element;
    private active;
    private text;
    private reply;
    constructor(lensState: LensState);
    dismiss(): void;
    getElement(): HTMLTextAreaElement;
    sendInputToLens(text: string): void;
    addEventListener(type: "active", callback: KeyboardEventListener, options?: TypedEventListenerOptions): void;
    removeEventListener(type: "active", callback: KeyboardEventListener): void;
    toPublicInterface(): Keyboard;
    destroy(): void;
    private sendReply;
    private notifyClient;
    private onElementKeyPress;
}
/**
 * Factory function for creating a LensKeyboard instance.
 *
 * @internal
 */
export declare const lensKeyboardFactory: {
    (args_0: import("@snap/state-management").StateMachine<import("@snap/state-management").Action<"applyLens", {
        lens: Lens;
        launchData?: import("..").LensLaunchData | undefined;
    }> | import("@snap/state-management").Action<"downloadComplete", Lens> | import("@snap/state-management").Action<"turnedOn", Lens> | import("@snap/state-management").Action<"resourcesLoaded", Lens> | import("@snap/state-management").Action<"firstFrameProcessed", Lens> | import("@snap/state-management").Action<"applyLensComplete", Lens> | import("@snap/state-management").Action<"applyLensFailed", {
        error: import("./lensState").LensErrors;
        lens: Lens;
    }> | import("@snap/state-management").Action<"applyLensAborted", Lens> | import("@snap/state-management").Action<"removeLens", undefined> | import("@snap/state-management").Action<"turnedOff", Lens> | import("@snap/state-management").Action<"removeLensComplete", undefined> | import("@snap/state-management").Action<"removeLensFailed", Error>, import("@snap/state-management").State<"noLensApplied", undefined> | import("@snap/state-management").State<"applyingLens", Lens> | import("@snap/state-management").State<"lensApplied", Lens>>): LensKeyboard;
    token: "lensKeyboard";
    dependencies: readonly ["lensState"];
};
//# sourceMappingURL=LensKeyboard.d.ts.map