DESCRIPTION

The spec_menu() function creates interactive menus that might be used for configuring macros and other spec options. When the menu is active, the user can use arrow and control keys to navigate the options and edit strings.

While waiting for input in spec_menu(), spec will continue to poll hardware and respond to client commands if in server mode, just as spec does while waiting for input at the main command prompt.

USAGE

spec_menu(menu [, modes [, dumbterm]])

The menu argument is a two-dimensional associative array that completely describes the menu as detailed below. The first index of the array is a number that identifies an item. The second index of the array is a string that matches one of a set of keys that identify an attribute for the item. The value of the array element depends on the key.

The optional modes argument is a single value where each bit can be associated with a menu item. Up to 52 items may have associated bits.

If the number of menu items plus the number of lines needed to display the hints and "info" strings is greater than the number of rows in the terminal window, the menu items will be scrollable. The number of additional lines above or below the visible window will be displayed in the left of the screen. Navigating past the top or bottom will automatically scroll the menu.

If the width of the menu is greater than the width of the window, the menu items will be compressed or scrolled horizontally, to fit the available space.

If dumbterm is nonzero, spec_menu() will not use cursor positioning. Instead, the menu options will be displayed one at a time in sequence and the user will be prompted for a value. In this mode, entering a single - for any response will jump back and prompt again for the previous item in the sequence.

The function will return a possibly modified value for modes, reflecting the user's choices. If the menu is exited with ^C or the x command, the values of the menu items on entry are restored.

MENU KEYS

Each item selected by the first index into the menu[][] array can have various attributes configured via the following string keys placed in the second array index.

The "title", "head" and "subhead" items don't have any other modifiers. All other items require at least a "desc" key. An item with a "desc" key also needs at least one of "bit", "value", "svalue", "@" or "list". The other keys are optional.

"title"

The title for the menu. No further attributes apply to a "title" item. Only one title will be displayed, and it will be displayed at the top of the page.

"width"

The width of the menu. If not specified, the entire window will be used.

"head"

A section header for the menu. It will be preceded by a blank line.

"subhead"

A subsection header for the menu. It will not be preceded by a blank line.

"desc"

A required descriptive text string for each item. The string is displayed when prompting for the value. A null description creates a blank line.

"info"

Optional text that gives a description of the parameter. The "info" text is displayed only when the current item is active. The text will be formatted for width using the rules of the tty_fmt() function. Formatting will work best if there are no embedded newlines in the string.

The value of a menu item is modifiable if at least one of the following five keys is included in the item description.

"bit"

Associates a bit in the modes argument to this item. The element value should be a single bit and each item in the array that has a bit set should have a unique value. The associated bit will be set or cleared in the return value of spec_menu(). Also, a "bit" attribute can be associated with items that have a "value", "svalue", "toggle" or "list" attribute so that such items can be enabled or disabled for editing using the "bit_and", "bit_or" and "bit_not" attributes.

Currently, bits 0 through 51 can be used.

"toggle"

Similar to the "bit" key in that the value can be toggled on or off, but there is no limit to the number of such items and no connection to the modes argument. The item's value contains the initial state on entry and the selected state when spec_menu() returns.

"choices"

For "bit" and "toggle" items, provides prompt strings to replace the default YES and NO. The choices are provided in one colon-delimited string, for example, "ENABLE:DISABLE" or "ON:OFF". The choices don't need to be capitalized and can include spaces. The first choice is associated with the value of one and the second with zero.

"value"

Indicates a number value is wanted. Also used to hold the "list" item selection. This item's value will be modified. Not used if the "@" indirection key is present.

Note, the number value can be entered as an expression which will be evaluated with the result displayed.

"svalue"

Indicates a string value is wanted. Can also be used to select the current "list" item. This item's value will be modified. Not used if the "@" indirection key is present.

"list"

Presents a list of possible values, only one of which can be selected. The selection is set and returned in "value", "svalue" or indirectly via the "@" key. Use "value" to indicate selection based on position in the list, counting from one. Use "svalue" to indicate selection based on a matching strings. If "@" is used, spec will use a number or string as appropriate.

By default, one or more space characters separate the list items. An alternate delimiter character or string can be specified using the "delim" attribute.

"@"

The value of this element contains the string name of a spec variable that is to be modified. If its current value is a number, then the rules for entering number values will be followed. If its current value is a string or the parameter is unset, the string rules will be followed. This key takes precedence over "value" or "svalue" attributes. Names of scalars and associative array elements are allowed, but data array elements are not. If the named variable doesn't exist, spec_menu() will display the variable name and "not found" as the value.

"format"

Can be used to set an alternative printf() format for display of a number-valued item. For example, "0x%X" can be used to display a value in hexadecimal. In fact, the format can be used to specify the same number value in multiple formats, such as "hex=0x%x dec=%d". The default format is "%.9g".

"delim"

Provides an alternative delimiter for "list" items. Can be one or more characters. The default delimiter is a space character. When the delimiter is a space character, multiple space and tab characters count as one delimiter. When the delimiter is any other character or string, each instance is a delimiter.

"default"

For "list" items, sets the default choice if the value passed via "value", "svalue" or "@" is invalid or out of range.

"min"

For "value" items, a minimum value to allow.

"max"

For "value" items, a maximum value to allow.

The item types "bit", "value", "svalue", "toggle" and "list" can have the following attributes set to enable or disable the item for editing based on the bit values of other items in the current value of modes.

"bit_and"

Editable if all the matching bits (or bit) are set in modes.

"bit_or"

Editable if any of the matching bits (or bit) are set in modes.

"bit_not"

Editable if the matching bits (or bit) are not set in modes.

Finally, this key applies to bit-toggle items:

"bit_flip"

Flip the YES/NO sense of this item. Normally, when a bit is set in modes, the value is presented as "YES". If "bit_flip" is present, the logic is reversed. This option can be used to avoid double negatives in the query/response, particularly when one doesn't have the freedom to define what a set bit means. For example, "Draw error bars (YES)?" is preferable to "Don't draw error bars (NO)".

RETURN VALUES

On a normal return with the q or ^D keys, spec_menu() will return an updated value for modes that reflects the new values of all the "bit" items. In addition, new values for "value", "svalue" and variables passed indirectly using "@" will be assigned. Finally, for any items that have been modified an element will be added to the menu array with a second index named "updated" and a value set to one.

NAVIGATION AND EDITING

The menu is presented as a list with the cursor positioned at the current value for a modifiable item. The up- and down-arrow keys, the ^P (previous) and ^N (next) control keys and the return key accept the current choice and move up or down the list.

One exits the menu saving the modifications using the q (quit) key or ^D. One can abandon the menu without saving the modifications using the x (exit) key or ^C.

The display is refreshed with ^L, taking into account the current window size.

Bit-value and toggle items are toggled using the space bar or the left- or right-arrow keys. In addition, the y, Y and 1 keys select YES, while the n, N and 0 keys select NO.

List items are also navigated using the left- and right-arrow keys and the ^B (back) and ^F (forward) to move one position. The ^A and ^E keys move to the first item and last item, respectively. Also, typing the first character of a list item will move the cursor to the first item in the list that begins with that character. The space bar makes the currently highlighted item the list selection.

Text entry items (both string- and number-valued) allow insertion and deletion of text from any point in the string. The left- and right-arrow keys and the ^B (back) and ^F (forward) move one position. The ^A and ^E keys move the cursor to the start and end of the entry, respectively. The ^D key and the keyboard forward-delete key both delete forward. The backspace and delete key delete backward. The ^U and ^K keys delete from the current position to the beginning and end of line, respectively.

For number-valued items, the text entered will be evaluated. Thus, expressions are allowed. For example, PI/2, 2 + 2 or pow(2,12) are all valid entries. Only commands and functions that make sense in the context of generating an expression are allowed. Other commands will not be executed and will generate an error message that will be displayed near the bottom of the menu window. Among the commands not allowed are those that generate screen output or control hardware.

To enter a string that starts with one of the navigation command letters, namely q or x, use one of the text-editing keys, such as left- or right-arrow to switch to text-entry mode.

When items are disabled by way of the "bit_and", "bit_or" and "bit_not" logic, the values appear as ---, and the up/down navigation passes over those items.

EXAMPLES

The standard spec macros setplot, setshow, mstartup and plotselect all use the spec_menu() function. Here is another example:

 def menu1 '{
     local i, menu[], modes
     local   group_size

     modes = 1
     group_size = 512
     menu[++i]["title"] = "Menu Example"
     menu[++i]["desc"] = "Enable List Examples"
     menu[  i]["bit"] = 0x0001

     menu[++i]["desc"] = "  List Example 1"
     menu[  i]["bit_and"] = 0x0001
     menu[  i]["list"] = "Now is the time for all good men"
     menu[  i]["svalue"] = "time"

     menu[++i]["desc"] = "  List Example 2"
     menu[  i]["bit_and"] = 0x0001
     menu[  i]["list"] = "The quick::brown fox::jumps over::the lazy dog"
     menu[  i]["delim"] = "::"
     menu[  i]["value"] = 3

     menu[++i]["desc"] = "  List Example 3"
     menu[  i]["bit_and"] = 0x0001
     menu[  i]["list"] = "128 256 512 1024 2048 4096 8192"
     menu[  i]["@"] = "group_size"

     menu[++i]["desc"] = ""
     menu[++i]["desc"] = "Use logarithmic y-axis"
     menu[  i]["bit"]     = PL_YLOG
     menu[++i]["desc"] = "Force y-axis minimum to zero"
     menu[  i]["bit"]     = PL_YZERO
     menu[  i]["bit_not"] = PL_YLOG

     modes = spec_menu(menu, modes)

     print modes, group_size
}'