'\"macro stdmacro
.if n .pH g1.ckitem @(#)ckitem	40.15 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} ckitem 1 "Essential Utilities" "\&"
.if \nX=1 .ds x} ckitem 1 "Essential Utilities"
.if \nX=2 .ds x} ckitem 1 "Essential Utilities" "\&"
.if \nX=3 .ds x} ckitem "Essential Utilities" "" "\&"
.TH \*(x}
.SH NAME
\f4ckitem\f1 \- build a menu; prompt for and return a menu item
.SH SYNOPSIS
\f4ckitem\f1 [\f4\-Q\f1] [\f4\-W\f2 width\f1] [\f4\-uno\f1] [\f4\-f\f2 file\f1] [\f4\-l \f2label\f1]
[[\f4\-i \f2invis\f1] [, ...]] [\f4\-m \f2max\f1]
.br
[\f4\-d\f2 default\f1]
[\f4\-h\f2 help\f1] [\f4\-e\f2 error\f1] [\f4\-p \f2prompt\f1]
[\f4\-k\f2 pid\f1 [\f4\-s\f2 signal\f1]] [\f2choice\f1 [...]]
.sp
\f4erritem\f1 [\f4\-W\f1] [\f4\-e \f2error\f1] [\f2choice \f1[...]]
.br
\f4helpint\f1 [\f4\-W\f1] [\f4\-h \f2help\fP] [\f2choice \f1[...]]
.SH DESCRIPTION
\f4ckitem\f1 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 will be a menu item, text for help and
error messages, and a default value
(which will be returned if the user responds with a carriage return).
.P
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.
.P
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 \f4\-W\f1 option cancels the automatic formatting.
When a tilde is placed at the beginning or end of a message definition,
the default text will be
inserted at that point, allowing both custom text and the default text
to be displayed.
.P
If the prompt, help or error message is not defined, the default message
(as defined under NOTES) will be displayed.
.P
Two visual tool modules are linked to the \f4ckitem\f1 command.
They are
\%\f4erritem\f1 (which formats and displays an error message) and
\f4helpitem\f1 (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 \f2choice\f1 is defined in these modules,
the messages will describe the
available menu choice (or choices).
.P
The options and arguments for this command are:
.TP
\f4\-Q\f1
Specifies that quit will not be allowed as a valid response.
.TP
\f4\-W\f1
Specifies that prompt, help and error messages will be formatted to a
line length of \f2width\f1.
.TP
\f4\-u\f1
Specifies that menu items should be displayed as an unnumbered list.
.TP
\f4\-n\f1
Specifies that menu items should not be displayed in alphabetical order.
.TP
\f4\-o\f1
Specifies that only one menu token will be returned.
.TP
\f4\-f\f1
Defines a file, \f2file\f1. which contains a
list of menu items to be displayed.
[The format of this file is: \f4token<tab>description\f1.
Lines beginning with a pound sign (\#) are designated as comments and
ignored.]
.TP
\f4\-l\f1
Defines a label, \f2label\f1, to print above the menu.
.TP
\f4\-i\f1
Defines invisible menu choices (those which will not be printed in the menu).
(For example,
"all" used as an invisible choice would mean it is a legal 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.
.TP
\f4\-m\f1
Defines the maximum number of menu choices allowed.
.TP
\f4\-d\f1
Defines the default value as \f2default\f1.
The default is not validated and so does not have to meet any criteria.
.TP
\f4\-h\f1
Defines the help messages as \f2help\fP.
.TP
\f4\-e\f1
Defines the error message as \f2error\f1.
.TP
\f4\-p\f1
Defines the prompt message as \f2prompt\f1.
.TP
\f4\-k\f1
Specifies that the process ID \f2pid\f1 is to
be sent a signal if the user chooses
to abort.
.TP
\f4\-s\f1
Specifies that process ID \f2pid\f1 defined with the \f4\-k\f1 option is to be
sent signal \f4signal\fP when quit is chosen.
If no signal is specified, SIGTERM is used.
.TP
.I choice
Defines menu items.
Items should be separated by white space or newline.
.PD
.SH SEE ALSO
.nf
\f4allocmenu\fP(3X)
\f4printmenu\fP(3X)
\f4setinvis\fP(3X)
\f4setitems\fP(3X)
.F
.SH EXIT CODES
.nf
\f40\f1 = Successful execution
\f41\f1 = EOF on input
\f42\f1 = Usage error
\f43\f1 = User termination (quit)
\f44\f1 = No choices from which to choose
.fi
.SH 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.
.P
When menu entries are defined both in a file (by using the \f4\-f\f1 option)
and also on the command line, they are usually combined alphabetically.
However, if the \f\-n\f1 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.
.P
The default prompt for \f4ckitem\f1 is:
.sp
.in +.25i
\f4Enter selection [?,??,q]:\f1
.in -.25i
.sp
One question mark will give a help message and then redisplay the prompt.
Two question marks will give a help
message and then redisplay the menu label, the
menu and the prompt.
.P
The default error message is:
.sp
.in +.25i
\f4ERROR - Does not match an available menu selection.
.br
Enter one of the following:
.br
\(em the number of the menu item you wish to select
.br
\(em the token associated withe the menu item,
.br
\(em partial string which uniquely identifies the token for the menu item
.br
\(em ?? to reprint the menu
.in -.25i
.sp
The default help message is:
.sp
.in +.25i
\f4Enter one of the following:
.br
\(em the number of the menu item you wish to select
.br
\(em the token associated with the menu item,
.br
\(em partial string which uniquely identifies the token for the menu item
.br
\(em ?? to reprint the menu
.in -.25i
.P
When the quit option is chosen (and allowed), \f4q\f1 is
returned along with the return code \f43\f1.
.\"	@(#)ckitem.1	5.2 of 6/16/87
