node-native-win-utils 1.4.0 → 2.1.1

package/README.md

@@ -67,9 +67,7 @@ To use the package, import the necessary functions, types, and classes:
 
 import {
 
-keyDownHandler,
-
-keyUpHandler,
+KeyboardListener
 
 getWindowData,
 
@@ -93,38 +91,30 @@ OpenCV,
 
   
 
-## Key Event Listeners
+## Keyboard Event Listener
 
   
 
-The package provides `keyDownHandler` and `keyUpHandler` functions, which allow you to register callbacks for key down and key up events, respectively. The callbacks receive the `keyCode` as a parameter:
+The package provides KeyboardListener singletone class, which allow you to register event listeners for key down and key up events, respectively. The event callbacks receive the `keyCode` as a parameter:
 
   
 
 ```javascript
 
-keyDownHandler((keyCode) => {
-
-console.log("Key down:", keyCode);
-
-});
-
-  
-
-// Key down: 8
-
-  
-
-keyUpHandler((keyCode) => {
-
-console.log("Key up:", keyCode);
-
-});
-
-  
-
-// Key up: 8
-
+const listener = KeyboardListener.listener()
+
+listener.on("keyDown", (data: {
+        keyCode: number;
+        keyName: string;
+      }) => {
+//your code
+})
+listener.on("keyUp", (data: {
+        keyCode: number;
+        keyName: string;
+      }) => {
+    //your code
+})
 ```
 
 ## Key Press
@@ -473,18 +463,16 @@ Writes the current image to a file specified by the `path`.
 
 | Function        | Parameters                                                                                   | Return Type |
 |-----------------|----------------------------------------------------------------------------------------------|-------------|
-| keyDownHandler  | `callback: (keyCode: number) => void`                                                         | `void`      |
-| keyUpHandler    | `callback: (keyCode: number) => void`                                                         | `void`      |
-| getWindowData   | `windowName: string`                                                                         | `WindowData`|
+| getWindowData   | `windowName: string`                                                                          | `WindowData`|
 | captureWindow   | `windowName: string, outputPath: string`                                                      | `void`      |
 | mouseMove       | `posX: number, posY: number`                                                                  | `boolean`   |
 | mouseClick      | `button?: "left" \| "middle" \| "right"`                                                      | `boolean`   |
-| mouseDrag       | `startX: number, startY: number, endX: number, endY: number, speed?: number`                | `boolean`   |
+| mouseDrag       | `startX: number, startY: number, endX: number, endY: number, speed?: number`                  | `boolean`   |
 | typeString      | `stringToType: string, delay?: number`                                                        | `boolean`   |
-| captureWindowN  | `windowName: string`                                                                         | `Buffer`    |
-| keyPress        | `keyCode: number, repeat?: number`                                                           | `boolean`   |
-
-
+| captureWindowN  | `windowName: string`                                                                          | `Buffer`    |
+| keyPress        | `keyCode: number, repeat?: number`                                                            | `boolean`   |
+| textRecognition | `trainedDataPath: string, dataLang: string, imagePath: string`                                | `string`    |
+| captureScreenToFile | `path: string`                                                                            | `boolean`   |
   
 
 ## Examples
@@ -493,7 +481,10 @@ Writes the current image to a file specified by the `path`.
 
 Here are some examples of using the package:
 
-  
+```javascript
+console.log(textRecognition(path.join(__dirname, 'traineddata'), 'eng', path.join(__dirname, 'images', '1.jpg'))) // ---> <recognized text>
+
+```
 
 ```javascript
 
@@ -577,10 +568,6 @@ Please note that the above example demonstrates the usage of different methods a
 
 import {
 
-keyDownHandler,
-
-keyUpHandler,
-
 getWindowData,
 
 captureWindow,
@@ -599,34 +586,6 @@ KeyListener,
 
   
 
-// Register key event handlers
-
-  
-
-keyDownHandler((keyCode) => {
-
-console.log("Key down:", keyCode);
-
-});
-
-  
-
-// Key down: 123
-
-  
-
-keyUpHandler((keyCode) => {
-
-console.log("Key up:", keyCode);
-
-});
-
-  
-
-// Key up: 123
-
-  
-
 // Retrieve window data
 
   
@@ -699,11 +658,11 @@ typeString("Hello, world!", 100); // Type with a delay of 100ms between characte
 
   
 
-// Use KeyListener class
+// Use KeyboardListener class
 
   
 
-const  listener  =  new  KeyListener();
+const  listener  =  KeyboardListener.listener();
 
   
 
@@ -734,18 +693,6 @@ console.log("Key up:", data.keyCode, data.keyName);
 
 ```
 
-# TODO
-
-  
-
-- Write proper tests
-
-- Add more useful functions
-
-- Fix issue with Windows scale for font,text,apps
-
-  
-
 [OpenCV License](https://github.com/opencv/opencv/blob/master/LICENSE)
 [MIT License](https://github.com/T-Rumibul/node-native-win-utils/blob/main/LICENSE)
   

package/binding.gyp

@@ -17,6 +17,8 @@
             "libraries": [
                 "dwmapi.lib",
                 "windowsapp.lib",
+                "-lgdi32", 
+                "-lgdiplus",
                 "<!(node -p \"require('path').resolve('libs/libjpeg-turbo.lib')\")",
                 "<!(node -p \"require('path').resolve('libs/libpng.lib')\")",
                 "<!(node -p \"require('path').resolve('libs/zlib.lib')\")",

package/dist/dirnameLocal.cjs

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__dirnameLocal = void 0;
+exports.__dirnameLocal = __dirname;

package/dist/dirnameLocal.d.cts

@@ -0,0 +1 @@
+export declare const __dirnameLocal: string;

package/dist/dirnameLocal.d.mts

@@ -0,0 +1 @@
+export declare const __dirnameLocal: string;

package/dist/dirnameLocal.mjs

@@ -0,0 +1,2 @@
+import * as url from 'url';
+export const __dirnameLocal = url.fileURLToPath(new URL('.', import.meta.url));

package/dist/{index.js → index.cjs}

@@ -3,20 +3,24 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.textRecognition = exports.KeyCodeHelper = exports.rawPressKey = exports.typeString = exports.mouseDrag = exports.mouseClick = exports.mouseMove = exports.captureWindowN = exports.getWindowData = exports.keyUpHandler = exports.keyDownHandler = exports.OpenCV = exports.KeyListener = void 0;
+exports.OpenCV = exports.KeyboardListener = exports.captureScreenAsync = exports.textRecognition = exports.KeyCodeHelper = exports.rawPressKey = exports.typeString = exports.mouseDrag = exports.mouseClick = exports.mouseMove = exports.captureWindowN = exports.getWindowData = void 0;
 exports.captureWindow = captureWindow;
 exports.keyPress = keyPress;
-const EventEmitter = require("events");
+exports.captureScreenToFile = captureScreenToFile;
+//@ts-nocheck 
+const events_1 = __importDefault(require("events"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
-const bindings = require("node-gyp-build")(path_1.default.resolve(__dirname, ".."));
-const keyCodes_1 = require("./keyCodes");
-Object.defineProperty(exports, "KeyCodeHelper", { enumerable: true, get: function () { return keyCodes_1.KeyCodeHelper; } });
-const { keyDownHandler, keyUpHandler, getWindowData, captureWindowN, mouseMove, mouseClick, mouseDrag, typeString, pressKey, imread, imwrite, matchTemplate, blur, bgrToGray, drawRectangle, getRegion, textRecognition } = bindings;
-exports.keyDownHandler = keyDownHandler;
-exports.keyUpHandler = keyUpHandler;
+// @ts-ignore
+const nodeGypBuild = require("node-gyp-build");
+const keyCodes_cjs_1 = require("./keyCodes.cjs");
+Object.defineProperty(exports, "KeyCodeHelper", { enumerable: true, get: function () { return keyCodes_cjs_1.KeyCodeHelper; } });
+const dirnameLocal_cjs_1 = require("./dirnameLocal.cjs");
+const bindings = nodeGypBuild(path_1.default.resolve(dirnameLocal_cjs_1.__dirnameLocal, ".."));
+const { setKeyDownCallback, setKeyUpCallback, unsetKeyDownCallback, unsetKeyUpCallback, getWindowData, captureWindowN, captureScreenAsync, mouseMove, mouseClick, mouseDrag, typeString, pressKey, imread, imwrite, matchTemplate, blur, bgrToGray, drawRectangle, getRegion, textRecognition } = bindings;
 exports.getWindowData = getWindowData;
 exports.captureWindowN = captureWindowN;
+exports.captureScreenAsync = captureScreenAsync;
 exports.mouseMove = mouseMove;
 exports.mouseClick = mouseClick;
 exports.mouseDrag = mouseDrag;
@@ -38,21 +42,51 @@ function captureWindow(windowName, path) {
     return true;
 }
 /**
- * Represents a class to listen to keyboard events.
+ * 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.
+ */
+function captureScreenToFile(path) {
+    return new Promise((resolve, reject) => {
+        captureScreenAsync().then((buffer) => {
+            fs_1.default.writeFileSync(path, new Uint8Array(buffer));
+            resolve(true);
+        }).catch((err => {
+            reject(err);
+        }));
+    });
+}
+/**
+ * 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
  */
-class KeyListener extends EventEmitter {
+class KeyboardListenerPrivate extends events_1.default {
+    /**
+     * 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() {
         super();
-        keyDownHandler((keyCode) => {
-            const keyName = keyCodes_1.keyCodes.get(keyCode.toString());
+        // Set the callback for key down events.
+        setKeyDownCallback((keyCode) => {
+            // Look up the human-readable key name from a mapping.
+            const keyName = keyCodes_cjs_1.keyCodes.get(keyCode.toString());
+            // Emit the 'keyDown' event to all registered JavaScript listeners.
             this.emit("keyDown", {
                 keyCode,
                 keyName,
             });
         });
-        keyUpHandler((keyCode) => {
-            const keyName = keyCodes_1.keyCodes.get(keyCode.toString());
+        // Set the callback for key up events.
+        setKeyUpCallback((keyCode) => {
+            // Look up the human-readable key name from a mapping.
+            const keyName = keyCodes_cjs_1.keyCodes.get(keyCode.toString());
+            // Emit the 'keyUp' event to all registered JavaScript listeners.
             this.emit("keyUp", {
                 keyCode,
                 keyName,
@@ -60,7 +94,40 @@ class KeyListener extends EventEmitter {
         });
     }
 }
-exports.KeyListener = KeyListener;
+/**
+ * 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.
+ */
+class KeyboardListener {
+    /**
+     * Holds the singleton instance of KeyboardListenerPrivate.
+     */
+    static listenerInstance = null;
+    /**
+     * 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() {
+        if (!this.listenerInstance) {
+            this.listenerInstance = new KeyboardListenerPrivate();
+        }
+        return this.listenerInstance;
+    }
+    /**
+     * 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() {
+        this.listenerInstance = null;
+        unsetKeyDownCallback();
+        unsetKeyUpCallback();
+    }
+}
+exports.KeyboardListener = KeyboardListener;
 /**
  * Represents the OpenCV class that provides image processing functionality.
  */
@@ -154,7 +221,7 @@ function keyPress(keyCode, repeat) {
                 reject('Something went wrong');
             return resolve(true);
         }
-        for (let i = 0; i < repeat; i++) {
+        for (let i = 0; i <= repeat; i++) {
             let result = rawPressKey(keyCode);
             if (!result)
                 reject('Something went wrong');

package/dist/{index.d.ts → index.d.cts}

@@ -1,5 +1,5 @@
-import EventEmitter = require("events");
-import { KeyCodeHelper } from "./keyCodes";
+import EventEmitter from 'events';
+import { KeyCodeHelper } from "./keyCodes.cjs";
 /**
  * Represents the data of a window.
  */
@@ -35,15 +35,15 @@ export type MatchData = {
 export type GetWindowData = (windowName: string) => WindowData;
 export type CaptureWindow = (windowName: string) => Buffer;
 /**
- * The handler to listen to key-down events.
+ * The handler to listen to key-events.
  * @param callback - The callback function to handle key-down events.
  */
-export type KeyDownHandler = (callback: (keyCode: number) => void) => void;
+export type SetKeyCallback = (callback: (keyCode: number) => void) => void;
 /**
- * The handler to listen to key-up events.
- * @param callback - The callback function to handle key-up events.
+ * The handler to stop thread listening to key-events.
+ * @param callback - The callback function to handle key-down events.
  */
-export type KeyUpHandler = (callback: (keyCode: number) => void) => void;
+export type UnsetKeyCallback = () => void;
 /**
  * Function type for moving the mouse.
  */
@@ -81,7 +81,8 @@ export type BgrToGray = (image: ImageData) => 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;
-declare const keyDownHandler: KeyDownHandler, keyUpHandler: KeyUpHandler, getWindowData: GetWindowData, captureWindowN: CaptureWindow, mouseMove: MouseMove, mouseClick: MouseClick, mouseDrag: MouseDrag, typeString: TypeString, textRecognition: TextRecognition;
+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.
@@ -90,20 +91,37 @@ declare const rawPressKey: PressKey;
  * @returns True if the capture and save operation is successful, otherwise false.
  */
 declare function captureWindow(windowName: string, path: string): boolean;
-export interface KeyListener extends EventEmitter {
+/**
+ * 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 {
     /**
-     * Event: Fires when a key is pressed down.
+     * 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 - The callback function to handle the event.
+     * @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;
     /**
-     * Event: Fires when a key is released.
+     * 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 - The callback function to handle the event.
+     * @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;
@@ -111,16 +129,49 @@ export interface KeyListener extends EventEmitter {
     }) => void): this;
 }
 /**
- * Represents a class to listen to keyboard events.
+ * 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
  */
-export declare class KeyListener 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;
+}
 /**
  * Represents the OpenCV class that provides image processing functionality.
  */
-export declare class OpenCV {
+declare class OpenCV {
     imageData: ImageData;
     /**
      * Represents the OpenCV class that provides image processing functionality.
@@ -176,4 +227,4 @@ export declare class OpenCV {
     imwrite(path: string): void;
 }
 declare function keyPress(keyCode: number, repeat?: number): Promise<boolean>;
-export { keyDownHandler, keyUpHandler, getWindowData, captureWindow, captureWindowN, mouseMove, mouseClick, mouseDrag, typeString, keyPress, rawPressKey, KeyCodeHelper, textRecognition };
+export { getWindowData, captureWindow, captureWindowN, mouseMove, mouseClick, mouseDrag, typeString, keyPress, rawPressKey, KeyCodeHelper, textRecognition, captureScreenToFile, captureScreenAsync, KeyboardListener, OpenCV };