GRID CARTOGRAPHER 4
Shortcuts

UITextMenu

2019-04-12

This helper class adds support for a text-based menu system.

Requirements

Header | uikit/textmenu.nut

Methods

Constructor

var menu = UITextMenu();

Create an instance of the UITextMenu class. During construction the number of display columns will be stored, so make sure to set the correct display mode prior to calling.

Menus

menu.Menus: array

The menu class has a public array member variable called Menus which holds the structure of the menu system. The array is expected to hold table objects with the following slots:

Key Value
name:string The display name of the menu. Use the & prefix on one character to specify the shortcut key for keyboard mode.
right:bool This optional flag allows the last menu to be right-aligned on the menu bar. Note that only last item in the Menus array can have this flag set.
options:array An array of options for the menu. Note that nested sub-menus are not supported.

The options array should contain a list of tables with the following slots:

Key Value
name:string The display name of the menu option. Use the & prefix on one character to specify the shortcut key for keyboard navigation mode.
shortcut:string Optional shortcut text to be display right-aligned on the menu. Note the user code is responsible for processing shortcuts, this is a display feature only.
div:bool This optional flag changes the menu option into a separating line in the menu. Use this to group related menu options. When this mode is used, all other fields in the option table are ignored.
enabled:bool This optional field allows for menu options to be disabled. Disabled options will not register as a selection.
checked:bool This optional field, when set true, will draw a check-mark next to the option.

Note that other user-defined fields may be added to the option to assist with decoding selected options by assigning a unique identifier.

Update

menu.Update(): bool

This is the primary function that handles running the menu system. It returns true if the menu is open or in keyboard navigation mode or a selection is available.

It is recommended that the Update

Selection

menu.Selection(): table|null

Acquires the last menu selection, or null if no selection has been made. Note that after a selection has been reported, the internal value is cleared and subsequent calls to this function will return null until a new selection is made.

The selection table contains the following slots:

Key Value
menu:int The index of the selected menu in the Menus array.
index:int The index in the menu options array (dividers are included).
option:table A reference to the array element in the menu that was selected (for easy access to any additional user-data.)

IsOpen

menu.IsOpen(): bool

Returns true if the menu is open, or in keyboard navigation mode. Input based application processing should be suspended while the menu is open.

Refresh

menu.Refresh(): bool

Forces the menu to redraw itself.