Regular macros

Regular macros

A macro is loaded by the global function Macro that receives one argument – a table containing parameters of the macro. On successful completion the function returns true.

  Macro {
    area         = "Shell Info Tree";                         -- string
    key          = "CtrlF11 ShiftHome";                       -- string (optional field)
    description  = "Macro example";                           -- string (optional field)
    flags        = "NoPluginPanels EmptyCommandLine";         -- string (optional field)
    filemask     = "*.txt,*.cpp";                             -- string (optional field)
    priority     = 50;                                        -- number (optional field)
    sortpriority = 50;                                        -- number (optional field)
    selected     = true;                                      -- boolean (optional field)
    condition    = function(key) return Far.Height>30 end;    -- function (optional field)
    action       = function() msgbox("","Macro example") end; -- function
    id           = "F0109446-AA63-4873-AEC3-17AEE993AA53";    -- string (optional field)
  }

1. The field area should contain names of one or more areas, separated by whitespaces.

2. The field key can contain names of one or more keys, separated by whitespaces.
   Keys can contain modifiers: Ctrl,LCtrl,RCtrl,Alt,RAlt,LAlt,Shift.
   Ctrl means “any of LCtrl,RCtrl”, the same goes for Alt. The order of modifiers can be arbitrary.
   
   Alternatively, the field key can be specified as a regular expression, enclosed in slashes (/).

   • In this case /Ctrl/ will not work when RCtrl is pressed, it should be specified explicitly /[LR]Ctrl/ etc.
   • Also in this case it is necessary to maintain the order in the sequence Ctrl,Alt,Shift,
     e.g. /[LR]Alt[LR]CtrlF1/ would never work.
     
     

3. Optional field flags may contain a set of flags separated with spaces. Some changes in names or interpretation of flags are described here.

4. Optional field priority – a number in the range 0 to 100. The default value = 50.
   Macros added via MCTL_ADDMACRO have priority = 50.

5. Optional field sortpriority – a number in the range 0 to 100. The default value = 50.
   This field affects the order of macros in the macro selection menu.

6. Optional field selected – a boolean.
   This field assigns this macro to be initially selected in the macro selection menu.

7. Optional field filemask – a string.
   It is applicable only for Editor and Viewer areas. It is processed according to the same rules that Far Manager applies for file masks when searching from panels, etc. If name of the file open in editor or viewer does not match the given mask, the macro will not execute.

8. Optional field condition – a function.

   • It is called with one argument: the name of pressed key. For auto-started macros it is called with no arguments.
   • If the function returns false/nil/nothing, the macro will not execute.
   • If it returns a number then this number is used instead of priority.
   • In other cases of return value (e.g., true) priority is used.
     
     

9. Field action – a function.
   If the macro has passed successfully all preliminary checks (area, flags, file mask, priority) then this functgion is called.

10. More than one macro for (key,area) combination is allowed. In this case a macro with highest priority is executed. If there are multiple macros having the same priority then the macro selection menu is displayed.
    The auto-starting macros are executed all, one by one, independently from priorities. The order of their execution is not defined.