Lazarus IDE with Gamepad on Linux
On occasion, particularly if exploring rarely-visited legacy code, it might be necessary to do an inordinate amount of single stepping. Particularly if afflicted with some degree of RSI, continual use of a PC keyboard's function keys- not to mention obscure control combinations- can become surprisingly uncomfortable; users with chilly workrooms might also appreciate a solution that allows them to keep their hands under a blanket or inside the sleeves of a dressing gown.
There are many utility programs on both Windows and Linux that map events from various kinds of game controller to the keyboard. However many of these, not to mention hardware solutions like the Logitech G600 gamer's mouse, are unable to generate function key presses and releases qualified by the control key etc. On Linux it is possible instead to map events either at the kernel or at the X11 level, neither is particularly well documented and it is possible to end up- particularly in the X11 case- having to use one program to detect an event and a separate one to emit a keyboard sequence.
The example below uses the MXK program http://welz.org.za/projects/mxk to map eight buttons from an NES-style gamepad https://en.wikipedia.org/wiki/File:Super-Famicom-Controller.jpg to the key combinations most commonly used during debugging. In addition it has useful mappings for the directional pad, but these are commented out by default since a rogue event source can render a system unusable.
#!/usr/local/bin/mxk -dp
# Experimental mapping from Belkin/Razer Nostromo to Lazarus debugger. For
# Debian 12 ("Bookworm") with Linux kernel v6 and later invoke like
#
# mxk -dp /etc/nostromo-to-lazarus.mxk
#
# For older versions it might be necessary to invoke like
#
# mxk -dzp /etc/gamepad-to-lazarus.mxk
#
# and remove the 'quit' command from the end.
#
# In either case, terminate by running interactively using mxk -a and
# issuing the halt command.
#
# Refer to http://welz.org.za/projects/mxk/mxk-tutorial.pdf MarkMLl.
# The mxk executable can, in fact usefully be a script like
#
# #!/bin/sh
#
# /usr/local/bin/mxk-release -u $HOME/.mxk $@
#
# which will allow it to be run by any member of the input group.
# L-shoulder top2 Run F9
# R-shoulder pinkie Stop Ctrl + F2
# Select base3 Compile Ctrl + F9
# Start base4 Build Shift + F9
# X trigger Step over F8
# Y top Step into F7
# A thumb Step out Shift + F8
# B thumb2 Step to cursor F4
# Pad-up Abs Y -ve Virt1 Call stack Ctrl + Alt + S
# Pad-right Abs X +ve Virt2 Breakpoints Ctrl + Alt + B
# Pad-down Abs Y +ve Virt3 Find in Files Ctrl + Shift + F
# Pad-left Abs X -ve Virt4 Insert ToDo Ctrl + Shift + T
# Note that Lazarus's default Stop Ctrl + F2 clashes with KDE's System Settings
# -> Shortcuts -> Global Shortcuts -> System Settings -> Switch to Desktop 2.
# The source is identified by a (partial) match of the name. YMMV.
name-source 0 usb gamepad
# Array 0 maps physical gamepad buttons and virtual buttons derived from the
# directional pad to output key sequences. Edit this to suit the actions you
# want the IDE to perform.
start-array 0
press-array 0 top2 f9/press sync:
release-array 0 top2 f9/release sync:
press-array 0 pinkie leftcontrol/press f2/press sync:
release-array 0 pinkie f2/release leftcontrol/release sync:
press-array 0 base3 leftcontrol/press f9/press sync:
release-array 0 base3 f9/release leftcontrol/release sync:
press-array 0 base4 leftshift/press f9/press sync:
release-array 0 base4 f9/release leftshift/release sync:
press-array 0 trigger f8/press sync:
release-array 0 trigger f8/release sync:
press-array 0 top f7/press sync:
release-array 0 top f7/release sync:
press-array 0 thumb leftshift/press f8/press sync:
release-array 0 thumb f8/release leftshift/release sync:
press-array 0 thumb2 f4/press sync:
release-array 0 thumb2 f4/release sync:
press-array 0 virt1 leftcontrol/press leftalt/press s/press sync:
release-array 0 virt1 s/release leftalt/release leftcontrol/release sync:
press-array 0 virt2 leftcontrol/press leftalt/press b/press sync:
release-array 0 virt2 b/release leftalt/release leftcontrol/release sync:
press-array 0 virt3 leftcontrol/press leftshift/press f/press sync:
release-array 0 virt3 f/release leftshift/release leftcontrol/release sync:
press-array 0 virt4 leftcontrol/press leftshift/press t/press sync:
release-array 0 virt4 t/release leftshift/release leftcontrol/release sync:
# Vectors 1 and 2 map absolute events generated by the directional pad to
# virtual keys, which are subsequently expanded by array 0. YMMV.
start-vector 1 x
point-vector 1 virt4 0
point-vector 1 virt2 255
point-vector 1 virt255 127
start-vector 2 y
point-vector 2 virt1 0
point-vector 2 virt3 255
point-vector 2 virt255 127
# Declare which keys the target may emit, then wire the nodes together. If you
# don't want the direction pad events then comment out the two lines that have
# vectors 1 and 2 as their source.
start-target 0 key:f2 key:f4 key:f7 key:f8 key:f9 key:leftshift key:leftcontrol key:leftalt key:s key:b key:f key:t
connect-node source:0 array:0
connect-node source:0 vector:1
connect-node source:0 vector:2
# connect-node vector:1 array:0
# connect-node vector:2 array:0
connect-node array:0 target:0
lock-source 0
# The key/button allocation and names will depend very much on the input device,
# and with cheap Chinese peripherals will be anybody's guess. Use evtest to see
# the raw events, and then refer to codes.c in the mxk source. Again, YMMV.
quit
# This script normally lives at http://wiki.freepascal.org/Lazarus_IDE_with_Gamepad_on_Linux
Save that as /etc/gamepad-to-Lazarus.mxk, it may be used both as a script and a configuration file.
With thanks to Neal Stephenson's "Dr. X" for the initial inspiration, and to Marc Welz for help with the fiddly detail.
