view release on metacpan or  search on metacpan

doc/Cmenu.tex  view on Meta::CPAN

\begin{center}
\$sel = \&menu\_display(``User prompt'',start\_item);
\end{center} 

\begin{description} 
\item [\$sel] This will contain user responses; it will always be terminated by separator character so chop it off with
\begin{center}
chop(\$sel);
\end{center}
Generally this return value will contain a list of values which need further processing (see below).
\item [User prompt] (mandatory) a string which will be displayed at the foot of the screen
\item [start\_item] (optional) which menu option should be highlighted at the start. This allows your script to keep track of where it was in a menu. If it is not provided, the first item in a menu will be highlighted.
\end{description}

\subsubsection{Processing return Values}

To help distinguish different data elements returned from the menu, two variables are used
\begin{description}
\item [\$Cmenu::menu\_sep] (this can be accessed and even set by user scripts) it separates individual item responses. This is most appropriate to check lists and data fields. 

\item [\$Cmenu::menu\_sepn] (this can be accessed and even set by user scripts). It defaults to the tilde (\textbf{~}) character. It is used to separate elements with a data field value.
\end{description}

Simple menu options will only return a single value indicating either a function key pressed or an item selected. For such menus doing \textbf{chop(\$sel)} will be enough to pick out the return value. Possible values might be

\begin{description}
\item [``\%EMPTY\%''] the \textit{EXIT} function has been selected. This is usually taken to mean an immediate exit from all menus or an abort from an editing spree.
\item [``\%UP\%''] the \textit{QUIT} function has been selected. This is usually taken to mean a menu sequence has been terminated, perhaps an editing session accepted or the user wishes to back-track through some menus.
\item [``YES''] given from \textbf{menu\_show} only - indicates a positive response from a confirmation screen
\item [``NO''] given by \textbf{menu\_show} only - indicates a negative response from a confirmation screen
\item [variable text field] a menu selection has been made by text-label (see menu\_item)
\item [variable number] a menu selection has been made by value (see menu\_item)
\item [variable array] a complex menu response has been completed; this needs further processing
\end{description}

\subsection{Complex Return Values}
Dealing with complex return values occur when menu items including radio lists, check lists and editing data fields. Essentially these type of items create multi-value responses. To do this, Cmenu returns an array of values separated by separation ch...
\begin{center}
@values = split(/\$Cmenu::menu\_sep/,\$sel)
\end{center}
will perform the first split. The array of values will contain the function key or menu item pressed when the menu was exited. Other values will correspond to specific menu items. For radio and check list, this will be a simple list of which items ha...

To deal with data fields, a field identifier and the field contents will be returned as a data pair. These can be separated with the following command;
\begin{center}
(\$identifier,\$contents) = split(\$Cmenu::menu\_sepn/,\$value[1]);
\end{center}
Notice that \$value[1] is one of the elements of the first array. Normally, values returned in this way will be ordered as they were defined with menu\_item calls but this is not guaranteed. The \$identifier is the value specified in the original \$m...

Where this return value can get really messy is when a complex data entry menu has a combination of regular, alpha, numeric, radio and check list menu items. You will need to take care that you identify all the parts you need for each item. When in d...
\begin{center}
\&menu\_show(``Data Response'',\$sel,''HELP'');
\end{center}
This will show what Cmenu is returning from a particular call.

\subsection{menu\_popup}
This is an extra routine which you may never need. It provides a way of displaying information while a process is being performed rather than the script stalling silently. It is called in two forms; first to display the popup and then to remove it;
\begin{description}
\item [menu\_popup(\$header,\$message)] This creates a popup which overlays the current menu. A very small window is opened with a drawn border and \textbf{\$header} displayed in the centre of the top line. The \textbf{\$message} is displayed in the ...

After calling this, your script should go off and busy itself until ready to talk to the user again
\item [menu\_popup()] call the same routine with no parameters and the Popup menu will be removed.
\end{description}
Please remember to close the popup as dangling windows can trash your display.

\subsection{menu\_show(\$title,\$message,\$style)} 
This provides for splash screens to be shown to the user either reporting difficulties, errors, providing help or asking for confirmation of responses. The routine draws a full window covering the normal menu space (not the backdrop). It accepts thre...
\begin{description}
\item [\$title] Gives the window a title included in the border
\item [\$message] provides the actual text message. If this can be fitted onto a single line, it will be centred in the screen. If the text exceeds a single line width, it will be passed through \textbf{Text::Wrap} for formating. \textbf{Text::Wrap} ...
\item [\$style] using different colours, a different meaning can be associated with splash screens. Also a simple button bar will be drawn for each type so that users can confirm or reject options as required. Responses from menu\_show will be either...
\begin{description}
\item [``HELP''] uses the help colour scheme (brown on grey); also automatically provides a single button.
\item [``WARN''] uses the warning colour scheme as used by the popup screens (defaults to yellow on green). User definable button bar available (see button\_set).
\item [``ERROR''] uses the error colour scheme (white on red) with an active button bar.
\end{description}
Splash screen are exited by pressing any normal key. Usually function keys are rejected.
\end{description}

\subsection{Internal Functions}
These are the internal functions of the module; these should not be called by user scripts.
\begin{description}
\item [menu\_advice] displays a short message at the foot of the screen
\item [menu\_button\_bar] creates a button bar
\item [menu\_create\_pane] creates the menu display
\item [menu\_draw\_active] draws the active menu option
\item [menu\_draw\_button] draws a button
\item [menu\_draw\_inlay] draws the backdrop
\item [menu\_draw\_line] draws an inactive menu option
\item [menu\_draw\_pane] draws the menu pane
\item [menu\_draw\_window] draws the menu window
\item [menu\_edit] edit a field
\item [menu\_hot\_button] report which button is hot
\item [menu\_key\_seq] get input from the keyboard
\item [menu\_navigate] navigate through a menu
\item [menu\_preferences] load modules preferences from file
\item [menu\_redraw\_backdrop] redraw the backdrop
\item [menu\_refresh] redraw the whole screen especially after resizing a terminal window
\end{description}



\section{Application Preferences}
Cmenu provides a facility to read a \textit{preferences} file to configure a common look-and-feel for all your applications. Preferences can be setup for all users (using file \textit{/etc/Cmenu/cmenurc}). individual users (using \textit{\~/.cmenurc}...
\begin{description}
\item [colour] the colours to be used in all screen renditions including special mono-chrome renderings. Cmenu allows a combination of explicit colours and terminal attributes like bold and dim.
\item [keyboard] cmenu is pre-configured to interpret a variety of key-sequences as specific cursor commands; these can be tailored, disabled or supplemented. This includes use of functions keys.\\
Menu navigation uses normal cursor keys and page keys for larger movement; navigation can also behave like \textit{lynx} where right and left move between menus - this can be disabled.
\item [helpfiles] help files can be stored in locations other than running directories
\item [hacks] when rendered on 25-line mono-screens, a large amount of screen space is taken up with superfluous cosmetic frippery; ultra-serious people can reclaim an extra-line.
\end{description}
A heavily commented sample preferences files is included with the distribution. The preferences file is strictly structured; not following the prescribed layout may corrupt display elements or deactivate certain features.

\section{tic file}
Provided with the module is a tic file for VT100 emulation on a Wyse 60 terminal. This has some of the function keys defined correctly. You will need to define function strings if you want to use the 16 F keys. Page and some of the character keys are...

%%%% Body ends here

\end{document}