node-native-win-utils/dist/index.d.mts

Native addon for Node.js providing utility operations on Windows systems

import EventEmitter from 'events';
import { KeyCodeHelper } from "./keyCodes.mjs";
/**
 * Represents the data of a window.
 */
export type WindowData = {
    width: number;
    height: number;
    x: number;
    y: number;
};
/**
 * Represents the data of an image.
 */
export type ImageData = {
    width: number;
    height: number;
    data: Uint8Array;
};
/**
 * Represents the result of a template matching operation.
 */
export type MatchData = {
    minValue: number;
    maxValue: number;
    minLocation: {
        x: number;
        y: number;
    };
    maxLocation: {
        x: number;
        y: number;
    };
};
export type GetWindowData = (windowName: string) => WindowData;
export type CaptureWindow = (windowName: string) => Buffer;
/**
 * The handler to listen to key-events.
 * @param callback - The callback function to handle key-down events.
 */
export type SetKeyCallback = (callback: (keyCode: number) => void) => void;
/**
 * The handler to stop thread listening to key-events.
 * @param callback - The callback function to handle key-down events.
 */
export type UnsetKeyCallback = () => void;
/**
 * Function type for moving the mouse.
 */
export type MouseMove = (posX: number, posY: number) => boolean;
/**
 * Function type for simulating a mouse click.
 */
export type MouseClick = (button?: "left" | "middle" | "right") => boolean;
/**
 * Function type for simulating typing.
 */
export type TypeString = (stringToType: string, delay?: number) => boolean;
/**
 * Function type for simulating key press and release.
 */
export type PressKey = (keyCode: number) => boolean;
/**
 * Function type for simulating a mouse drag operation.
 */
export type MouseDrag = (starX: number, startY: number, endX: Number, endY: number, speed?: number) => boolean;
/**
 * Represents a point in a two-dimensional space.
 */
export type Point = [x: number, y: number];
export type Color = [r: number, g: number, b: number];
/**
 * Represents a region of interest in an image.
 */
export type ROI = [x: number, y: number, width: number, height: number];
export type Imread = (path: string) => ImageData;
export type Imwrite = (image: ImageData) => Buffer;
export type MatchTemplate = (image: ImageData, template: ImageData, method?: number | null, mask?: ImageData) => MatchData;
export type Blur = (image: ImageData, sizeX: number, sizeY: number) => ImageData;
export type BgrToGray = (image: ImageData) => ImageData;
export type EqualizeHist = (image: ImageData) => ImageData;
export type ColorBound = [number, number, number];
export type DarkenColor = (image: ImageData, lowerBound: ColorBound, upperBound: ColorBound, darkenFactor: number) => ImageData;
export type DrawRectangle = (image: ImageData, start: Point, end: Point, rgb: Color, thickness: number) => ImageData;
export type GetRegion = (image: ImageData, region: ROI) => ImageData;
export type TextRecognition = (trainedDataPath: string, dataLang: string, imagePath: string) => string;
export type CaptureScreenAsync = () => Promise<Buffer>;
declare const getWindowData: GetWindowData, captureWindowN: CaptureWindow, captureScreenAsync: CaptureScreenAsync, mouseMove: MouseMove, mouseClick: MouseClick, mouseDrag: MouseDrag, typeString: TypeString, textRecognition: TextRecognition;
declare const rawPressKey: PressKey;
/**
 * Captures a window and saves it to a file.
 * @param windowName - The name of the window to capture.
 * @param path - The file path to save the captured image.
 * @returns True if the capture and save operation is successful, otherwise false.
 */
declare function captureWindow(windowName: string, path: string): boolean;
/**
 * Captures a screen and saves it to a file.
 * @param path - The file path to save the captured image.
 * @returns True if the capture and save operation is successful, otherwise false.
 */
declare function captureScreenToFile(path: string): Promise<boolean>;
/**
 * Interface representing a private keyboard listener that extends EventEmitter.
 * It declares event handlers for native keyboard events, which are forwarded from
 * the C++ bindings using thread-safe callbacks.
 */
interface KeyboardListenerPrivate extends EventEmitter {
    /**
     * Registers an event handler for the 'keyDown' event.
     * This event is fired when a key is pressed down. The C++ native binding calls
     * this callback using a thread-safe mechanism (via Napi::ThreadSafeFunction).
     * @param event - The event name ('keyDown').
     * @param callback - Function invoked with an object containing the keyCode and keyName.
     * @returns The current instance for method chaining.
     */
    on(event: "keyDown", callback: (data: {
        keyCode: number;
        keyName: string;
    }) => void): this;
    /**
     * Registers an event handler for the 'keyUp' event.
     * This event is fired when a key is released. The underlying C++ code safely
     * invokes this callback from a background thread using a thread-safe function.
     * @param event - The event name ('keyUp').
     * @param callback - Function invoked with an object containing the keyCode and keyName.
     * @returns The current instance for method chaining.
     */
    on(event: "keyUp", callback: (data: {
        keyCode: number;
        keyName: string;
    }) => void): this;
}
/**
 * Class that implements a private keyboard listener.
 * This class leverages native C++ bindings to hook into system keyboard events.
 * The C++ layer uses global ThreadSafeFunction objects to safely dispatch events
 * (using a dedicated monitoring thread, mutexes, and atomic flags) to JavaScript.
 * @extends EventEmitter
 */
declare class KeyboardListenerPrivate extends EventEmitter {
    /**
     * Constructs the keyboard listener and sets up native callbacks.
     * The callbacks (set via setKeyDownCallback and setKeyUpCallback) are defined in the
     * C++ binding layer. They are responsible for invoking these JavaScript callbacks
     * in a thread-safe manner once a key event is detected.
     */
    constructor();
}
/**
 * A singleton manager for the KeyboardListenerPrivate instance.
 * This class ensures that only one native keyboard listener is active at any time.
 * When the listener is destroyed, it calls unsetKeyDownCallback and unsetKeyUpCallback
 * to clean up native resources, mirroring the cleanup logic in the C++ bindings.
 */
declare class KeyboardListener {
    /**
     * Holds the singleton instance of KeyboardListenerPrivate.
     */
    private static listenerInstance;
    /**
     * Returns the singleton instance of KeyboardListenerPrivate. If not already created,
     * it instantiates a new instance and sets up the native callbacks.
     * @returns The active KeyboardListenerPrivate instance.
     */
    static listener(): KeyboardListenerPrivate;
    /**
     * Destroys the current KeyboardListenerPrivate instance and cleans up native callbacks.
     * This method calls unsetKeyDownCallback and unsetKeyUpCallback to release any
     * native resources (such as the global ThreadSafeFunctions) and stops the monitoring thread.
     */
    static destroy(): void;
}
export declare enum TemplateMatchModes {
    TM_SQDIFF = 0,/*!< \f[R(x,y)= \sum _{x',y'} (T(x',y')-I(x+x',y+y'))^2\f]
                               with mask:
                               \f[R(x,y)= \sum _{x',y'} \left( (T(x',y')-I(x+x',y+y')) \cdot
                                  M(x',y') \right)^2\f] */
    TM_SQDIFF_NORMED = 1,/*!< \f[R(x,y)= \frac{\sum_{x',y'} (T(x',y')-I(x+x',y+y'))^2}{\sqrt{\sum_{
                                  x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}\f]
                               with mask:
                               \f[R(x,y)= \frac{\sum _{x',y'} \left( (T(x',y')-I(x+x',y+y')) \cdot
                                  M(x',y') \right)^2}{\sqrt{\sum_{x',y'} \left( T(x',y') \cdot
                                  M(x',y') \right)^2 \cdot \sum_{x',y'} \left( I(x+x',y+y') \cdot
                                  M(x',y') \right)^2}}\f] */
    TM_CCORR = 2,/*!< \f[R(x,y)= \sum _{x',y'} (T(x',y') \cdot I(x+x',y+y'))\f]
                               with mask:
                               \f[R(x,y)= \sum _{x',y'} (T(x',y') \cdot I(x+x',y+y') \cdot M(x',y')
                                  ^2)\f] */
    TM_CCORR_NORMED = 3,/*!< \f[R(x,y)= \frac{\sum_{x',y'} (T(x',y') \cdot I(x+x',y+y'))}{\sqrt{
                                  \sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}\f]
                               with mask:
                               \f[R(x,y)= \frac{\sum_{x',y'} (T(x',y') \cdot I(x+x',y+y') \cdot
                                  M(x',y')^2)}{\sqrt{\sum_{x',y'} \left( T(x',y') \cdot M(x',y')
                                  \right)^2 \cdot \sum_{x',y'} \left( I(x+x',y+y') \cdot M(x',y')
                                  \right)^2}}\f] */
    TM_CCOEFF = 4,/*!< \f[R(x,y)= \sum _{x',y'} (T'(x',y') \cdot I'(x+x',y+y'))\f]
                               where
                               \f[\begin{array}{l} T'(x',y')=T(x',y') - 1/(w \cdot h) \cdot \sum _{
                                  x'',y''} T(x'',y'') \\ I'(x+x',y+y')=I(x+x',y+y') - 1/(w \cdot h)
                                  \cdot \sum _{x'',y''} I(x+x'',y+y'') \end{array}\f]
                               with mask:
                               \f[\begin{array}{l} T'(x',y')=M(x',y') \cdot \left( T(x',y') -
                                  \frac{1}{\sum _{x'',y''} M(x'',y'')} \cdot \sum _{x'',y''}
                                  (T(x'',y'') \cdot M(x'',y'')) \right) \\ I'(x+x',y+y')=M(x',y')
                                  \cdot \left( I(x+x',y+y') - \frac{1}{\sum _{x'',y''} M(x'',y'')}
                                  \cdot \sum _{x'',y''} (I(x+x'',y+y'') \cdot M(x'',y'')) \right)
                                  \end{array} \f] */
    TM_CCOEFF_NORMED = 5 /*!< \f[R(x,y)= \frac{ \sum_{x',y'} (T'(x',y') \cdot I'(x+x',y+y')) }{
                                  \sqrt{\sum_{x',y'}T'(x',y')^2 \cdot \sum_{x',y'} I'(x+x',y+y')^2}
                                  }\f] */
}
/**
 * Represents the OpenCV class that provides image processing functionality.
 */
declare class OpenCV {
    imageData: ImageData;
    /**
     * Represents the OpenCV class that provides image processing functionality.
     */
    constructor(image: string | ImageData);
    /**
     * The width of the image.
     */
    get width(): number;
    /**
     * The height of the image.
     */
    get height(): number;
    /**
     * Matches a template image within the current image.
     * @param template - The template image data to search for.
     * @param method - The template matching method (optional).
     * @param mask - The optional mask image data to apply the operation (optional).
     * @returns The result of the template matching operation.
     */
    matchTemplate(template: ImageData, method?: number | null, mask?: ImageData): MatchData;
    /**
     * Applies a blur filter to the image.
     * @param sizeX - The horizontal size of the blur filter.
     * @param sizeY - The vertical size of the blur filter.
     * @returns A new OpenCV instance with the blurred image data.
     */
    blur(sizeX: number, sizeY: number): OpenCV;
    /**
     * Converts the image from BGR to grayscale.
     * @returns A new OpenCV instance with the grayscale image data.
     */
    bgrToGray(): OpenCV;
    /**
      * Equalize the Histogram by using the OpenCV function cv::equalizeHist.
      * @returns A new OpenCV instance with the equalized image data.
      */
    equalizeHist(): OpenCV;
    rgbToHsv(rgb: ColorBound): number[];
    darkenColor(lowerBound: ColorBound, upperBound: ColorBound, darkenFactor: number): OpenCV;
    /**
     * Draws a rectangle on the image.
     * @param start - The starting point of the rectangle.
     * @param end - The ending point of the rectangle.
     * @param rgb - The color (RGB) of the rectangle.
     * @param thickness - The thickness of the rectangle's border.
     * @returns A new OpenCV instance with the image containing the drawn rectangle.
     */
    drawRectangle(start: Point, end: Point, rgb: Color, thickness: number): OpenCV;
    /**
     * Extracts a region of interest (ROI) from the image.
     * @param region - The region of interest defined as [x, y, width, height].
     * @returns A new OpenCV instance with the extracted region of interest.
     */
    getRegion(region: ROI): OpenCV;
    /**
     * Writes the image data to a file.
     * @param path - The file path to save the image.
     */
    imwrite(path: string): void;
}
declare function keyPress(keyCode: number, repeat?: number): Promise<boolean>;
export { getWindowData, captureWindow, captureWindowN, mouseMove, mouseClick, mouseDrag, typeString, keyPress, rawPressKey, KeyCodeHelper, textRecognition, captureScreenToFile, captureScreenAsync, KeyboardListener, OpenCV };