ckitem(1) UNIX System V(Essential Utilities) ckitem(1)
NAME
ckitem - build a menu; prompt for and return a menu item
SYNOPSIS
ckitem [ -Q ] [ -W width ] [ -uno ] [ -f file ] [ -l label ]
[ [ -i invis ] [ -i invis ] . . . ] [ -m max ] [ -d default ] [ -h
help ] [ -e error ]
[ -p prompt ] [ -k pid [ -s signal ] ] [ choice1 choice2 . . . ]
erritem [ -W width ] [ -e error ] [ choice1 choice2 . . . ]
helpitem [-W width] [-h help] [ choice1 choice2 . . . ]
DESCRIPTION
ckitem builds a menu and prompts the user to choose one item from a menu
of items. It then verifies the response. Options for this command
define, among other things, a prompt message whose response is a menu
item, text for help and error messages, and a default value (which is
returned if the user responds with a RETURN).
By default, the menu is formatted so that each item is prepended by a
number and is printed in columns across the terminal. Column length is
determined by the longest choice. Items are alphabetized.
All messages are limited in length to 70 characters and are formatted
automatically. Any white space used in the definition (including
newline) is stripped. The -W option cancels the automatic formatting.
When a tilde is placed at the beginning or end of a message definition,
the default text is inserted at that point, allowing both custom text and
the default text to be displayed.
If the prompt, help or error message is not defined, the default message
(as defined under NOTES) is displayed.
Two visual tool modules are linked to the ckitem command. They are
erritem (which formats and displays an error message) and helpitem (which
formats and displays a help message). These modules should be used in
conjunction with FML objects. In this instance, the FML object defines
the prompt. When choice is defined in these modules, the messages
describe the available menu choice (or choices).
The options and arguments for this command are:
-Q Do not allow quit as a valid response.
-W Use width as the line length for prompt, help, and error messages.
-u Display menu items as an unnumbered list.
-n Do not display menu items in alphabetical order.
10/89 Page 1
ckitem(1) UNIX System V(Essential Utilities) ckitem(1)
-o Return only one menu token.
-f file contains a list of menu items to be displayed. [The format of
this file is: token<tab>description. Lines beginning with a pound
sign (``#'') are comments and are ignored.]
-l Print label above the menu.
-i invis specifies invisible menu choices (choices not to be printed
in the menu). For example, ``all'' used as an invisible choice
would mean it is a valid option but does not appear in the menu.
Any number of invisible choices may be defined. Invisible choices
should be made known to a user either in the prompt or in a help
message.
-m The maximum number of menu choices allowed is m.
-d The default value is default. The default is not validated and so
does not have to meet any criteria.
-h The help message is help.
-e The error message is error.
-p The prompt message is prompt.
-k Send process ID pid a signal if the user chooses to abort.
-s When quit is chosen, send signal to the process whose pid is
specified by the -k option. If no signal is specified, use
SIGTERM.
choice
Defines menu items. Items should be separated by white space or
newline.
EXIT CODES
0 = Successful execution
1 = EOF on input
2 = Usage error
3 = User termination (quit)
4 = No choices from which to choose
NOTES
The user may input the number of the menu item if choices are numbered or
as much of the string required for a unique identification of the item.
Long menus are paged with 10 items per page.
When menu entries are defined both in a file (by using the -f option) and
also on the command line, they are usually combined alphabetically.
However, if the -n option is used to suppress alphabetical ordering, then
the entries defined in the file are shown first, followed by the options
Page 2 10/89
ckitem(1) UNIX System V(Essential Utilities) ckitem(1)
defined on the command line.
The default prompt for ckitem is:
Enter selection [?,??,q]:
One question mark gives a help message and then redisplays the prompt.
Two question marks gives a help message and then redisplays the menu
label, the menu and the prompt.
The default error message is:
ERROR - Does not match an available menu selection.
Enter one of the following:
- the number of the menu item you wish to select
- the token associated withe the menu item,
- partial string which uniquely identifies the token
for the menu item
- ?? to reprint the menu
The default help message is:
Enter one of the following:
- the number of the menu item you wish to select
- the token associated with the menu item,
- partial string which uniquely identifies the token
for the menu item
- ?? to reprint the menu
When the quit option is chosen (and allowed), q is returned along with
the return code 3.
10/89 Page 3