view release on metacpan or  search on metacpan

doc/Cmenu.tex  view on Meta::CPAN

%%%% Page Heading and title of Document
\maketitle
\quote{Cmenu is a module for perl v5 offering menuing facilities typically offered by the command-line utility \textit{dialog}. Unlike \textit{dialog} it is not meant to be called from the command-line, instead it provides a number of menuing and dia...

This document describes how the module should be installed and how it can be used in perl scripts.}

\tableofcontents

%%%% Body starts here
\section{Installation}
Installation of the Module should be pretty painless.
\begin{enumerate}
\item Check the source for hacks which may be necessary for your Platform. In the \textit{menu\_initialise} routine, we try to get some terminal characteristics direct from the terminal; there seem to be different methods for different platforms. Che...

The module has only been tested under Linux and the default is set for it; the other methods my be totally unnecessary now with Curses but I left these in from \textbf{perlmenu}.
\item Run \textbf{perl Makefile.PL}. This performs a few checks
\item Run \textbf{make}. This creates a tree ready for installation
\item Run \textbf{demo}. This demonstration script should run before the Module has been installed; use it as a test for now.
\item Run \textbf{make install} The Module should now be available for your own scripts.
\end{enumerate}

\section{How to use Cmenu}
The Module provides a few global functions that can be called by user scripts. Before these become available you must include the command

\textbf{use Cmenu;}

in your script. The Module also requires the Curses and Text::Wrap modules though these should be loaded by \textit{Cmenu} for you.

Details of using each function is explained fully in the appendix. An overview is provided here;

\subsection{General operation}
The typical sequence of using the Cmenu functions is;
\begin{enumerate}
\item Initialise the Module and Curses by calling \textbf{menu\_initialise}. This activates Curses and sets up module variables. Once this has been called, Curses is active; this means screen I/O should only be performed through Curses functions. If ...
\item Create a new menu with the \textbf{menu\_init} function.
\item Create one or more menu items with the \textit{menu\_item} function. This is the most powerful function as it allows you control over the functioning and appearance of each menu item.
\item Display the menu by calling \textbf{menu\_display}. This routine performs all menu navigation, field editing, help displays and other stuff. Eventually pressing an exit key will end this routine when the results of the menu navigation will be r...
\item Your script should then react to the data returned by the menu. Most of the time this processing will be fairly trivial but if you built a complex menu with lists and data fields for editing, the return value may be quite complicated to deal wi...
\item You can continue this process until you no longer need the module when \textbf{menu\_terminate} should be called. This will closedown Curses so that screen I/O will return to normal. You can continue user interaction if you wish but none of the...
\end{enumerate}


\appendix
\section{Sample Script}
The following script shows how a simple menu can be created. This is provided as a quick guide to creating user dialogs. 

A more comprehensive example script is provided with the distribution as a test script to verify the correct installation of the module; it also serves as a demonstration of all the features provided by the module. This demonstration script can be fo...

In the following script, elements presented in \textbf{bold} are functions or variables provided by Cmenu, elements in \textit{italics} are items provided by the user, all other text are generic perl instructions.

\begin{center}
\textbf{Sample Script\\}
\begin{tabular}{rll}
\hline
1&\#!/usr/bin/perl\\
2&\\
3&\# Sample Cmenu script\\
4&\\
5&\textbf{menu\_initialise}(\textit{"Cmenu Sample Script"});\\
6&\\
7&\textbf{menu\_init}(\textit{"Menu Title"},\textit{"Menu Help Text"});\\
8&\\
9&\textbf{menu\_item}(\textit{"Option 1"},\textit{"gimme1"});\\
10&\textbf{menu\_item}(\textit{"Option 2"},\textit{"gimme2"});\\
11&\\
12&chop(\$sel $=$ \textbf{menu\_display}(\textit{"Menu Prompt"}));\\
13&\\
14&\textbf{menu\_terminate}(\textit{"bye bye"});\\
15&\\
\hline
\end{tabular}
\end{center}


\section{Function Reference}
This section provides a comprehensive list of user functions provided by the module explaining their use and calling parameters.

\subsection{User Functions}
These functions are designed to be called by user scripts.
\begin{description}
\item [menu\_button\_set] enables or disables buttons; sets text on button
\item [menu\_display] call to activate a menu and return a selection
\item [menu\_init] initialise a new menu structure
\item [menu\_initialise] initialise the module; called at the beginning of a script once only
\item [menu\_item] define a menu option
\item [menu\_popup] popup a display while processing is occurring
\item [menu\_show] splash data to the screen
\item [menu\_terminate] terminate all Curse and menuing structures; called on exit from script
\end{description}

\subsection{menu\_initialise}
Its job is to create a Curses environment and configure Cmenu to operate effectively with your terminal providing some default values for variables. It accepts tow variables and is called like this;
\begin{center}
menu\_initialise("My System","Menu Prompt");
\end{center}

\begin{description}
\item [My System] the name of your system displayed in the top left-hand corner of the display - it is always present
\item [Menu prompt] a standard propmpt displayed at the foot of the screen; can be over-ridden during menu specification
\end{description}

\subsection{menu\_init}
Create a menu structure. It is normally called like;
\begin{center}
menu\_init("My Menu","Interesting text","help\_file");
\end{center}

\begin{description}
\item [My Menu] the title of your menu displayed at the centre-top of the menu window
\item [Interesting Text] supplementary text usually enhancing a users experience as they enjoy your finely crafted program
\item [help\_file] a file to display when the user panics and presses the \textit{help} button (a function key can be defined as a help button rather than a soft button on the screen).

\textbf{NB} this feature is untested and may be broken
\end{description}

\subsection{menu\_item}
Creates a menu item; the main element of the module. Called like this;
\begin{center}
menu\_item("menu text","label",\$type,"tag","format");
\end{center}

\begin{description}
\item [menu text] (mandatory) the menu's descriptive text
\item [label] a text label associated with the menu item; unless over-ridden, this will be returned when an option is selected
\item [\$type] the type of a menu item controlling its rendering and behaviour
\begin{description}
\item [0 default] simple menu option returning the label if selected
\item [1 numeric] instead of text labels, offers numeric options
\item [2 radio list] a radio list selects ONLY one from a list
\item [3 check list] a check list select any (including none) from a list
\item [4 data label] a regular label usually used to accompany data fields for information only
\item [5 display] a right-aligned label for data information fields
\item [6 alpha-edit] an editable textfield
\item [7 numeric-edit] an editable numeric field
\item [8 encoded] for fields from a database it is often convenient to display a descriptive label but requiring a different return value
\item [9 spacer] like a comment, create a spacre-line in the menu
\end{description}
\item [tag] only used in some item types to contains alternate return values (type 8) or indicate active list selections (types 2 or 3)
\item [format] for editable fields specifies the field size and numeric formating; phrased as a space seperate list like \textbf{"25 2 0"} which has field-width 25 and 2 decimal places. (I forget why I wanted the third digit)
\end{description}

For a demonstration of all these options and how to use them in real menus, run and play with the included \textbf{demo} script.

\subsection{menu\_display} 
Activate a menu and let Cmenu do the menu navigation. This call will return user selections depending on the type of menu items included in the menu. Dealing with the return value can be quite complicated for complex menus.

It is normally called as

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

doc/Cmenu.tex  view on Meta::CPAN

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}