Event handlers

Event handlers

---

Like regular macros, event handlers are loaded from Lua-files (extension *.lua), residing in the directory
%FARPROFILE%\Macros\scripts and its subdirectories. Each Lua-file may contain both macros and event handlers.

Loading a handler occurs when the global function Event is called. It receives one argument – a table containing parameters of the event handler. On successful completion the function returns true.

Event {
  group       = "EditorEvent";                          -- string
  description = "Event example";                        -- string (optional field)
  filemask    = "*.txt,*.cpp";                          -- string (optional field)
  priority    = 50;                                     -- number (optional field)
  condition   = function() ...... end;                  -- function (optional field)
  action      = function() ...... end;                  -- function
  id          = "F0109446-AA63-4873-AEC3-17AEE993AA53"; -- string (optional field)
}

The field group can have one of the following values:
"DialogEvent", "EditorEvent", "EditorInput", "ExitFAR", "ViewerEvent", "ConsoleInput".
These names are derived from names of the corresponding functions, exported by the plugin, e.g.:

    export.ProcessDialogEvent -> DialogEvent

The functions condition and action are called with the same parameters as the corresponding exported functions are called (see LuaFAR manual).

When there are multiple event handlers for the same event (i.e. handlers with the same group value), these handlers will be called one after one: a handler having higher priority is called first. Priorities are evaluated dynamically accounting for condition() results if any, the same way it is done for macros.

The ExitFAR handler is called in the following cases: (a) exit from Far Manager, (b) unloading LuaMacro plugin, (c) unloading or reloading macros. The handler receives one argument of boolean type: false for cases (a) and (b); true for case (c).