Triggers

Triggers

Luamacros performs tasks (macros) scripted in lua language based on some actions - triggers. The most common trigger is pressing key at some keyboard but luamacros supports others. Currently (in Feb 2019) these triggers are available

• keyboard key
• game device (joystick) button
• game device axis value change, e.g. moving joystick, turning steering wheel
• data arriving on COM port
• request to build-in http server
• X plane dataref change
• timer - tasks performed after specified time

Let's have a closer look how are those triggers defined in lua.

Keyboards

Specific key

The most specific way how to define action for keyboard key is to use lmc_set_handler with 4 parameters

• logical name of the keyboard
• key number - this is virtual key code
• direction flag - value 1 means action is triggered on key press, 0 means on key release
• handler - the lua function itself which is executed on key press/release

The handler function can read up to 4 parameters

• key number - in this case it will be always the same value as 2nd parameter of lmc_set_handler
• direction - again for this case it will be always the same value as 3rd parameter of lmc_set_handler
• timestamp in milliseconds - unix epoch timestamp indicating when exactly the action happened. Note this doesn't have to be current time - handlers can get delayed in lua queue
• flags - integer with additional flags helping to recognize e.g. left and right ctrl/shift. This parameter was added in version 0.1.1.98

So for example to define handler that just prints some output when key A is pressed you can do

log_handler = function(button, direction, ts, flags)
  print('Callback for device: button ' .. button .. ', direction '..direction..', ts '..ts..', flags '..flags)
end

lmc_set_handler('KEYBOARD_1',65,1,log_handler)

Or inline and simple version

lmc_set_handler('KEYBOARD_1',65,1,function()
  print('A was pressed')
end)

Whole keyboard

Defining macro for specific key is useful if you need single or a few keys as macro triggers. Rest of the keyboard is not affected by luamacros. However it's quite common that you connect additional keyboard dedicated for macros. In this case you can set handler for whole keyboard and perform appropriate action in handler code - based on scanned key code. When lua handler is assigned to whole keyboard then luamacros blocks all key actions in Windows. In other words key press and release never arrives to active application even if you don't perform any action in lua handler. There are technical reasons why you cannot control this blocking/passing e.g. by return value of the handler. If you need to pass some keys from the keyboard to active application you have to define macros for each separate keys (see above).

To define handler for whole keyboard you the same call lmc_set_handler but with 2 parameters only

• logical name of the keyboard
• handler - the lua function itself which is executed on key press/release

Handler parameters are the same and now they come handy because you can find out which key was pressed/released and act accorodigly

• key number - virtual key code of pressed/released key
• direction - 1 for press, 0 for release
• timestamp in milliseconds - unix epoch timestamp indicating when exactly the action happened
• flags - integer with additional flags helping to recognize e.g. left and right ctrl/shift. This parameter was added in version 0.1.1.98

Simple example of whole device handler

log_handler = function(button, direction, ts, flags)
  print('Callback for device: button ' .. button .. ', direction '..direction..', ts '..ts..', flags '..flags)
end

lmc_set_handler('KEYBOARD_1',log_handler)