ckitem(1) 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] . . .] [-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 NOTICES) 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:
Copyright 1994 Novell, Inc. Page 1
ckitem(1) ckitem(1)
-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.
-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.
Copyright 1994 Novell, Inc. Page 2
ckitem(1) ckitem(1)
choice
Defines menu items. Items should be separated by white
space or newline. Menu items with descriptions are
enclosed in quotation marks where the first word is the
actual item, followed by a TAB, and the remaining words
are used as the description. The command:
ckitem "choice1 the first choice" choice2
returns:
1 choice1 the first choice
2 choice2
Enter selection [?,??,q]:
EXIT CODES
0 = Successful execution
1 = EOF on input
1 = Usage error
3 = User termination (quit)
4 = No choices from which to choose
NOTICES
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 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: Entry does not match available menu selection.
Enter the number of the menu item you wish to select,
or the token which is associated with the menu item, or
Copyright 1994 Novell, Inc. Page 3
ckitem(1) ckitem(1)
a partial string which uniquely identifies the token
for the menu item. Enter ?? to reprint the menu.
The default help message is:
Enter the number of the menu item you wish to select,
or the token which is associated with the menu item, or
a partial string which uniquely identifies the token for
the menu item. Enter ?? to reprint the menu.
When the quit option is chosen (and allowed), q is returned
along with the return code 3.
Copyright 1994 Novell, Inc. Page 4