Module action

Generic menu system for EE, flexible enough to handle GM buttons, comms menus, and custom station button menus.

Any ... function argument in examples below refers to the target arguments of the menu, which should be specified in implementations.

Supported menu item list fields:

  • allowHome: Whether to allow returning directly to the top-level menu from this menu. Default true.
  • allowBack: Whether to allow returning to the parent menu. Default true.
  • allowSticky: Whether to allow sticky menu items to display with this menu. Default true.

Supported menu item fields:

Any entry with a description starting with [F] may be replaced with a function(...) returning the described value.

{
    -- Exactly one of the following three fields must be present.
    -- [F] Name of button.
    button = "Button Name",
    -- [F] Text for info panel/comms message.
    info = "Info Text",
    -- [F] List of menu items to substitute for this item if shown.
    expand = {},

    -- [F] The action to perform when the button is pressed.
    -- Only valid on button items. See below for valid values.
    action = ...,
    -- Whether to allow returning to the current menu after this
    -- submenu is entered. Only valid on button items. Default true.
    allowBack = true,

    -- Whether the item is a debug item that should only be displayed
    -- when the 'menuOptions' debug toggle is enabled. Default false.
    isDebug = false,
    -- Order the item relative to other items.
    order = 42,
    -- Function defining when to show the menu item. If no function is
    -- provided, the item is always shown.
    when = function(...) ... end,
    -- Menu item to replace this item with if the function provided in
    -- when returns false.
    otherwise = {},

    -- Top-level items only. If true, the item is 'sticky' and will
    -- display regardless of which menu is open. Default false.
    sticky = false,
}

Supported menu item action values:

  • nil: return to top-level menu.
  • false: re-display current menu.
  • number: go back N menus. Zero is equivalent to false. Values greater than the number of preceding menus are equivalent to nil.
  • menu list: display these items.

MenuSet

MenuSet() Create a new MenuSet, which can be used like a menu list but has an add method for ease of use.
menuSet:add(entry) Add an entry to this MenuSet.

ActionBase

ActionBase(provider) Create a new ActionBase-derived type, using the given provider implementation.
actionBase:add(entry) Add a top-level entry to this Menu
actionBase:setMenu(menu, ...) Set the current menu to menu for the provided target.
actionBase:refreshMenu(...) Refresh the currently-displayed menu for the provided target.

Provider

provider:_dataFor(...) Get the data table for the given target.
provider:_startMenu(...) Start showing a menu for the given target.
provider:_finishMenu(...) Finish showing a menu for the given target.
provider:_addButton(button, order, act, ...) Add a button to the menu for the given target.
provider:_addInfo(info, order, ...) Add an info entry to the menu for the given target.
provider:_shouldShow(item, ...) Return whether the given item should show for the given target.
provider:_onReset(...) Called whenever the menu state is reset.
provider:_onPush(...) Called whenever the user enters a sub-menu.
provider:_onPop(...) Called whenever the user exits a sub-menu.


MenuSet

MenuSet()
Create a new MenuSet, which can be used like a menu list but has an add method for ease of use.
menuSet:add(entry)
Add an entry to this MenuSet.

Parameters:

  • entry The entry to add.

ActionBase

ActionBase(provider)
Create a new ActionBase-derived type, using the given provider implementation.

Parameters:

  • provider The provider to use for this instance.

Returns:

    A constructor function for the new type.
actionBase:add(entry)
Add a top-level entry to this Menu

Parameters:

  • entry The entry to add.
actionBase:setMenu(menu, ...)
Set the current menu to menu for the provided target.

Parameters:

  • menu The menu to set.
  • ... The target to set the menu for.
actionBase:refreshMenu(...)
Refresh the currently-displayed menu for the provided target.

Parameters:

  • ... The target to refresh the menu for.

Provider

This is the interface that specific implementations must provide to ActionBase as provider.
provider:_dataFor(...)
Get the data table for the given target.

Parameters:

  • ... The target to get data for.

Returns:

    A unique table corresponding to the given set of target parameters.
provider:_startMenu(...)
Start showing a menu for the given target.

Parameters:

  • ... The target to start showing a menu for.
provider:_finishMenu(...)
Finish showing a menu for the given target.

Parameters:

  • ... The target to finish showing a menu for.
provider:_addButton(button, order, act, ...)
Add a button to the menu for the given target.

Parameters:

  • button The name of the button.
  • order The ordering of the button.
  • act A callback to call when the button is clicked.
  • ... The target to add a button for.
provider:_addInfo(info, order, ...)
Add an info entry to the menu for the given target.

Parameters:

  • info The text of the info entry.
  • order The ordering of the info entry.
  • ... The target to add an info entry for.
provider:_shouldShow(item, ...)
Return whether the given item should show for the given target.
This method is optional. If not provided, defaults to showing all items.

Parameters:

  • item The item to check, in standard action format.
  • ... The target to check.

Returns:

    Whether the item should show.
provider:_onReset(...)
Called whenever the menu state is reset. This happens when the user returns to the top-level menu, or by an explicit setMenu call.
This method is optional.

Parameters:

  • ... The target of the menu.
provider:_onPush(...)
Called whenever the user enters a sub-menu.
This method is optional.

Parameters:

  • ... The target of the menu.
provider:_onPop(...)
Called whenever the user exits a sub-menu.
This method is optional.

Parameters:

  • ... The target of the menu.
generated by LDoc 1.5.0