npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@futpib/node-global-key-listener

v1.0.3

Published

A module to listen to global key events

Downloads

335

Readme

node-global-key-listener

Description

A simple, cross-platform NodeJS package which can be used to listen to and capture keyboard events.

Compatibility table:

| Platform | Compatible? | Tested | | -------- | --------------- | ------------- | | Windows | True | Win10 | | Mac | True | Mac OS Mojave | | Linux | X11 only | Arch Linux |

This keyboard listener was originally made for the productivity application, LaunchMenu.

Usage

import {GlobalKeyboardListener} from "node-global-key-listener";
const v = new GlobalKeyboardListener();

//Log every key that's pressed.
v.addListener(function (e, down) {
    console.log(
        `${e.name} ${e.state == "DOWN" ? "DOWN" : "UP  "} [${e.rawKey._nameRaw}]`
    );
});

//Capture Windows + Space on Windows and Command + Space on Mac
v.addListener(function (e, down) {
    if (
        e.state == "DOWN" &&
        e.name == "SPACE" &&
        (down["LEFT META"] || down["RIGHT META"])
    ) {
        //call your function
        return true;
    }
});

//Capture ALT + F
v.addListener(function (e, down) {
    if (e.state == "DOWN" && e.name == "F" && (down["LEFT ALT"] || down["RIGHT ALT"])) {
        //call your function
        return true;
    }
});

//Call one listener only once (demonstrating removeListener())
calledOnce = function (e) {
    console.log("only called once");
    v.removeListener(calledOnce);
};
v.addListener(calledOnce);

/* 
 To add logging of errors please use. This is hopefully not needed in most cases, but may still be useful in production.
    new GlobalKeyboardListener({
        windows: {
            onError: (errorCode) => console.error("ERROR: " + errorCode),
            onInfo: (info) => console.info("INFO: " + info)
        },
        mac: {
            onError: (errorCode) => console.error("ERROR: " + errorCode),
        }
    })
*/

Installation

To install this npm package call:

npm install node-global-key-listener

Is this the right package for you?

NodeJS has various packages for listening to keyboard events raised in the operating system. We may not have created the best package for you, please use the below descriptions to aid you in making your decision:

Electron::globalShortcut

Advantages:

  • Native to electron apps
  • No compiling issues with Node-gyp
  • All execution occurs in-process

Disadvantages:

  • On Windows: Cannot override windows specific shortcuts. E.G. Ctrl+Alt+Delete or Windows+Space etc.
  • On Mac: Will not prevent other applications from listening for events
  • Cannot easily be used to listen for arbitrary keys
  • Requires electron in order to function.

IOHook

Advantages:

  • All execution occurs in-process
  • On Windows: Allows capture of windows specific shortcuts. E.G. Ctrl+Alt+Delete or Windows+Space etc.
  • On Mac: Prevents other applications from listening for captured events.

Disadvantages:

  • Cannot easily be used to listen for arbitrary keys
  • Requires compilation with node-gyp. Sometimes the package is released with binaries, however these binaries need to be compiled seperately for each version of node. Furthermore, when compile errors occur the code given is a black box which you will need to fix, which may be complex if you're not used to the languages they are written in.

node-global-key-listener

Advantages:

  • Easy to setup as an arbitrary key listener/logger.
  • Does not require node-gyp. Our package comes with pre-compiled binaries which are compatible with your OS and not dependent on node version.
  • On Windows: Allows capture of windows specific shortcuts. E.G. Ctrl+Alt+Delete or Windows+Space etc.
  • On Mac: Prevents other applications from listening for captured events.

Disadvantages:

  • Most execution occurs out-of-process. Our package executes and runs a seperate key server which NodeJS interfaces with over stdio. This means that this application might require permission to run depending on your anti-virus system.
  • Some workarounds used may rarely lead to unexpected functionality, see windows specific implementation of windows key listeners
  • If installed into an application on Mac explicit permission will be required from the user via Accessibility.

Developement

If modifying the typescript code you will have to run the following command in a terminal in the root directory of this package:

npm run watch

This will cause the application to recompile the typescript whenever the source code is changed. If you are making a change to an application for a single system, please consider adding these changes to both keyboard servers if possible. Generally we will work on both simultaneiously however we know this is not always possible.

Modifying the compiled binaries

To modify the Windows C++ or Mac Swift source code please compile these applications before testing with:

Pre-requisites

Windows

This project is configured to use mingw, and thus this should be installed before compiling the source code.

Compiling the binary code

To compile the source code of these applications use the below command line commands respective to the system you are working on.

Windows
npm run compile-win
Mac
npm run compile-mac
Linux (X11)
npm run compile-x11

Notes

  • If Including this package into an Electron application, the built application will require explicit permission from the user on Mac OS X systems.
  • Given that a fallback may be required we may release an electron-global-key-listener package to accommodate this in the future. In our case for LaunchMenu, our fallback is implemented in core/keyHandler.