DESCRIPTION

The spec_menu() function creates interactive menus that can 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 the window is resized while within spec_menu(), the ^L command will redraw the window using the new size.

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. In addition, menu array elements associated with certain items will contain possibly modified values. See RETURN VALUES below. 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", "width", "head", "subhead" and "text" 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", "@", "family", "list" or "alist". 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 maximum width of the menu. If not specified, the entire window will be used. If the window is narrower than the specified width, the window width will be used.

"head"

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

"subhead"

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

"text"

A text block will be inserted into the menu. 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. (As of spec release 6.08.09.)

"desc"

A required descriptive text string for each item (other than for "title", "width" "head" "subhead" and "text"). The string is displayed when prompting for the value. A null description creates a blank line.

For items associated with a "family", the sibling ID will be inserted in parenthesis at the end of the descriptive text. If the text string ends with a "?", ":", ".", "=" or "-", the sibling ID will be inserted before that character. If there is a space before the character, the space will also be included after the ID.

"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.

"family"

Either a string containing a list of sibling IDs, a value specifying the number of siblings or the name of an "alist" associative array already defined. A family item allows multiple parameters of the same type to be set on one line of the menu. Members of this family are assigned by having their "parent" attribute (described next) specify the family item number to which its associated parameter belongs.

When given a string argument, the string contains a space-delimited list of identifiers. The number of such identifiers determines the number of siblings for each subsequent item that has this parent. That number cannot be changed while in a call of spec_menu(). No spaces are allowed within the identifiers. The menu will display the "desc" text followed by the list, with the active sibling highlighted.

If given a number value, that value sets the number of siblings for subsequent items that have this parameter. The value can be changed while in spec_menu(). Siblings are numbered starting from zero.

If "family" is set to the name of an "alist" associative array (described below) that has already appeared, the array indices will be potential sibling IDS, but only those array elements selected will be used as sibling IDS. The selection can be changed while in spec_menu().

"parent"

Contains the index of the associated "family" (the parent) for this child entry. The "value", "svalue", "list" "bit" and "toggle" attributes can be used with "parent". The "alist" item cannot be used.

The values for each sibling in the family are passed in an associative array, assigned using the "@" key or for strictly number or strings types, assigned with the "value" or "svalue" key.

If the "family" attribute is a string of identifiers, those identifiers can be used to index the array. Otherwise, the array must be indexed using consecutive integers, starting with zero. The array elements can be numbers or strings. If any element is not a number, all elements will be treated as strings.

The menu will include the identifier of the active child at the end of the "desc" text using the string name ID if the "family" was selected with a list or a pointer to an "alist" array. Otherwise, the sibling index number is used.

A tag containing the family index number or ID enclosed in parenthesis and prepended with a space will be added to the end of the item description from "desc". If the description ends with a character in the set ".?:=-", the tag will be inserted before the final character. If the "prefix" key is set for this item, the prefix string will be included in the tag.

The "parent" and "family" index can be the same item, in which case, the current ID or sibling number will be displayed in the description. There won't be a separate line on the menu showing the list of IDs for the family.

The spec_menu() code will attempt to determine whether values are number or string type, based on current values in the associative array passed with "@". If there are no current values, the "format" key can be included with the item to force a number or string type, based on the format type. If the format type cannot be determined, values will be considered strings.

Items with a parent do not look at or affect the bits set in the modes argument to spec_menu(). Each family maintains a private set of bits, which can be used to enable or disable other items in the same family as described below.

The value of a menu item is modifiable if at least one of the following six 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.

"value"

Indicates a number value is wanted. Also used to hold the "list" item selection. This item's value will be modified and can be accessed from the menu argument array when spec_menu() returns. Not used if the "@" indirection key is present.

Note, a number value can be typed into the spec_menu() screen as an expression that will be immediately 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 and can be accessed from the menu argument array when spec_menu() returns. 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 string. 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 selected item will be shown enclosed in square brackets []. Alternative brackets can be specified using the "bracket" attribute.

"alist"

Presents a list of possible values, any number of which can be selected. The menu array item is a string containing the name of a one- or two-dimensional associative array. For a 1D array, the value names will be the array indices, and the list will be sorted by those names. For a 2D array, the value names will be the second index of each element, and the list will be sorted by the first element. For either case, the value of each element is zero or nonzero to indicate whether the item has been selected. The array is modified on return to reflect any changes to the selections. The "@" key cannot be used to pass the name of the array.

Selected items will be shown enclosed in square brackets []. Alternate brackets can be specified using the "bracket" attribute.

The following keys modify the above keys.

"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. As of spec release 6.08.07, there can be more than two choices for "toggle" items.

"@"

The value of this element contains the string name of a spec variable that is to be modified. When used with a "parent" entry, the value is a string name of an associative array with each element associated with one sibling of the family. If the current value of the variable or each element of the array is a number, then the rules for entering number values will be followed. If the 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. For "bit" attributes, can be used to return the value of the associated bit, but the modes argument is still used to initialize the setting (as of spec release 6.07.08).

If the named variable exists, but is unset so is of unknown type, The "value" and "svalue" keys can be used to set the type even though the value will be unused. Also, the "format" key can be used to force a string or number type, where a "%s" format will indicate a string, while every other allowed "%" format will indicate a number.

"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.

"bracket"

Sets an alternative bracket character for "list" and "alist" items. Only the first character of the string passed as a value is examined. If it is any of [, ], {, }, (, ), < or >, spec will assign the appropriate pair as left and right characters. Any other printing character will be used as both the left and right bracket character.

"default"

For "list" items, sets the default choice if the value passed via "value", "svalue" or "@" is invalid or out of range. For new siblings created in families where the number of siblings is editable, sets the default number or string value for the sibling parameter.

"min"

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

"max"

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

"prefix"

For "parent" items, contains a prefix to be displayed in the appended parenthetical description tag prior to the family ID.

"check_macro"

For "value" and "svalue" items, the name of a macro function that will be called when the user enters a value. The purpose of the macro function is to validate the user input, which is passed to it via the function argument. Use the eprint or eprintf() built-in commands to indicate an invalid value. The string formatted by the eprint or eprintf() will be displayed as an error in spec_menu(). If there is an error indicated, the value entered by the user will be cleared. Also, any errors generated within spec by code in the macro will invalidate the user input and the spec generated error will be displayed in the menu. (Preliminary version in spec release 6.10.1.)

The item types "bit", "value", "svalue", "toggle", "list" and "alist" 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)".

TEXT FORMATTING

The strings for the "title", "head", "subhead", "desc", "text" and "info" attributes can include instances of the special sequence "\[xx]" where xx is one of the following:

"so" start text stand-out mode.

"se" end text stand-out mode.

"md" start bold (intensified) mode.

"me" end bold mode.

"us" start underline mode.

"ue" end underline mode.

"mb" start blink mode (if you want to annoy).

"mh" start half-bright mode.

"mr" start reverse video mode.

The "se" sequence turns off all modes and is the only way to turn off blink, half bright and reverse video. Half-bright mode is unlikely to be effective on xterm-like windows. The bold, half-bright, reverse, underline and blink modes can be combined. Only bold and underline can be selectively disabled.

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. Elements for "alist" arrays will be changed to reflect which have been toggled on or off. 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, along with the ^P (previous) and ^N (next) control keys move up or down the list. The return key accept the current choice and moves down to the next item.

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. The ^G command moves the cursor to the top of the menu (as of spec release 6.08.08).

Bit-value and toggle items are toggled using the space bar or the left- or right-arrow keys. For bit-value items and toggle items with only two choices, 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.

For "alist", the command ^R will select all items, ^U will deselect items from the first to the current and ^K will deselect items after the current to the last.

For "family" and "parent" items, the <tab>, ^[ and ^] keys enter a modified value and cycle to the next (previous for ^[) sibling.

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.

COMMAND SUMMARY

EXAMPLES

The standard spec macros setplot, setshow, mstartup, fly_setup 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]["width"] = 90
     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

     menu[++i]["desc"] = "Enter a random value:"
     menu[  i]["value"] = rand()

     modes = spec_menu(menu, modes)

     print modes, group_size, menu[i]["value"]
}'

Here is an example using the various ways to describe a family:

def menu2 '{
     local i, parent, modes, menu[], fam_num
     local   home_dirs[], par_val[], par2_val[]

     menu[++i]["desc"] = "Choose family members by ID:"
     menu[  i]["family"] = "tth th chi phi"
     parent = i

     menu[++i]["desc"] = " Configure motor home direction:"
     menu[  i]["parent"] = parent
     menu[  i]["value"] = "home_dirs"
     menu[  i]["toggle"] = 1
     menu[  i]["choices"] = "cw:ccw"

     menu[++i]["desc"] = "Choose family members by count:"
     menu[  i]["family"] = fam_num
     parent = i

     menu[++i]["desc"] = " Value for parameter?"
     menu[  i]["parent"] = parent
     menu[  i]["value"] = "par_val"

     local   fam_array[] = [ 0:"zzz":0, 1:"yyy":1, 2:"xxx":0, 3:"vvv":1, 4:"uuu":0 ]
     menu[++i]["desc"] = "Choose allowed siblings for family:"
     menu[  i]["alist"] = "fam_array"

     menu[++i]["desc"] = "Choose family member by \"alist\":"
     menu[  i]["family"] = "fam_array"
     parent = i

     menu[++i]["desc"] = " Values for sibling?"
     menu[  i]["parent"] = parent
     menu[  i]["value"] = "par2_val"

     spec_menu(menu, modes)

     print fam_array, home_dirs, par_val, par2_val
}'