1 | # Usage
|
2 | ## Usage with Electron
|
3 | Before installing this module, you will need to set a runtime version.
|
4 |
|
5 | When developing with webpack, you will need the Node.js runtime. In production, your Electron app will need the Electron version.
|
6 |
|
7 | Checkout your ABI for [node.js](https://nodejs.org/en/download/releases/) or [electron](https://www.npmjs.com/package/electron-abi). The example below uses Node.js v9.X and Electron v1.8.X.
|
8 |
|
9 | ```json
|
10 | "iohook": {
|
11 | "targets": [
|
12 | "node-59",
|
13 | "electron-57"
|
14 | ],
|
15 | "platforms": [
|
16 | "win32",
|
17 | "darwin",
|
18 | "linux"
|
19 | ],
|
20 | "arches": [
|
21 | "x64",
|
22 | "ia32"
|
23 | ]
|
24 | }
|
25 | ```
|
26 |
|
27 | ::: tip
|
28 | if you use a two-package.json structure, add this to application package.json.
|
29 | :::
|
30 |
|
31 | ## Usage in a generic Node application
|
32 | Here is a simple example :
|
33 |
|
34 | ```javascript
|
35 | 'use strict';
|
36 |
|
37 | const ioHook = require('iohook');
|
38 |
|
39 | ioHook.on('mousemove', event => {
|
40 | console.log(event); // { type: 'mousemove', x: 700, y: 400 }
|
41 | });
|
42 |
|
43 | // Register and start hook
|
44 | ioHook.start();
|
45 |
|
46 | // Alternatively, pass true to start in DEBUG mode.
|
47 | ioHook.start(true);
|
48 | ```
|
49 |
|
50 | ## Available events
|
51 |
|
52 | ### keydown
|
53 |
|
54 | Triggered when user presses a key.
|
55 |
|
56 | ```js
|
57 | {
|
58 | keycode: 46,
|
59 | rawcode: 8,
|
60 | type: 'keydown',
|
61 | altKey: true,
|
62 | shiftKey: true,
|
63 | ctrlKey: false,
|
64 | metaKey: false
|
65 | }
|
66 | ```
|
67 |
|
68 | ### keyup
|
69 |
|
70 | Triggered when user releases a key.
|
71 |
|
72 | ```js
|
73 | {
|
74 | keycode: 19,
|
75 | rawcode: 15,
|
76 | type: 'keyup',
|
77 | altKey: true,
|
78 | shiftKey: true,
|
79 | ctrlKey: false,
|
80 | metaKey: false
|
81 | }
|
82 | ```
|
83 |
|
84 | ### mouseclick
|
85 |
|
86 | Triggered when user clicks a mouse button.
|
87 | ```js
|
88 | { button: 1, clicks: 1, x: 545, y: 696, type: 'mouseclick' }
|
89 | ```
|
90 |
|
91 | ### mousedown
|
92 |
|
93 | Triggered when user clicks a mouse button.
|
94 |
|
95 | ```js
|
96 | { button: 1, clicks: 1, x: 545, y: 696, type: 'mousedown' }
|
97 | ```
|
98 |
|
99 | ### mouseup
|
100 |
|
101 | Triggered when user releases a mouse button.
|
102 |
|
103 | ```js
|
104 | { button: 1, clicks: 1, x: 545, y: 696, type: 'mouseup' }
|
105 | ```
|
106 |
|
107 | ### mousemove
|
108 |
|
109 | Triggered when user moves the mouse.
|
110 |
|
111 | ```js
|
112 | { button: 0, clicks: 0, x: 521, y: 737, type: 'mousemove' }
|
113 | ```
|
114 |
|
115 | ### mousedrag
|
116 |
|
117 | Triggered when user clicks and drags something.
|
118 |
|
119 | ```js
|
120 | { button: 0, clicks: 0, x: 373, y: 683, type: 'mousedrag' }
|
121 | ```
|
122 |
|
123 | ### mousewheel
|
124 |
|
125 | Triggered when user uses the mouse wheel.
|
126 |
|
127 | ```js
|
128 | { amount: 3, clicks: 1, direction: 3, rotation: 1, type: 'mousewheel', x: 466, y: 683 }
|
129 | ```
|
130 |
|
131 | ## Shortcuts
|
132 |
|
133 | You can register global shortcuts.
|
134 |
|
135 | ::: tip NOTE
|
136 | When a shortcut is caught, keyup/keydown events still emit events. It means, that if you register a keyup AND shortcut for `ALT+T`, both events will be emited.
|
137 | :::
|
138 |
|
139 | ### registerShortcut(keys, callback, releaseCallback?)
|
140 |
|
141 | In the next example we register CTRL+F7 shortcut (in MacOS. For other OSes, the keycodes could be different).
|
142 |
|
143 | ```js
|
144 | const id = ioHook.registerShortcut([29, 65], (keys) => {
|
145 | console.log('Shortcut called with keys:', keys)
|
146 | });
|
147 | ```
|
148 |
|
149 | We can also specify a callback to run when our shortcut has been released by specifying a third function argument.
|
150 |
|
151 | ```js
|
152 | const id = ioHook.registerShortcut([29, 65], (keys) => {
|
153 | console.log('Shortcut called with keys:', keys)
|
154 | }, (keys) => {
|
155 | console.log('Shortcut has been released!')
|
156 | });
|
157 | ```
|
158 |
|
159 | ### unregisterShortcut(shortcutId)
|
160 |
|
161 | You can unregister shortcut by using shortcutId returned by `registerShortcut()`.
|
162 |
|
163 | ```js
|
164 | ioHook.unregisterShortcut(id);
|
165 | ```
|
166 |
|
167 | ### unregisterShortcutByKeys(keys)
|
168 |
|
169 | You can unregister shortcut by using the keys codes passed to `registerShortcut()`. Passing codes in the same order as during registration is not required.
|
170 |
|
171 | ```js
|
172 | ioHook.unregisterShortcutByKeys(keys);
|
173 | ```
|
174 |
|
175 | ### unregisterAllShortcuts()
|
176 |
|
177 | You can also unregister all shortcuts.
|
178 | ```js
|
179 | ioHook.unregisterAllShortcuts();
|
180 | ```
|
181 |
|
182 | ### useRawcode(using)
|
183 |
|
184 | Some libraries, such as [Mousetrap]() will emit keyboard events that contain
|
185 | a `rawcode` value. This is a separate, but equally valid, representation of
|
186 | the key that was pressed. However by default iohook instead uses an event's
|
187 | `keycode` field to determine which key was pressed. If these key codes do not
|
188 | line up, your shortcut will not be detected as pressed.
|
189 |
|
190 | To tell iohook to use the `rawcode` value instead, simply do so before
|
191 | starting iohook.
|
192 |
|
193 | ```js
|
194 | iohook.useRawcode(true);
|
195 | iohook.start();
|
196 | ```
|
197 |
|
198 | ### disableClickPropagation()
|
199 |
|
200 | You can disable mouse click event propagation. Click events are captured and emitted but not propagated to the window.
|
201 |
|
202 | ```js
|
203 | ioHook.disableClickPropagation();
|
204 | ```
|
205 |
|
206 | ### enableClickPropagation()
|
207 |
|
208 | You can enable mouse click event propagation if it's disabled. Click event are propagated by default.
|
209 |
|
210 | ```js
|
211 | ioHook.enableClickPropagation();
|
212 | ```
|