AddToMenu

AddToMenu

---

AddToMenu (where, text, hotkey, file [, ...])

Function AddToMenu is available to the _usermenu.lua script.
It allows to add a specified utility to the plugin’s menu and assign it a hot key.

Parameters

1. where
   Where the utility is intended to run from: any combination of letters [cdepv] (c=configuration menu, d=dialog, e=editor, p=panels, v=viewer).

2. text
   Text that should appear in the menu.
   — To assign a hot key without adding a menu item, supply a nil.
   — To add a separator, specify a string beginning with ":sep:" following by optional text, e.g. ":sep:Block commands".
   — If the utility for localization is used, and text begins with "::", then the rest of the text is treated as a message identifier. (In the case of separator, prefix ":sep:::" can be used).

3. hotkey
   A key combination for calling the utility, e.g. "Alt+Shift+F4".
   Supply nil if no hot key is needed.
   NOTE: a hot key assigned this way works only from Editor, provided that no macro is assigned to that key.

4. file
   A specification for a Lua script to run upon this item activation. The exact file name is determined according to the same rules as with require function, that is, package.path is used to search for the file. But contrary to require, the value returned by the script is not cached in package.loaded.

5. Extra parameters (optional)
   Values that will be passed to user script (they are passed to the script in a table). There can be any number of values of any Lua type.

Examples

  AddToMenu ("e",   "Count words",   nil,      "farscripts.edit.count", "words")
  AddToMenu ("e",   "Count letters", "Alt+F2", "farscripts.edit.count", "letters")
  AddToMenu ("e",   "Search",        "Ctrl+F", "farscripts.edit.search")
  AddToMenu ("p",   "Rename Files",  nil,      "farscripts.rename")
  AddToMenu ("evp", "Calendar",     "Alt+F12", "farscripts.calendar",   "show")

To assign a hot key to a built-in utility, supply text as true and specify the menu position via file:

  AddToMenu ("e",   true,           "Ctrl+1",  1)