far.Menu

LuaFAR 3

far.Menu


Item, Position = far.Menu (Properties, Items [, BreakKeys])

Parameters:
  Properties: table
    fields of Properties (every field is optional):
      X:            integer
      Y:            integer
      MaxHeight:    integer
      Flags:        flags   (default = FMENU_WRAPMODE)
      Title:        string
      Bottom:       string
      HelpTopic:    string
      SelectIndex:  integer (1-based)
      Id:           string  (GUID)

  Items: table (array of menu items)
      a menu item is a table;
      fields of a menu item (every field is optional):
        text:         string
        checked:      boolean, or string
        separator:    boolean
        disable:      boolean
        grayed:       boolean
        hidden:       boolean
        selected:     boolean
        AccelKey:     table tFarKey (or string - key name used in Far macros)

  BreakKeys:
      Either table (array of break key items)
        a break key item is a table;
        fields of a break key item:
          BreakKey:     string (see NOTE 2)
      Or string (space delimited sequence of keys)

Returns:
  Item:     table   Either the selected element of Items array (if Enter was pressed)
                    or an element of BreakKeys array (if a corresponding break key was
                    pressed). If a break key was pressed and BreakKeys argument was a string
                    then the returned table is created by far.Menu function.
            nil     The menu was cancelled by the user.

  Position: integer Position of the selected item at the moment of closing the menu.
            nil     The menu was cancelled by the user.

NOTE 1
  Properties.SelectIndex=N is equivalent to Items[N].selected=true
  but it has a higher priority.

NOTE 2
  Example of constructing a BreakKey string:
  BreakKey="AS+DELETE", where:
    AS     - stands for AltShift
    +      - separates key modifiers from key
    DELETE - virtual key VK_DELETE (prefix VK_ is removed).

  Key names used in Far macros are also acceptable, e.g. BreakKey="AltShiftDel"

NOTE 3
  The first return value (Item) can be used by the program for performing
  the item-specific action. To do so, the program can put some specific field(s)
  into each element of Items and BreakKeys tables. For example, such fields
  can be "action", "filename", etc.

Far API used:
  Menu