evidently-input/dist/MouseInput.d.ts

TypeScript powered for easily handling input in your games.

export interface MouseInputRelativeScaleProps {
    scaleX: number;
    scaleY: number;
    offsetX: number;
    offsetY: number;
}
export interface InputRelativeContainer {
    readonly offsetLeft: number;
    readonly offsetTop: number;
}
export declare enum MouseButtons {
    Left = 0,
    Middle = 1,
    Right = 2
}
/**
 * Handles the mouse events and provdes an API for interacting with it easily. The simplest way to use it is:
 *
 * 1. Create a new instance of `MouseInput`.
 * 2. Call `registerListeners()` passing the `document`.
 * 3. Set `inputContainer` to the canvas element created by PIXI.
 * 4. Call `update` **at the end** of every update frame of your game.
 * 5. Use the functions of this library in your code.
 *
 * ### Different mouse positions
 *
 *  * `screen` is the position of the mouse in the whole screen.
 *  * `page` is the position of the mouse inside the loaded webpage.
 *  * `local` is the position of the mouse relative to the `inputContainer` if defined, or to the element passed to `registerListeners`.
 *  * `scaled` is the position of the mouse inside the game, which is `local` modified by `scaleProperties`. It is mostly useful in games
 *    that scale up when their workspace is enlarged, as opposed to games that just reorganize their content and allow seeing more
 *    space inside.
 *
 * In order to get the proper values for `local` it is recommended to set `inputContainer` to the canvas element used to render the game.
 *
 * ### Scaled mouse position
 *
 * In order to get the proper values for `scaled` you need to keep the `scaleProperties` in sync with the modifications you do to the rendering of the game.
 * For example, a typical game imitating 8-bit aesthetics would likely have its own internal resolution and then would scale that up, maybe pixel-perfect
 * or maybe not. For example: a game in resolution `320x240` scaled up proportionally to resolution `1920x1080`:
 *
 *  * It would scale `4.5` times, to `1440x1080.`
 *  * It would be horizontally centered, so offset in `X` by `240px` ( `(1920 - 1440) / 2` )
 *  * So the `scaleProperties` would be `{scaleX: 4.5, scaleY: 4.5, offsetX: 240, offsetY: 0}
 *
 * With these values scaledX/Y will return the proper position of the mouse in the stage.
 *
 * ### How does it work:
 *
 * See [[KeyboardInput]] for details.
 *
 * ### Understanding mouse button states
 *
 * Down, pressed and released for the mouse buttons work exactly the same as the keys in [[KeyboardInput]], please refer to its documentation.
 */
export declare class MouseInput {
    private _localX;
    private _localY;
    private _pageX;
    private _pageY;
    private _screenX;
    private _screenY;
    private _mouseButtonsDown;
    private _mouseButtonsPressed;
    private _mouseButtonsReleased;
    /**
     * When provided, `local` mouse position will be calculated treating this as a reference. Most of the time it'll
     * be the canvas element created by PIXI to render the game into.
     * If the game does not begin in the top-left corner of the HTML page it has to be set for `local` mouse
     * position to be calculated correctly.
     */
    inputContainer?: InputRelativeContainer;
    /**
     * When viewport of the game changes there are two common solutions:
     *  1. Change the workspace of the game (ie. player sees more/less of the play area)
     *  2. Scale the game up (ie. everything get bigger/smaller)
     *
     * `scaleProperties` is used in the second situation. When your game is scaled and possibly offset
     * (when you prefer keeping the display ratio) inside its container `local` mouse positions will not
     * take those changes into consideration while `scaled` mouse positions will, provided
     * `MouseInputRelativeScaleProps` is set correctly.
     */
    readonly scaleProperties: MouseInputRelativeScaleProps;
    get pageX(): number;
    get pageY(): number;
    get localX(): number;
    get localY(): number;
    get screenX(): number;
    get screenY(): number;
    get scaledX(): number;
    get scaledY(): number;
    get isAnyMouseDown(): boolean;
    get isAnyMousePressed(): boolean;
    get isAnyMouseReleased(): boolean;
    isMouseDown: (button: number) => boolean;
    isMousePressed: (button: number) => boolean;
    isMouseReleased: (button: number) => boolean;
    constructor();
    /**
     * Updates the internal state, should be called at the end of each frame.
     */
    update: () => void;
    /**
     * Resets the internal state of this class to what it is during creation - nothing pressed, released or held down, positions reset.
     * This won't affect `scaleProperties` and `inputContainer`.
     */
    flush: () => void;
    /**
     * Registers the `mousemove`, `mosedown` and `mouseup` listeners on the passed element so that the class
     * can handle the input.
     * This also registers an event that blocks right mouse button context menu from appearing.
     *
     * @param {GlobalEventHandlers} element To avoid issues with focus it's best to pass `document` here
     */
    registerListeners(element: GlobalEventHandlers): void;
    /**
     * Handles a mouse event updating the internal status. This will be called automatically if you register the listeners
     * via `registerListeners`. If you have listeners being registered somewhere else entirely and would like to keep it
     * that way, you can manually call this method passing the MouseEvent/PointerEvent.
     *
     * @param {MouseEvent | PointerEvent} event
     */
    handleEvent: (event: MouseEvent | PointerEvent) => void;
    handleContextMenuEvent: (event: Event) => boolean;
}