Keys and key sequences

All of map2’s functions that deal with mapping keys and emmiting virtual input events accept a specific syntax for defining such events.

Single keys

Let’s look at an example, the Mapper::map_key(key, key) function:

import map2

mapper = map2.Mapper()
mapper.map_key("a", "tab")

This function maps the “a” key to the “tab” key and expects a key type for both sides. When functions expect a key, it means that only a single key with optional modifiers is allowed.

Passing in additional modifiers is possible by prepending the keys with one or more of the following special characters:

  • ^: ctrl
  • !: alt
  • +: shift
  • #: meta

Let’s map ALT + a to CTRL + tab:

import map2

mapper = map2.Mapper()

# "ALT + b" to "CTRL + tab"
mapper.map_key("!b", "^tab")

# if we want to map the "!" key, we need to escape it with "\"
mapper.map_key("\\!", "^tab")

# note that we used two "\" since it's a python string

Note: Keys are case-sensitive except special keys discussed in the next section.

Key sequences

Sometimes functions accept more than one key, in which case we need to use the more explicit syntax. Let’s look at the Mapper::map(key, key_sequence) function:

mapper.map("!a", "Hello!")
mapper.map("b", "{ctrl down}{tab}{ctrl up}")

# mixing regular characters with special ones is also allowed
mapper.map("#c", "type this and CTRL+w{ctrl down}w{ctrl up}")

Notice that the first argument is a key type while the second argument is a key_sequence. The special modifier characters are treated as normal characters, instead there are only two special characters in sequences: { and }.

Special keys now need to be surrounded by curly braces, i.e. “tab” becomes {tab}, which will result in tab being pressed and released right after.

In many cases, we want a key to be held for some time, which can be achieved by specifying a state after the key name, i.e. {ctrl down} will press the control key, but not release it.

Valid states are:

  • down
  • up
  • repeat

Special key list

Here’s a list of all special key names you can use with {KEY_NAME}.

Key namesDescription
reserved
escape
esc
backspace
tab
enter
ctrl
leftctrl
left control
shift
leftshift
left shift
right_shift
rightshift
right shift
kpasteriskkeypad '*'
left_alt
leftalt
left meta
space
capslock
f1function 1
f2function 2
f3function 3
f4function 4
f5function 5
f6function 6
f7function 7
f8function 8
f9function 9
f10function 10
numlock
scrolllock
keypad_7
kp7
keypad 7
keypad_8
kp8
keypad 8
keypad_9
kp9
keypad 9
kpminuskeypad '-'
keypad_4
kp4
keypad 4
keypad_5
kp5
keypad 5
keypad_6
kp6
keypad 6
kppluskeypad '+'
keypad_1
kp1
keypad 1
keypad_2
kp2
keypad 2
keypad_3
kp3
keypad 3
keypad_0
kp0
keypad 0
kpdotkeypad '.'
zenkakuhankaku
102nd
f11function 11
f12function 12
ro
katakana
hiragana
henkan
katakanahiragana
muhenkan
kpjpcommakeypad Japanese '、'
kpenterkeypad 'center'
right_ctrl
rightctrl
right control
kpslashkeypad '/'
sysrq
right_alt
rightalt
right alt
linefeed
home
up'up' directional key
page_up
pageup
left'left' directional key
right'right' directional key
end
down'down' directional key
page_down
pagedown
insert
delete
macro
mute
volumedown
volumeup
power
kpequalkeypad '='
kpplusminuskeypad '+/-'
pause
scale
kpcommakeypad ','
hangeul
hanja
yenJPY (円)
meta
leftmeta
left meta
rightmetaright meta
compose
stop
again
props
undo
front
copy
open
paste
find
cut
help
menu
calc
setup
sleep
wakeup
file
sendfile
deletefile
xfer
prog1
prog2
www
msdos
coffee
rotate_display
cyclewindows
mail
bookmarks
computer
back
forward
closecd
ejectcd
ejectclosecd
nextsong
playpause
previoussong
stopcd
record
rewind
phone
iso
config
homepage
refresh
exit
move
edit
scrollup
scrolldown
kpleftparenkeypad '('
kprightparenkeypad ')'
new
redo
f13function 13
f14function 14
f15function 15
f16function 16
f17function 17
f18function 18
f19function 19
f20function 20
f21function 21
f22function 22
f23function 23
f24function 24
playcd
pausecd
prog3
prog4
dashboard
suspend
close
play
fastforward
bassboost
print
hp
camera
sound
question
email
chat
search
connect
finance
sport
shop
alterase
cancel
brightnessdown
brightnessup
media
switchvideomode
kbdillumtoggle
kbdillumdown
kbdillumup
send
reply
forwardmail
save
documents
battery
bluetooth
wlan
uwb
unknown
video_next
video_prev
brightness_cycle
brightness_auto
display_off
wwan
rfkill
micmute
ok
select
goto
clear
power2
option
info
time
vendor
archive
program
channel
favorites
epg
pvr
mhp
language
title
subtitle
angle
zoom
mode
keyboard
screen
pc
tv
tv2
vcr
vcr2
sat
sat2
cd
tape
radio
tuner
player
text
dvd
aux
mp3
audio
video
directory
list
memo
calendar
red
green
yellow
blue
channelup
channeldown
first
last
ab
next
restart
slow
shuffle
break
previous
digits
teen
twen
videophone
games
zoomin
zoomout
zoomreset
wordprocessor
editor
spreadsheet
graphicseditor
presentation
database
news
voicemail
addressbook
messenger
displaytoggle
spellcheck
logoff
frameback
frameforward
context_menu
media_repeat
10channelsup
10channelsdown
images
del_eol
del_eos
ins_line
del_line
fn
fn_esc
fn_f1
fn_f2
fn_f3
fn_f4
fn_f5
fn_f6
fn_f7
fn_f8
fn_f9
fn_f10
fn_f11
fn_f12
fn_1
fn_2
fn_d
fn_e
fn_f
fn_s
fn_b
brl_dot1braille dot 1
brl_dot2braille dot 2
brl_dot3braille dot 3
brl_dot4braille dot 4
brl_dot5braille dot 5
brl_dot6braille dot 6
brl_dot7braille dot 7
brl_dot8braille dot 8
brl_dot9braille dot 9
brl_dot10braille dot 10
numeric_0numpad 0
numeric_1numpad 1
numeric_2numpad 2
numeric_3numpad 3
numeric_4numpad 4
numeric_5numpad 5
numeric_6numpad 6
numeric_7numpad 7
numeric_8numpad 8
numeric_9numpad 9
numeric_starnumpad '*'
numeric_poundnumpad '£'
numeric_anumpad 'a'
numeric_bnumpad 'b'
numeric_cnumpad 'c'
numeric_dnumpad 'd'
camera_focus
wps_button
touchpad_toggle
touchpad_on
touchpad_off
camera_zoomin
camera_zoomout
camera_up
camera_down
camera_left
camera_right
attendant_on
attendant_off
attendant_toggle
lights_toggle
als_toggle
buttonconfig
taskmanager
journal
controlpanel
appselect
screensaver
voicecommand
brightness_min
brightness_max
kbdinputassist_prev
kbdinputassist_next
kbdinputassist_prevgroup
kbdinputassist_nextgroup
kbdinputassist_accept
kbdinputassist_cancel
right_up
right_down
left_up
left_down
root_menu
media_top_menu
numeric_11
numeric_12
audio_desc
3d_mode
next_favorite
stop_record
pause_record
vod
unmute
fastreverse
slowreverse
data
max
btn_0
btn_1
btn_2
btn_3
btn_4
btn_5
btn_6
btn_7
btn_8
btn_9
btn_leftleft mouse button
btn_rightright mouse button
btn_middlemiddle mouse button
btn_side
btn_extra
btn_forward
btn_back
btn_task
btn_trigger
btn_thumb
btn_thumb2
btn_top
btn_top2
btn_pinkie
btn_base
btn_base2
btn_base3
btn_base4
btn_base5
btn_base6
btn_dead
btn_south
btn_east
btn_c
btn_north
btn_west
btn_z
btn_tl
btn_tr
btn_tl2
btn_tr2
btn_select
btn_start
btn_mode
btn_thumbl
btn_thumbr
btn_tool_pen
btn_tool_rubber
btn_tool_brush
btn_tool_pencil
btn_tool_airbrush
btn_tool_finger
btn_tool_mouse
btn_tool_lens
btn_tool_quinttap
btn_touch
btn_stylus
btn_stylus2
btn_tool_doubletap
btn_tool_tripletap
btn_tool_quadtap
btn_gear_down
btn_gear_up
btn_dpad_up
btn_dpad_down
btn_dpad_left
btn_dpad_right
btn_trigger_happy1
btn_trigger_happy2
btn_trigger_happy3
btn_trigger_happy4
btn_trigger_happy5
btn_trigger_happy6
btn_trigger_happy7
btn_trigger_happy8
btn_trigger_happy9
btn_trigger_happy10
btn_trigger_happy11
btn_trigger_happy12
btn_trigger_happy13
btn_trigger_happy14
btn_trigger_happy15
btn_trigger_happy16
btn_trigger_happy17
btn_trigger_happy18
btn_trigger_happy19
btn_trigger_happy20
btn_trigger_happy21
btn_trigger_happy22
btn_trigger_happy23
btn_trigger_happy24
btn_trigger_happy25
btn_trigger_happy26
btn_trigger_happy27
btn_trigger_happy28
btn_trigger_happy29
btn_trigger_happy30
btn_trigger_happy31
btn_trigger_happy32
btn_trigger_happy33
btn_trigger_happy34
btn_trigger_happy35
btn_trigger_happy36
btn_trigger_happy37
btn_trigger_happy38
btn_trigger_happy39
btn_trigger_happy40