@league-of-foundry-developers/foundry-vtt-types 0.8.9-7 → 9.238.1

package/src/foundry/foundry.js/keyboardManager.d.ts

@@ -8,144 +8,174 @@ declare class KeyboardManager {
   /**
    * The set of key codes which are currently depressed (down)
    */
-  protected _downKeys: Set<string>;
+  downKeys: Set<string>;
 
   /**
-   * The set of key codes which have been already handled per workflow
+   * The set of movement keys which were recently pressed
    */
-  protected _handled: Set<string>;
+  moveKeys: Set<string>;
 
   /**
-   * A mapping of movement keys which are pending
+   * Allowed modifier keys
    */
-  protected _moveKeys: Set<string>;
-
-  /**
-   * @defaultValue `null`
-   */
-  protected _moveTime: number | null;
-
-  /**
-   * @defaultValue `0`
-   */
-  protected _tabState: 0 | 1;
+  static MODIFIER_KEYS: {
+    CONTROL: 'Control';
+    SHIFT: 'Shift';
+    ALT: 'Alt';
+  };
 
   /**
-   * @defaultValue `0`
+   * Track which KeyboardEvent#code presses associate with each modifier
    */
-  protected _wheelTime: number;
+  static MODIFIER_CODES: {
+    Alt: ['AltLeft', 'AltRight'];
+    Control: ['ControlLeft', 'ControlRight', 'MetaLeft', 'MetaRight'];
+    Shift: ['ShiftLeft', 'ShiftRight'];
+  };
 
   /**
-   * Specify a rate limit for mouse wheel to gate repeated scrolling.
-   * This is especially important for continuous scrolling mice which emit hundreds of events per second.
-   * This designates a minimum number of milliseconds which must pass before another wheel event is handled
-   */
-  static MOUSE_WHEEL_RATE_LIMIT: 50;
+   * Key codes which are "protected" and should not be used because they are reserved for browser-level actions.
+   */
+  static PROTECTED_KEYS: ['F5', 'F11', 'F12', 'PrintScreen', 'ScrollLock', 'NumLock', 'CapsLock'];
+
+  /** The OS-specific string display for what their Command key is */
+  static CONTROL_KEY_STRING: '⌘' | 'Control';
+
+  /**
+   * An special mapping of how special KeyboardEvent#code values should map to displayed strings or symbols.
+   * Values in this configuration object override any other display formatting rules which may be applied.
+   */
+  static KEYCODE_DISPLAY_MAPPING: {
+    ArrowLeft: '🡸';
+    ArrowRight: '🡺';
+    ArrowUp: '🡹';
+    ArrowDown: '🡻';
+    Backquote: '`';
+    Backslash: '\\';
+    BracketLeft: '[';
+    BracketRight: ']';
+    Comma: ',';
+    Equal: '=';
+    MetaLeft: '⌘' | '⊞';
+    Minus: '-';
+    NumpadAdd: 'Numpad+';
+    NumpadSubtract: 'Numpad-';
+    Period: '.';
+    Quote: "'";
+    Semicolon: ';';
+    Slash: '/';
+  };
 
   /**
-   * Enumerate the "digit keys"
+   * Test whether an input currently has focus
    */
-  static DIGIT_KEYS: ['1', '2', '3', '4', '5', '6', '7', '8', '9', '0'];
+  get hasFocus(): boolean;
 
   /**
-   * Map keys used for movement
+   * Emulates a key being pressed, triggering the Keyboard event workflow.
+   * @param up       - If True, emulates the `keyup` Event. Else, the `keydown` event
+   * @param code     - The KeyboardEvent#code which is being pressed
+   * @param altKey   - Emulate the ALT modifier as pressed
+   *                   (default: `false`)
+   * @param ctrlKey  - Emulate the CONTROL modifier as pressed
+   *                   (default: `false`)
+   * @param shiftKey - Emulate the SHIFT modifier as pressed
+   *                   (default: `false`)
+   * @param repeat   - Emulate this as a repeat event
+   *                   (default: `false`)
    */
-  static MOVEMENT_KEYS: {
-    w: ['up'];
-    a: ['left'];
-    s: ['down'];
-    d: ['right'];
-    W: ['up'];
-    A: ['left'];
-    S: ['down'];
-    D: ['right'];
-    ArrowUp: ['up'];
-    ArrowRight: ['right'];
-    ArrowDown: ['down'];
-    ArrowLeft: ['left'];
-    Numpad1: ['down', 'left'];
-    Numpad2: ['down'];
-    Numpad3: ['down', 'right'];
-    Numpad4: ['left'];
-    Numpad6: ['right'];
-    Numpad7: ['up', 'left'];
-    Numpad8: ['up'];
-    Numpad9: ['up', 'right'];
-  };
+  static emulateKeypress(
+    up: boolean,
+    key: string,
+    {
+      altKey,
+      ctrlKey,
+      shiftKey,
+      repeat
+    }?: { altKey?: boolean; ctrlKey?: boolean; shiftKey?: boolean; repeat?: boolean }
+  ): void;
 
   /**
-   * Map keys used for canvas zooming
+   * Format a KeyboardEvent#code into a displayed string.
+   * @param code - The input code
+   * @returns The displayed string for this code
    */
-  static ZOOM_KEYS: {
-    PageUp: 'in';
-    PageDown: 'out';
-    NumpadAdd: 'in';
-    NumpadSubtract: 'out';
-  };
+  static getKeycodeDisplayString(code: string): string;
 
   /**
-   * Reset tracking for which keys are in the down and released states
+   * Get a standardized keyboard context for a given event.
+   * Every individual keypress is uniquely identified using the KeyboardEvent#code property.
+   * A list of possible key codes is documented here: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values
+   *
+   * @param event - The originating keypress event
+   * @param up    - A flag for whether the key is down or up
+   *                (default: `false`)
+   * @returns The standardized context of the event
    */
-  protected _reset(): void;
+  static getKeyboardEventContext(event: KeyboardEvent, up: boolean): KeyboardEventContext;
 
   /**
-   * Return whether the key code is currently in the DOWN state
-   * @param code - The key code to test
+   * Report whether a modifier in KeyboardManager.MODIFIER_KEYS is currently actively depressed.
+   * @param modifier - A modifier in MODIFIER_KEYS
+   * @returns Is this modifier key currently down (active)?
    */
-  isDown(code: string): boolean;
+  isModifierActive(modifier: string): boolean;
 
   /**
-   * A helper method to test whether, given an Event, the CTRL (or CMD) keys are pressed
-   * @param event - The originating event or canvas interaction
+   * Converts a Keyboard Context event into a string representation, such as "C" or "Control+C"
+   * @param context          - The standardized context of the event
+   * @param includeModifiers - If True, includes modifiers in the string representation
+   *                           (default: `true`)
+   * @internal
    */
-  isCtrl(event: Event | PIXI.InteractionEvent): boolean;
+  protected static _getContextDisplayString(context: KeyboardEventContext, includeModifiers?: boolean): string;
 
   /**
-   * Get a standardized keyboard code for a given event
-   * @param event - The originating keypress event
-   * @returns The standardized string code to use
+   * Given a standardized pressed key, find all matching registered Keybind Actions.
+   * @param context - A standardized keyboard event context
+   * @returns The matched Keybind Actions. May be empty.
    */
-  getKey(event: KeyboardEvent): string;
+  protected static _getMatchingActions(context: KeyboardEventContext): KeybindingAction[];
 
   /**
-   * The key codes which represent a possible movement key
+   * Test whether a keypress context matches the registration for a keybinding action
+   * @param action  - The keybinding action
+   * @param context - The keyboard event context
+   * @returns Does the context match the action requirements?
+   * @internal
    */
-  get moveKeys(): typeof KeyboardManager.MOVEMENT_KEYS;
+  protected static _testContext(action: KeybindingAction, context: KeyboardEventContext): boolean;
 
   /**
-   * The key codes which represent a digit key
+   * Given a registered Keybinding Action, executes the action with a given event and context
+   *
+   * @param keybind - The registered Keybinding action to execute
+   * @param context - The gathered context of the event
+   * @returns Returns true if the keybind was consumed
+   * @internal
    */
-  get digitKeys(): typeof KeyboardManager.DIGIT_KEYS;
+  protected static _executeKeybind(keybind: KeybindingAction, context: KeyboardEventContext): boolean;
 
   /**
-   * Return the key codes used for zooming the canvas
+   * Processes a keyboard event context, checking it against registered keybinding actions
+   * @param context - The keyboard event context
+   * @internal
    */
-  get zoomKeys(): typeof KeyboardManager.ZOOM_KEYS;
+  protected _processKeyboardContext(context: KeyboardEventContext): void;
 
   /**
-   * Test whether an input currently has focus
+   * Reset tracking for which keys are in the down and released states
+   * @internal
    */
-  get hasFocus(): boolean;
+  protected _reset(): void;
 
   /**
    * Handle a key press into the down position
    * @param event - The originating keyboard event
-   */
-  protected _onKeyDown(event: KeyboardEvent): void;
-
-  /**
-   * Handle a key release into the up position
-   * @param event - The originating keyboard event
-   */
-  protected _onKeyUp(event: KeyboardEvent): void;
-
-  /**
-   * Delegate tracked key codes by dispatching to their various handlers
-   * @param event - The keydown or keyup event
-   * @param key   - The key being depressed
    * @param up    - A flag for whether the key is down or up
+   * @internal
    */
-  protected _handleKeys(event: KeyboardEvent, key: string, up: boolean): void;
+  protected _handleKeyboardEvent(event: KeyboardEvent, up: boolean): void;
 
   /**
    * Input events do not fire with isComposing = false at the end of a composition event in Chrome
@@ -153,143 +183,65 @@ declare class KeyboardManager {
    */
   protected _onCompositionEnd(event: CompositionEvent): void;
 
-  /**
-   * Master mouse-wheel event keyboard handler
-   */
-  protected _onWheel(event: WheelEvent): void;
+  /** @deprecated since v9, will be removed in v10 */
+  static get MOUSE_WHEEL_RATE_LIMIT(): number;
 
   /**
-   * Handle TAB keypress events
-   * @param event     - The originating keyboard event
-   * @param up        - Is the key being released?
-   * @param modifiers - The identified modifiers attached to this keypress
-   */
-  protected _onTab(event: KeyboardEvent, up: boolean, modifiers: KeyboardManager.MetaModifiers): void;
-
-  /**
-   * Handle ESC keypress events
-   * @param event     - The originating keyboard event
-   * @param up        - Is the key being released?
-   * @param modifiers - The identified modifiers attached to this keypress
-   */
-  protected _onEscape(
-    event: KeyboardEvent,
-    up: boolean,
-    modifiers: KeyboardManager.MetaModifiers
-  ): void | Promise<void>;
-
-  /**
-   * Handle SPACE keypress events
-   * @param event     - The originating keyboard event
-   * @param up        - Is the key being released?
-   * @param modifiers - The identified modifiers attached to this keypress
-   */
-  protected _onSpace(
-    event: KeyboardEvent,
-    up: boolean,
-    modifiers: KeyboardManager.MetaModifiers
-  ): void | ReturnType<Set<string>['add']>;
-
-  /**
-   * Handle ALT keypress events
-   * @param event     - The originating keyboard event
-   * @param up        - Is the key being released?
-   * @param modifiers - The identified modifiers attached to this keypress
-   */
-  protected _onAlt(event: KeyboardEvent, up: boolean, modifiers: KeyboardManager.MetaModifiers): void;
-
-  /**
-   * Handle movement keypress events
-   * @param event     - The originating keyboard event
-   * @param up        - Is the key being released?
-   * @param modifiers - The identified modifiers attached to this keypress
+   * @deprecated since V9, will be removed in V10
+   * Return whether the key code is currently in the DOWN state
+   * @param code - The key code to test
    */
-  protected _onMovement(event: KeyboardEvent, up: boolean, modifiers: KeyboardManager.MetaModifiers): void;
+  isDown(code: string): boolean;
 
-  /**
-   * Handle keyboard movement once a small delay has elapsed to allow for multiple simultaneous key-presses.
-   */
-  protected _handleMovement(event: KeyboardEvent, layer: PlaceablesLayer<any>): void;
+  /** @deprecated since v9, will be removed in v10 */
+  static isControl(event: KeyboardEvent | PIXI.InteractionEvent): boolean;
 
   /**
-   * Handle panning the canvas using CTRL + directional keys
+   * @deprecated since v9, will be removed in v10
+   * @see KeyboardManager.isControl
    */
-  protected _handleCanvasPan(): ReturnType<Canvas['animatePan']>;
-
-  /**
-   * Handle number key presses
-   * @param event     - The original digit key press
-   *                    (unused)
-   * @param up        - Is it a keyup?
-   * @param modifiers - What modifiers affect the keypress?
-   */
-  protected _onDigit(event: KeyboardEvent, up: boolean, modifiers: KeyboardManager.MetaModifiers): void;
+  isCtrl(event: Event | PIXI.InteractionEvent): boolean;
 
-  /**
-   * Handle "A" keypress events (CTRL only) to select all objects
-   * @param event     - The originating keyboard event
-   *                    (unused)
-   * @param up        - Is the key being released?
-   * @param modifiers - The identified modifiers attached to this keypress
-   */
-  protected _onKeyA(event: KeyboardEvent, up: boolean, modifiers: KeyboardManager.MetaModifiers): void;
+  /** @deprecated since v9, will be removed in v10 */
+  get _downKeys(): Set<string>;
 
-  /**
-   * Handle "C" keypress events to copy data to clipboard
-   * @param event     - The originating keyboard event
-   * @param up        - Is the key being released?
-   * @param modifiers - The identified modifiers attached to this keypress
-   */
-  protected _onKeyC(event: KeyboardEvent, up: boolean, modifiers: KeyboardManager.MetaModifiers): void;
+  /** @deprecated since v9, will be removed in v10 */
+  static DIGIT_KEYS: ['1', '2', '3', '4', '5', '6', '7', '8', '9', '0'];
 
-  /**
-   * Handle "V" keypress events to paste data from clipboard
-   * @param event     - The originating keyboard event
-   * @param up        - Is the key being released?
-   * @param modifiers - The identified modifiers attached to this keypress
-   */
-  protected _onKeyV(event: KeyboardEvent, up: boolean, modifiers: KeyboardManager.MetaModifiers): void;
+  /** @deprecated since v9, will be removed in v10 */
+  static MOVEMENT_KEYS: {
+    W: ['up'];
+    A: ['left'];
+    S: ['down'];
+    D: ['right'];
+    ARROWUP: ['up'];
+    ARROWRIGHT: ['right'];
+    ARROWDOWN: ['down'];
+    ARROWLEFT: ['left'];
+    NUMPAD1: ['down', 'left'];
+    NUMPAD2: ['down'];
+    NUMPAD3: ['down', 'right'];
+    NUMPAD4: ['left'];
+    NUMPAD6: ['right'];
+    NUMPAD7: ['up', 'left'];
+    NUMPAD8: ['up'];
+    NUMPAD9: ['up', 'right'];
+  };
 
-  /**
-   * Handle Z Keypress Events to generally undo previous actions
-   * @param event     - The originating keyboard event
-   * @param up        - Is the key being released?
-   * @param modifiers - The identified modifiers attached to this keypress
-   */
-  protected _onKeyZ(event: KeyboardEvent, up: boolean, modifiers: KeyboardManager.MetaModifiers): void;
+  /** @deprecated since v9, will be removed in v10 */
+  static ZOOM_KEYS: {
+    PAGEUP: 'in';
+    PAGEDOWN: 'out';
+    NUMPADADD: 'in';
+    NUMPADSUBTRACT: 'out';
+  };
 
-  /**
-   * Handle presses to keyboard zoom keys
-   * @param event     - The originating keyboard event
-   * @param up        - Is the key being released?
-   * @param modifiers - The identified modifiers attached to this keypress
-   */
-  protected _onKeyZoom(
-    event: KeyboardEvent,
-    up: boolean,
-    modifiers: KeyboardManager.MetaModifiers
-  ): void | ReturnType<Canvas['animatePan']>;
+  /** @deprecated since v9, will be removed in v10 */
+  static standardizeKey(key: string): string;
 
-  /**
-   * Handle DELETE Keypress Events
-   * @param event     - The originating keyboard event
-   * @param up        - Is the key being released?
-   * @param modifiers - The identified modifiers attached to this keypress
-   */
-  protected _onDelete(
-    event: KeyboardEvent,
-    up: boolean,
-    modifiers: KeyboardManager.MetaModifiers
-  ): void | Promise<foundry.abstract.Document<any, any>[] | undefined>;
-}
+  /** @deprecated since v9, will be removed in v10 */
+  get digitKeys(): typeof KeyboardManager.DIGIT_KEYS;
 
-declare namespace KeyboardManager {
-  interface MetaModifiers {
-    key: string;
-    isShift: boolean;
-    isCtrl: boolean;
-    isAlt: boolean;
-    hasFocus: boolean;
-    hasModifier: boolean;
-  }
+  /** @deprecated since v9, will be removed in v10 */
+  get zoomKeys(): KeybindingActionBinding[];
 }