Interface Input

The Input module provides methods to capture mouse and keybord events in the player window. Although it can be used to add keyboard shortcuts, it is recommended to use the Menu module to do so. This module, by providing both the keyDown/mouseDown and keyUp/mouseUp listeners, provides more user interaction possibilities; for example, you can implement a "hold to seek" feature.

Each listener is associated with a priority. Listeners with higher priority are called first. If the priority >= PRIORITY_HIGH, the handler will be called before the default handlers, e.g. mpv key bindings. To be more specific, the listeners are called in the following order:

  • Listeners with priority >= PRIORITY_HIGH
  • Default handlers, e.g. mpv key bindings
  • Listeners with priority < PRIORITY_HIGH

You should avoid using PRIORITY_HIGH unless necessary. The default priority is always PRIORITY_LOW.

The event callback should return a boolean value indicating whether the event is handled. If the event is handled, it will not be passed down to other listeners (which might include the default handlers in IINA, therefore overriding the default behavior).

In IINA, an input event is sent to the menu bar first, then to the frontmost window. Therefore, under current implementation, if a key input is captured by one of the menu items, it will not be passed down to this module. We may change this behavior in the future, but for now, you should not expect much from the priority system and always use PRIORIY_LOW for your listeners.

For mouse events, due to the complexity of the underlying implementation, currently it is not possible to detect drag events. For more advanced mouse event handling, the overlay module might be helpful.

Example

// priority is HIGH for this listener, so it will be called before default handlers
input.onKeyDown("A", (data) => {
  console.log(data);
  // doesn't return anything, so the event will be passed down to other handlers
}, input.PRIORITY_HIGH)

// priority is LOW for this listener, so it will be called after default handlers
input.onKeyUp("Alt+a", ({x, y}) => {
  console.log(`Alt+a up at ${x},${y}`);
  return true;  // stop the event propagation
})

Hold the mouse button to speed up the playback:

input.onMouseDown(input.MOUSE, () => { core.setSpeed(2) });
input.onMouseUp(input.MOUSE, () => { core.setSpeed(1); });
// Reset speed when started dragging.
// See the docs for the `onMouseDrag` method for more details.
input.onMouseDrag(input.MOUSE, () => { core.setSpeed(1) });

Available In Entry

Main entry only

Hierarchy

  • Input

Properties

MOUSE RIGHT_MOUSE OTHER_MOUSE PRIORITY_LOW PRIORITY_HIGH

Methods

normalizeKeyCode getAllKeyBindings onKeyDown onKeyUp onMouseUp onMouseDown onMouseDrag

Properties

MOUSE

MOUSE: string

RIGHT_MOUSE

RIGHT_MOUSE: string

OTHER_MOUSE

OTHER_MOUSE: string

PRIORITY_LOW

PRIORITY_LOW: number

PRIORITY_HIGH

PRIORITY_HIGH: number

Methods

normalizeKeyCode

  • Convert a mpv key code to a standarized form used in IINA. This method is useful when checking if there is already a registered key binding.

    Example

    input.normalizeKeyCode("Shift+a") // => "A"

    Parameters

    • code: string

      the mpv key code.

    Returns string

getAllKeyBindings

  • Get all registered mpv (and iina) key bindings.

    Returns

    A dictionary of key bindings, where the key is the key code and the value is an object with the following properties:

    • action: the corresponding mpv or iina command
    • key: the key code
    • isIINACommand: whether the command is an iina command

    Example

    // check if a key binding is already registered
    const kc = input.normalizeKeyCode("Shift+Alt+X")
    if (input.getAllKeyBindings()[kc]) {
      // alert the user: the key binding is already registered
    }

    Returns Record<string, {
        key: string;
        action: string;
        isIINACommand: string;
    }>

onKeyDown

  • Listen to a key down event.

    Parameters

    • button: string

      The key (or key combination) to listen to. It should be a valid mpv key code.

    • callback: ((data: {
          x: number;
          y: number;
          isRepeat: boolean;
      }) => boolean)

      To remove the listener, pass null to this parameter.

        • (data: {
              x: number;
              y: number;
              isRepeat: boolean;
          }): boolean

        • Returns

          Whether to stop the event propagation. If true, the event will not be passed down to other handlers.

          Parameters

          • data: {
                x: number;
                y: number;
                isRepeat: boolean;
            }

            The data associated with the event.

            • x: number

              The x coordinate of the current mouse cursor, relative to the player window.

            • y: number

              The y coordinate of the current mouse cursor, relative to the player window.

            • isRepeat: boolean

              Whether the event is a repeat event (by holding down the key).

          Returns boolean

    • Optional priority: number

      The priority of the handler. Higher priority handlers are called first.

    Returns string

onKeyUp

  • Listen to a key up event.

    Parameters

    • button: string

      The key (or key combination) to listen to. It should be a valid mpv key code.

    • callback: ((data: {
          x: number;
          y: number;
          isRepeat: boolean;
      }) => boolean)

      To remove the listener, pass null to this parameter.

        • (data: {
              x: number;
              y: number;
              isRepeat: boolean;
          }): boolean

        • Returns

          Whether to stop the event propagation. If true, the event will not be passed down to other handlers.

          Parameters

          • data: {
                x: number;
                y: number;
                isRepeat: boolean;
            }

            The data associated with the event.

            • x: number

              The x coordinate of the current mouse cursor, relative to the player window.

            • y: number

              The y coordinate of the current mouse cursor, relative to the player window.

            • isRepeat: boolean

              Whether the event is a repeat event (by holding down the key).

          Returns boolean

    • Optional priority: number

      The priority of the handler. Higher priority handlers are called first.

    Returns string

onMouseUp

  • Listen to a mouse up event.

    Note that if you return true in the callback, both the default single-click and double-click actions in IINA will stop working. You are responsible for handling them on your own.

    Parameters

    • button: string

      The mouse button. Should be one of input.MOUSE, input.RIGHT_MOUSE, and input.OTHER_MOUSE.

    • callback: ((data: {
          x: number;
          y: number;
      }) => boolean)

      To remove the listener, pass null to this parameter.

        • (data: {
              x: number;
              y: number;
          }): boolean

        • Returns

          Whether to stop the event propagation. If true, the event will not be passed down to other handlers.

          Parameters

          • data: {
                x: number;
                y: number;
            }

            The data associated with the event.

            • x: number

              The x coordinate of the current mouse cursor, relative to the player window.

            • y: number

              The y coordinate of the current mouse cursor, relative to the player window.

          Returns boolean

    • Optional priority: number

      The priority of the handler. Higher priority handlers are called first.

    Returns string

onMouseDown

  • Listen to a mouse down event.

    Parameters

    • button: string

      The mouse button. Should be one of input.MOUSE, input.RIGHT_MOUSE, and input.OTHER_MOUSE.

    • callback: ((data: {
          x: number;
          y: number;
      }) => boolean)

      To remove the listener, pass null to this parameter.

        • (data: {
              x: number;
              y: number;
          }): boolean

        • Returns

          Whether to stop the event propagation. If true, the event will not be passed down to other handlers.

          Parameters

          • data: {
                x: number;
                y: number;
            }

            The data associated with the event.

            • x: number

              The x coordinate of the current mouse cursor, relative to the player window.

            • y: number

              The y coordinate of the current mouse cursor, relative to the player window.

          Returns boolean

    • Optional priority: number

      The priority of the handler. Higher priority handlers are called first.

    Returns string

onMouseDrag

  • Listen to a mouse drag event. Works for the left mouse button only. The sole purpose of this method is to allow the plugin to know when a drag event is initiated while the mouse button is hold down. If the user started dragging, the plugin should not perform any action to interfere with the default dragging behavior. In short, if you need to do something while the mouse button is hold down, listen to both mouseDown and mouseDrag events, and cancel your action when either of them fires.

    Parameters

    • button: string

      The mouse button. Should always be input.MOUSE.

    • callback: ((data: {
          x: number;
          y: number;
      }) => boolean)

      To remove the listener, pass null to this parameter.

        • (data: {
              x: number;
              y: number;
          }): boolean

        • Returns

          Whether to stop the event propagation, but it has no effect. Should always return false.

          Parameters

          • data: {
                x: number;
                y: number;
            }
            • x: number
            • y: number

          Returns boolean

    • Optional priority: number

      The priority of the handler, however it has no effect. There is no way to override the default dragging behavior in IINA. Should always be PRIORITY_LOW.

    Returns string

Settings

Member Visibility

Theme

Generated using TypeDoc