Skip to content

Latest commit

 

History

History
157 lines (106 loc) · 6.64 KB

events.md

File metadata and controls

157 lines (106 loc) · 6.64 KB
Raw

Events

Those events are fired on your Terminal instances.

Table of Contents

'resize' event ( width , height )

  • width number the new width in character
  • height number the new height in character

The 'resize' event is emitted when the terminal get resized, and it contains the new width and height. Also term.width and term.height are updated too.

'key' event ( name , matches , data )

  • name string the key name
  • matches Array of matched key name
  • data Object contains more informations, mostly useful for debugging purpose, where:
    • isCharacter boolean is true if this is a regular character, i.e. not a control character
    • codepoint number (optional) the utf-8 code point of the character, if relevant
    • code number or Buffer, for multibyte character it is the raw Buffer input, for single byte character it is a number between 0 and 255

The 'key' event is emitted whenever the user type something on the keyboard.

If name is a single char, this is a regular UTF8 character, entered by the user. If the user type a word, each UTF8 character will produce its own 'key' event.

If name is a multiple chars string, then it is a SPECIAL key.

List of SPECIAL keys:

ESCAPE ENTER BACKSPACE NUL TAB SHIFT_TAB 
UP DOWN RIGHT LEFT
INSERT DELETE HOME END PAGE_UP PAGE_DOWN
KP_NUMLOCK KP_DIVIDE KP_MULTIPLY KP_MINUS KP_PLUS KP_DELETE KP_ENTER
KP_0 KP_1 KP_2 KP_3 KP_4 KP_5 KP_6 KP_7 KP_8 KP_9
F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
SHIFT_F1 SHIFT_F2 SHIFT_F3 SHIFT_F4 SHIFT_F5 SHIFT_F6
SHIFT_F7 SHIFT_F8 SHIFT_F9 SHIFT_F10 SHIFT_F11 SHIFT_F12
CTRL_F1 CTRL_F2 CTRL_F3 CTRL_F4 CTRL_F5 CTRL_F6
CTRL_F7 CTRL_F8 CTRL_F9 CTRL_F10 CTRL_F11 CTRL_F12
CTRL_SHIFT_F1 CTRL_SHIFT_F2 CTRL_SHIFT_F3 CTRL_SHIFT_F4
CTRL_SHIFT_F5 CTRL_SHIFT_F6 CTRL_SHIFT_F7 CTRL_SHIFT_F8
CTRL_SHIFT_F9 CTRL_SHIFT_F10 CTRL_SHIFT_F11 CTRL_SHIFT_F12
SHIFT_UP SHIFT_DOWN SHIFT_RIGHT SHIFT_LEFT
ALT_UP ALT_DOWN ALT_RIGHT ALT_LEFT
CTRL_UP CTRL_DOWN CTRL_RIGHT CTRL_LEFT
SHIFT_INSERT SHIFT_DELETE SHIFT_HOME SHIFT_END SHIFT_PAGE_UP SHIFT_PAGE_DOWN
CTRL_INSERT CTRL_DELETE CTRL_HOME CTRL_END CTRL_PAGE_UP CTRL_PAGE_DOWN
ALT_BACKSPACE ALT_INSERT ALT_DELETE ALT_HOME ALT_END ALT_PAGE_UP ALT_PAGE_DOWN
SHIFT_TAB ALT_TAB
ALT_SPACE CTRL_ALT_SPACE

And modifier on regular A-Z key:

CTRL_A ALT_A CTRL_ALT_A ALT_SHIFT_A
CTRL_B ALT_B CTRL_ALT_B ALT_SHIFT_B
CTRL_C ALT_C CTRL_ALT_C ALT_SHIFT_C
...

Sometime, a key matches multiple combination. For example CTRL-M on linux boxes is always the same as ENTER. So the event will provide as the 'name' argument the most useful/common, here ENTER. However the 'matches' argument will contain [ ENTER , CTRL_M ].

Also notice that some terminal will support less keys. For example, the Linux Console does not support SHIFT/CTRL/ALT + Arrows keys, it will produce a normal arrow key. There is no workaround here, the underlying keyboard driver simply does not support this.

KP_* keys needs applicationKeypad(), e.g. without it KP_1 will report '1' or END.

Some terminal does not support applicationKeypad() at all, sometime turning numlock off can works, sometime not, so it is nearly impossible to differentiate (for example) a KP_1 from an END, or a KP_7 from a HOME: dont rely too much on that!

If you have to use some of those less supported keys, either provide alternatives keys, or make key bindings configurable.

'mouse' event ( name , data )

  • name string the name of the subtype of event
  • data Object provide the mouse coordinates and keyboard modifiers status, where:
    • x number the row number where the mouse is
    • y number the column number where the mouse is
    • ctrl boolean true if the CTRL key is down or not
    • alt boolean true if the ALT key is down or not
    • shift boolean true if the SHIFT key is down or not

Activated when grabInput() is called with the 'mouse' options, e.g. { mouse: 'button' }, { mouse: 'drag' } or { mouse: 'motion' }.

The argument 'name' can be:

  • MOUSE_LEFT_BUTTON_PRESSED: well... it is emitted when the left mouse button is pressed
  • MOUSE_LEFT_BUTTON_RELEASED: when this button is released
  • MOUSE_RIGHT_BUTTON_PRESSED, MOUSE_RIGHT_BUTTON_RELEASED, MOUSE_MIDDLE_BUTTON_PRESSED, MOUSE_MIDDLE_BUTTON_RELEASED: self explanatory
  • MOUSE_WHEEL_UP, MOUSE_WHEEL_DOWN: self explanatory
  • MOUSE_OTHER_BUTTON_PRESSED, MOUSE_OTHER_BUTTON_RELEASED: a fourth mouse button is sometime supported
  • MOUSE_BUTTON_RELEASED: a button were released, however the terminal does not tell us which one
  • MOUSE_MOTION: if the options { mouse: 'motion' } is passed to grabInput(), every moves of the mouse will fire this event, if { mouse: 'drag' } is given, it will be fired if the mouse move while a button is pressed

Good terminals will provide everything: which specific buttons was pressed, which was released, mouse wheel, motions...

Some terminals will just report MOUSE_BUTTON_RELEASED for any button releases instead of the correct MOUSE_LEFT_BUTTON_RELEASED / MOUSE_RIGHT_BUTTON_RELEASED / MOUSE_MIDDLE_BUTTON_RELEASED / MOUSE_OTHER_BUTTON_RELEASED.

Some terminals will never report MOUSE_RIGHT_BUTTON_PRESSED (e.g. Gnome-Terminal), instead it triggers the terminal's context menu.

Some terminals will never report MOUSE_MOTION. By the way, you can still get the mouse position when a button is pressed (or released): the data argument still contains the x and y coordinates of the mouse when said event was fired.

So your application should not rely too much on less supported features: it should always provide alternatives.

'terminal' event ( name , data )

  • name string the name of the subtype of event
  • data Object provide some data depending on the event's subtype

The 'terminal' event is emitted for terminal generic information.

The argument 'name' can be:

  • CURSOR_LOCATION: it is emitted in response of a requestCursorLocation(), data contains 'x' & 'y', the coordinate of the cursor.

  • SCREEN_SIZE: rarely useful it is emitted in response of a requestScreenSize(), data contains 'width' & 'height', the size of the screen in characters, and 'resized' (true/false) if the size has changed without node.js being notified

  • FOCUS_IN: it is emitted if the terminal gains focus (if supported by your terminal)

  • FOCUS_OUT: it is emitted if the terminal loses focus (if supported by your terminal)