%  devmenu.tex from ObjectProDSP 0.2
%  Copyright (C) 1994 1995, Mountain Math Software. All rights reserved.
%  
%  This file is part of ObjectProDSP, a tool for Digital Signal
%  Processing design, development and implementation. It is free
%  software provided you use and distribute it under the terms of
%  version 2 of the GNU General Public License as published
%  by the Free Software Foundation. You may NOT distribute it or
%  works derived from it or code that it generates under ANY
%  OTHER terms.  In particular NONE of the ObjectProDSP system is
%  licensed for use under the GNU General Public LIBRARY License.
%  Mountain Math Software plans to offer a commercial version of
%  ObjectProDSP for a fee. That version will allow redistribution
%  of generated code under standard commercial terms.
%  
%  This program is distributed in the hope that it will be useful,
%  but WITHOUT ANY WARRANTY; without even the implied warranty of
%  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
%  GNU General Public License for more details.
%  
%  You should have received a copy of version 2 of the GNU General
%  Public License along with this program. See file COPYING. If not
%  or if you wish information on commercial versions and licensing
%  write Mountain Math Software, P. O. Box 2124, Saratoga, CA 95070,
%  USA, or send us e-mail at: support@mtnmath.com.
%  
%  You may also obtain the GNU General Public License by writing the
%  Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
%  USA.  However if you received a copy of this program without the
%  file COPYING or without a copyright notice attached to all text
%  files, libraries and executables please inform Mountain Math Software.
%  
%  ObjectProDSP is a trademark of Mountain Math Software.
%  
\section{Modifying the menu data base}
\label{Sec:MenuDataBase}

The menu data base is defined by a text file \DppNm{opd.menu} in
directory \\
\verb"$OPD_ROOT/menus" and by the \DppNm{.nod} text files created by
\IntPp{}. In this section we describe the syntax and semantics
of these files.


\subsection{Menu data base menus}
\label{Sec:Menus}

Figure~\PageRef{Fig:MenuExamp} is the start of
the definition of the main menu from that file.
The keyword \DppNm{Menu} followed by `{\tt \{}' indicates the start
of the menu. The items in the menu are delimited by the opening
and closing braces. The closing brace for the main menu is not
in the figure because this is only a part of the meu.
Next is the menu name \DppNm{MainCgi}. This id used in higher
level menus to specify a submenu. For this main menu it is referenced
at the start of the file to define the root of the menu tree.
(The syntax there that supports multiple main menus is obsolete
and not documented but you do need to copy that structure to specify
the root menu.)

\begin{figure}
\input{mmenu.tex}
\caption{First part of the definition of the main menu}
\label{Fig:MenuExamp}
\end{figure}


Following the menu name is a `{\tt :}' and text that describes
the menu. This text is displayed above the buttons for the menu
when the cursor is not positioned over any of those buttons.
Next is a sequence of menu items each of which corresponds to
a button in the menu. If there are more items then there is
space for buttons submenus under `\DppNm{other}' are automatically
created.

\subsection{Menu items}
\label{Sec:MenuItems}

The first menu item starts with the command or label 
for the button, {\tt help}, followed by a `{\tt ,}' and the
name of the structure corresponding to that command the character `{\tt =}'
and the type of the command. In this example all three menu
items reference submenus. Next there is a `{\tt :}' and text 
describing the menu item. This is the text displayed above the menus
when the cursor is positioned over the button for this item. Next is optional
text enclosed in braces that provides a more complete description
of this item. Any of this text enclosed with `{\tt \$}' characters
should refer to user commands. These are set in {\tt typescript font}
in the documentation and index entries are created for them.
Such text is enclosed in single quotes when the text is displayed
interactively. This description of the item is displayed in the
\DppNm{help information} window when the left or right mouse button
is {\it released} with the cursor over this button. This can
be disabled by changing the help levels.

If the same text is used in several menu items it can be defined
once with the 
\DppNm{Help\-Def\-inition} {\tt \{} {\it definition\_name help text} {\tt \}}\\
construct. The text can then be referenced many times with the
`{\it definition\_name}\DppNm{=HelpText}' option in the syntax
for a menu item.

\subsection{Help files}
\label{Sec:MenuHelpFile}

Finally is the keyword \DppNm{HelpFile} a `{\tt :}'
and the base name for the help file. This is optional.
See Section~\PageRef{Sec:HelpFile} for more information on these files.
Instead of a help file base name the key word `\DppNm{Default}' may
be used. This refers to the last help file specified with the
\DppNm{HelpFileDefault} construct.

\subsection{Menu qualifiers}
\label{Sec:Qualifier}

There are several qualifiers that can precede the key word menu.

\begin{itemize}
\item{\DppNm{History}} The action taken may be a function of
previous selections using action parameters as described in
\PageRef{Sec:ActParam}.
\item{\DppNm{Dynamic}} The menu may have items added to it after
executions starts.
\item{\DppNm{Multiple Use}} The menu may occur at multiple points
in the tree with different initializations (obsolete).
\item{\DppNm{Orphan}} A menu that has no predefined place in the tree. This
is used for member functions of a base class. The class member functions are not
included in the tree through the class itself but through other classes derived
from the base class. The \DppNm{Orphan} menu generated for such a class is merged
with the member function menus of all derived classes that occur in the tree.
\item{\DppNm{Select}} The actions are initialized at execution time based
on a \DppNm{Template} menu item. See Section~\PageRef{Sec:ExampMenu}.
\end{itemize}


\subsection{Simplified menu syntax}
\index{menu syntax}

Figure~\PageRef{Fig:MenuSyntax} gives a simplified \DppNm{yacc}
(or \DppNm{bison})
syntax for the menus. The rules are in alphabetical order. The top level
symbol is \Index{ObjectList}. Literal
terminal symbols are in {\tt typewriter} font
and enclosed in single quotes. Standard terminal symbols like
{\it name} are in {\it italicized font}.
If a rule ends with `$\mid$'
it can be reduced to the null symbol.

Table~\PageRef{Tab:MenuSyntaxTerminals} gives a brief explanation
for each nonterminal symbol and references for some.
The full \DppNm{yacc} (or \DppNm{bison}) syntax
is in file\\ {\tt \$OPD\_ROOT/src/util/mkmenu/menu\_b.y}.\\
\index{mkmenu_b.y}
Note some constructs in the full syntax are for future
expansion and others 
are obsolete but retained for backwards compatibility.



{\small
\begin{figure}
\setlength{\parindent}{.2in}
\noindent
\Index{Action} : Name Parameters $\mid$ Name Parameters `\DppNm{Wait}' $\mid$
	`\DppNm{Orphan}' \\
\Index{ActionType} : `\DppNm{=Local}'\index{Local}
	$\mid$ `\DppNm{=Remote}'\index{Remote}
	$\mid$ `\DppNm{=LocalRemote}'\index{LocalRemote}
	$\mid$ `\DppNm{=RemoteOptions}'\index{RemoteOptions}
	$\mid$ `\DppNm{=Menu}'\index{Menu}
	$\mid$ `\DppNm{=DynamicMenu}'\index{DynamicMenu}
	$\mid$ `\DppNm{HelpFile}' \\
\Index{ClassRelation} : `{\tt \{}' {\it name}   {\it name}  `{\tt \}}' \\
\Index{Command} : WordString \\
\Index{Comment} : `\DppNm{//}' {\it text to end of line } \\
\Index{DefinedActionList} : `\DppNm{DefinedAction}' `{\tt \{}' NameList `{\tt \}}' \\
\Index{Help} : `{\tt \{}' {\it text} `{\tt \}}' \\
\Index{HelpDef} : `\DppNm{HelpDefinition}' `{\tt \{}' {\it name} {\it help text} `{\tt \}}' \\
\Index{HelpDefaultFile} : `\DppNm{HelpDefaultFile}' {\it quoted string} \\
\Index{HelpFile} : \DppNm{=HelpFile}\index{HelpFile} `{\tt base\_file\_name} $\mid$ `\DppNm{Default}' $\mid$ \\
\Index{HelpRef} : `{\tt ,}' {\it name} `\DppNm{=HelpText}'\index{HelpText}  \\
\Index{InitEntry} : `\DppNm{Init}'  `{\tt \{}' {\it \Cpp{} code} `{\tt \}}'
	{\it name} '=' PriorNameList `{\tt ;}' \\
	\indent $\mid$ `\DppNm{Init}'  `{\tt \{}' {\it \Cpp{} code}
	`{\tt \}}' {\it name} `{\tt ;}' \\
\Index{Menu} : MenuId `{\tt \{}' Name `{\tt :}' MenuTitle MenuBody `{\tt \}}'  \\
	\indent $\mid$ `\DppNm{Add To Menu}' `{\tt \{}' {\it name} MenuBody `{\tt \}}' \\
\Index{MenuBody} :  MenuBody MenuItem $\mid$  \\
\Index{MenuId} : Qualifier `\DppNm{Menu}' \\
\Index{MenuItem} : Command `{\tt ,}' Action  ActionType HelpRef `{\tt :}' {\it text} Help HelpFile \\
	\indent $\mid$ Command `{\tt ,}' Action  ActionType HelpRef `{\tt :}' {\it text} HelpFile \\
	\indent $\mid$ Command `{\tt ,}' Action  ActionType `{\tt :}' {\it text} Help HelpFile \\
	\indent $\mid$ Command `{\tt ,}' Action  ActionType `{\tt :}' {\it text} HelpFile \\
	\indent $\mid$ `\DppNm{Template}' `{\tt ,}' Action  ActionType `{\tt :}' {\it text} HelpFile \\
	\indent $\mid$ Command `\DppNm{=Reference}'\index{Reference} \\
\Index{MenuStackReference} : `{\tt [}' {\it nonnegative integer} `{\tt ]}'
\Index{MenuTitle} : {\it text } \\
\Index{NameList} : {\it name} $\mid$ NameList `{\tt ,}' {\it name} \\
\Index{Object} : Menu $\mid$ HelpDef $\mid$ HelpDefaultFile $\mid$ DefinedActionList $\mid$ \\
	\indent  InitEntry $\mid$ ClassRelation \\
\Index{ObjectList} : Object $\mid$ ObjectList Object \\
\Index{Parameter} : {\it number} $\mid$ {\it quoted string} $\mid$ MenuStackReference	\\
\Index{ParameterList} : ParameterList `{\tt ,}' Parameter $\mid$ Parameter\\
\Index{Parameters} : '(' ParameterList ')' $\mid$ \\
\Index{PriorNameList} : {\it name} $\mid$ PriorNameList `{\tt ,}' {\it name} \\
\Index{Qualifier} : Qualifier `\DppNm{Dynamic}' $\mid$ Qualifier `\DppNm{Multiple Use}' \\
	\indent $\mid$ Qualifier `\DppNm{History}' $\mid$ Qualifier `\DppNm{Select}' $\mid$ Qualifier `\DppNm{Orphan}' $\mid$ \\
\Index{WordString} : {\it text }
\caption{Menu data base syntax}
\label{Fig:MenuSyntax}
\end{figure}
} % end small

\begin{table}
\begin{tabular}{|lllr|} \hline
\Index{Symbol} & Meaning & Section & Page\\ \hline
\Index{Action} & what to do if selected \tref{Sec:MenuActions} \\
\Index{ActionType} & what type of action \tref{Sec:MenuActions} \\
\Index{ClassRelation} & class and base class \tref{Sec:IntegrateNodes} \\
\Index{Command} & user command name \tref{Sec:MenuItems} \\
\Index{Comment} & \Cpp{} style comments can end any line & & \\
\Index{DefinedActionList} & actions implemented \tref{Sec:WritingActions} \\
\Index{Help} & help text for an item \tref{Sec:MenuItems} \\
\Index{HelpDef} & help text used more than once \tref{Sec:MenuItems}  \\
\Index{HelpDefaultFile} & default help file name \tref{Sec:MenuHelpFile} \\
\Index{HelpFile} & help file action \tref{Sec:WritingActions} \\
\Index{HelpRef} & reference to help text \tref{Sec:IntegrateNodes} \\
\Index{InitEntry} & initialization of default objects \tref{Sec:IntegrateNodes} \\
\Index{Menu} & complete menu \tref{Sec:Menus} \\
\Index{MenuBody} & items in a menu \tref{Sec:MenuItems}  \\
\Index{MenuId} & menu type and internal name \tref{Sec:Menus} \\
\Index{MenuItem} & one entry under a menu \tref{Sec:MenuItems} \\
\Index{MenuStackReference} & previous menu reference \tref{Sec:WritingActions} \\
\Index{MenuTitle} & displayed title of menu \tref{Sec:Menus} \\
\Index{NameList} & list of defined actions \tref{Sec:WritingActions} \\
\Index{Object} & menu or other major syntactic element & & \\
\Index{ObjectList} & top level syntactic object & & \\
\Index{Parameter} & action parameter \tref{Sec:ActParam} \\
\Index{ParameterList} & list of parameters \tref{Sec:ActParam} \\
\Index{Parameters} & parameters for an action \tref{Sec:ActParam}  \\
\Index{PriorNameList} & required objects \tref{Sec:IntegrateNodes}  \\
\Index{Qualifier} & type of menu \tref{Sec:Qualifier} \\
\Index{Wait} & disables input until command completes & & \\
\Index{WordString} & command name \tref{Sec:MenuItems} \\
\hline
\end{tabular}
\caption{Symbols in \IntPp{} syntax}
\label{Tab:MenuSyntaxTerminals}
\end{table}

\subsection{Writing menu action code}
\label{Sec:MenuActions}
\label{Sec:WritingActions}

A menu item can select another menu display a help file or
perform some action. These actions can be \DppNm{Local}
(executed on the user interface process) \DppNm{Remote}
(executed on the DSP process) or \DppNm{LocalRemote} (executed
on both). The name for an action (that precedes the character
`\DppNm{ActionType}') should be the name of a \Cpp{} subroutine
in the appropriate executable. Dummy stubs for all actions
are generated unless the action name is listed in the
\DppNm{DefinedAction} construct. After you have written the
code for an action you must add its name to this list or
you will get a double definition of the subroutine when you
link.

\subsection{Examples menu and action parameters}
\label{Sec:ActParam}
\label{Sec:ExampMenu}

Actions can have parameters which refer to previous menu selections.
This is most commonly used in menus generated by \IntPp{} described
in Section~\PageRef{Sec:IntegrateNodes}. Action parameters are also used in
the examples menu. The top level menu for examples is a \DppNm{Select}
menu that has a single \DppNm{Template} menu item. This template will
be copied for every item under this menu. This is done
by reading a directory where examples are stored and generating an
entry for every file with a \DppNm{.xml} suffix in that directory.
The code to update the menus is in class \DppNm{DynamicMenuServer} defined in files
\DppNm{dynmnu.h} and \DppNm{dynmnug.C} in directory \\
\verb"$OPD_ROOT/src/dsp_gui/gui" \\
The code that calls the \DppNm{DunamicMenuServer} with the
action names for the menu items is in the constructor of \DppNm{ExamplesDspPP}
in file \\
\verb"$OPD_ROOT/src/gui/lib/examp.C".

\begin{figure}
\input{exampmenu.tex}
\caption{`Example networks' menu tree definition}
\label{Fig:ExampMenuTree}
\end{figure}

The definition of the `{\tt Example networks}' menu subtree from \DppNm{opd.menu}
is shown in Figure~\PageRef{Fig:ExampMenuTree}. The first top level
menu contains a single \DppNm{Template} menu item that will be duplicated
for each example found as just explained. The rest of the figure contains
the menu items in the `{\tt Describe or execute this example}' menu.
Each of these actions has at least one parameter that refers to the
selection in the previous menu. In the first item the action is
{\tt DescribeExample([1])}. When this item is selected subroutine
\DppNm{DescrubeExample} will be called with a single `{\tt const char *}'
parameter that will be the label on the button selected. 
This is denoted by `\DppNm{[1]}' in the menu definition. The integer
one refers to the most recent menu selection. Earlier selections can
are denoted by larger integers.

The \DppNm{ExecutExample} action has a second parameter: {\tt "no"}.
An action can have any number of parameters and they can be literal strings
integers or previous menu selections.

\subsection{Menus generated by \protect\IntPp{}}
\label{Sec:IntegrateNodes}

Figures~\PageRef{Fig:GeneratedMenus} and \PageRef{Fig:GeneratedMenus2}
show the first and last parts of the menus generated
by \IntPp{} for the node defined in \DppNm{const.usr}.
This starts with a line that designates \DppNm{ConstantData} as
a derived class from \DppNm{Signal}. This will insure any member
functions of \DppNm{Signal} will also appear in the menus under
\DppNm{ConstantData}. This is followed by \DppNm{Init} and \Cpp{}
code enclosed in braces to initialize default instances of this class.
This code is collected in file \DppNm{meninit.C} in routine
\DppNm{InitAllMenuRoutines} under directory \\
\verb"$OPD_ROOT/src/menus/dsp".

Next is statement{\tt Add To Menu} which provides the connection
to the full menu tree. It causes an item to be added under
the menu named \DppNm{Signal\-Nodes\-Menu}. This connection is specified
by giving the menu name after the key word \DppNm{MenuLine} for
the node. In \DppNm{opd.menu} menu \DppNm{Signal\-Nodes\-Menu}
is defined without any entries for commands or submenus.

Next is a \DppNm{Dynamic} menu to select an instance of
\DppNm{ConstantData}. This menu has no predefined
entries. It is a \DppNm{Template} used to add
entries to the menu as new instances of \DppNm{ConstantData} are created.
Next is
the submenu \\ \DppNm{ConstantDataInstancesAccessMenu} \\
that operates on the selected instance.
This is done by referring to previous selections in the
action. For example the action \\
\verb|DescribeNodeInstance("ConstantData",[1])=Remote| \\
calls the function \DppNm{DescribeNodeInstance} in the DSP process
with parameters \verb|"ConstantData"| and a string giving the
name of the selected instance of \DppNm{ConstantData}.


\begin{figure}
\begin{verbatim}
{ ConstantData Signal }
Init {
#include "ObjProUsr/const.h"
    ConstantDataDef = new ConstantData("ConstantDataDef", 1024);
} ConstantDataDef ;
HelpDefinition { ConstantDataMainHelpDefinition
      `ConstantData'   writes parameter   `Value'   to the output stream
    repeatedly. It is written as a binary integer constant.
}
Add To Menu { SignalNodesMenu
ConstantData,ConstantDataNodeOptMenu=Menu,
    ConstantDataMainHelpDefinition=HelpText :
    generate a `MachWord' constant
HelpFile : signalT
}
\end{verbatim}
\caption{First part of {\tt ConstantData} menus generated by \IntPp{}}
\label{Fig:GeneratedMenus}
\end{figure}



\begin{figure}
\begin{verbatim}
Multiple Use Dynamic Select Menu { ConstantDataInstancesMenu :
        Select an Instance of `ConstantData' t
Template,ConstantDataInstanceAccessMenu=Menu   :
        Select this instance of `ConstantData'
}

History Menu { ConstantDataInstanceAccessMenu:
        Describe or delete an instance of  object `ConstantData'
desc,DescribeNodeInstance("ConstantData",[1])=Remote,
    NodeInstanceDescribeHelp=HelpText   :
        Describe this instance of `ConstantData'
HelpFile : Default
param,ConstantDataInstanceParamMenu=Menu,
    ParamInstanceDescribeHelp=HelpText  :
        Describe parameters of this `ConstantData'
HelpFile : Default
exec, Orphan=Menu,
    HelpMemberExecute=HelpText  :
        Select a member of `ConstantData' to execute
HelpFile : Default
variables,ConstantDataInstanceVariableMenu=Menu,
    VariableInstanceDescribeHelp=HelpText   :
        Describe variables of this `ConstantData'
HelpFile : Default
set,ConstantDataSetInstanceVariableMenu=Menu,
    VariableInstanceDescribeHelp=HelpText   :
        Set variable values of this `ConstantData'
HelpFile : Default
delete,DeleteNodeInteractiveEntity("ConstantData", [1])=Remote,
    NodeDeleteHelp=HelpText : Delete this `ConstantData'
HelpFile : Default
}
\end{verbatim}
\caption{Last part of {\tt ConstantData} menus generated by \IntPp{}}
\label{Fig:GeneratedMenus2}
\end{figure}

\subsection{Menus documented at the top level}

The menus are automatically translated to documentation for
the \DppUser{}. The table of contents of this document has
a hierarchy that mirrors the menu hierarchy.
To prevent too many levels the menu for all classes is forced to
the top level i. e. \verb"\section" level. The name of this menu,
\DppNm{AllCls} is hardwired into program \\
\verb"$OPD_ROOT/src/util/mkmenu/menmain.C". \\
It is also used in \\
\verb"$OPD_ROOT/doc/userman/menu.tex". \\ 
If you change the name of this menu you wiil need
to edit those files.

However to keep the table of contents from getting t
going too many levels deep some menus are forced


