# electron-webcontents-shortcut

> register/unregister a keyboard shortcut locally to a webContents instance, using `before-input-event`

Latest version **1.0.8** (published 2023-12-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install electron-webcontents-shortcut
pnpm add electron-webcontents-shortcut
yarn add electron-webcontents-shortcut
bun add electron-webcontents-shortcut
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.8 |
| Published | 2023-12-17 |
| First published | 2023-12-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 20.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | auhnip |
| Maintainers | auhnip |
| Keywords | electron, shortcuts, webContents |

## Links

- npm: https://www.npmjs.com/package/electron-webcontents-shortcut
- Repository: https://github.com/Auhnip/electron-webcontent-shortcut
- Homepage: https://github.com/Auhnip/electron-webcontent-shortcut#readme
- Issues: https://github.com/Auhnip/electron-webcontent-shortcut/issues
- npm.io page: https://npm.io/package/electron-webcontents-shortcut

## Dependencies (1)

- [debug](https://npm.io/package/debug.md) ^4.3.4

## Recent versions

- 1.0.8 (latest) — 2023-12-17
- 1.0.7 — 2023-12-17
- 1.0.6 — 2023-12-17
- 1.0.5 — 2023-12-16
- 1.0.4 — 2023-12-16
- 1.0.3 — 2023-12-16
- 1.0.2 — 2023-12-16
- 1.0.1 — 2023-12-16
- 1.0.0 — 2023-12-16

## README

# electron-webcontents-shortcut

## Overview

This project is inspired by another project, [electron-localshortcut](https://www.npmjs.com/package/electron-localshortcut), with a similar implementation principle but enhanced functionality. In comparison to `electron-localshortcut`, this project offers greater flexibility, allowing users to freely bind shortcuts in the multi-process environment of Electron applications, including `BrowserWindow`, `BrowserView`, and `Webview`.

## Background

In `electron-localshortcut`, shortcuts can only be bound to a `BrowserWindow`, limiting its use in Electron applications with multiple processes that may involve the use of `BrowserView` or `Webview`. To address this limitation, this project relaxes the constraints imposed by `electron-localshortcut`, enabling users to bind shortcuts to any source of `WebContents`, thus better accommodating the needs of multi-process applications.

## Features

- **Flexibility**: Shortcuts can be bound to sources from any `WebContents`, including `BrowserWindow`, `BrowserView`, `Webview`, and more.

## Installation

Install via npm:

```bash
npm install electron-webcontents-shortcut
```

## Usage

Import this module into your Electron project:

```javascript
const shortcutManager = require('electron-webcontents-shortcut');
```

Then, use the following methods to bind shortcuts:

```javascript
const { register } = shortcutManager;

app.whenReady().then(() => {
  const win = new BrowserWindow({
    width: 600,
    height: 400,
  });

  win.loadURL('https://www.electronjs.org//');

  register(win.webContents, 'Ctrl+Shift+O', () => {
    console.log('Ctrl+Shift+O');
    win.webContents.openDevTools({ mode: 'detach' });
  });
});
```

## API

### 1. `isAccelerator(input: string): boolean`

Checks whether a given string is a valid representation of a keyboard accelerator. A valid accelerator should consist of any number of modifier keys followed by a regular key. For example, `Shift+Alt+P`.

### 2. `unregisterAll(webContents: WebContents): void`

Unregisters all keyboard shortcuts associated with the specified `webContents`.

### 3. `register(webContents: WebContents, accelerator: string | string[], callback: () => void): void`

Registers a keyboard shortcut on the specified `webContents`. The `accelerator` parameter can be a string or an array of strings representing the keyboard shortcut(s), and the `callback` function will be invoked when the shortcut is triggered.

### 4. `unregister(webContents: WebContents, accelerator: string | string[]): void`

Unregisters the specified keyboard shortcut(s) associated with the given `webContents`.

### 5. `isRegistered(webContents: WebContents, accelerator: string): boolean`

Checks whether a specific keyboard shortcut is registered on the specified `webContents`.

### Example Usage

```javascript
const {
  isAccelerator,
  register,
  unregister,
  unregisterAll,
  isRegistered,
} = require('electron-webcontents-shortcut');

// Check if a string is a valid accelerator
if (isAccelerator('Ctrl+A')) {
  const webContents = // ... obtain WebContents instance
    // Register a keyboard shortcut
    register(webContents, 'Ctrl+A', () => {
      // Handle the shortcut
    });

  // Check if a shortcut is registered
  if (isRegistered(webContents, 'Ctrl+A')) {
    // Do something
  }

  // Unregister a shortcut
  unregister(webContents, 'Ctrl+A');

  // Unregister all shortcuts
  unregisterAll(webContents);
}
```

## Contribution

If you encounter any issues or have suggestions for improvement, feel free to raise an issue or submit a pull request. We welcome and appreciate your contributions!

## License

This project is licensed under the MIT License. For details, see the [LICENSE](LICENSE.md) file.

---
_Source: https://npm.io/package/electron-webcontents-shortcut · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._