Diffpack Documentation

Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members File Members Search

MenuSystem Class Reference

a menu system (user interface) for input data. More...

#include <MenuSystem.h>

Inheritance diagram for MenuSystem::

Public Methods
	MenuSystem ()
	~MenuSystem ()
void	init (const String &description, const String &label)
MenuItemBase*	addItem (int level, const String &command, const String &cl_option_string, const String &description, const String &default_answer, const String &valid_answer, char hot_key, char cl_option_char, MenuCallBack *func=NULL)
MenuItemBase*	addItem (int level, const String &command, const String &cl_option_string, const String &description, const String &default_answer, const String &valid_answer, MenuCallBack *func=NULL)
MenuItemBase*	addItem (int level, const String &command, const String &description, const String &default_answer)
bool	addSubMenu (int level, const String &name_label, const String &command, const String &description, char hot_key)
bool	addSubMenu (int level, const String &name_label, const String &command, const String &description)
bool	addSubMenu (MenuSystem *menu)
bool	disableIfEqual (String item_boss, String value, String item_disable)
void	forget ()
void	prompt ()
void	forceAnswer (const String &command_and_answer)
String	get (const String &command)
void	set (const String &command, const String &value)
void	setAboutImage (const String &path)
void	setAboutText (const String &text)
void	setAboutGeometry (int width, int height)
String	getAboutImage () const
String	getAboutText () const
int	getAboutWidth () const
int	getAboutHeight () const
void	print4awk (Os os)
void	multipleLoop (SimCase &user)
bool	insideMultipleLoop () const
int	getMultipleLoopLimit () const
int	getMultipleLoopIndex () const
void	setCommandPrefix (const String &prefix)
void	unsetCommandPrefix ()
String	getCommandPrefix () const
bool	ok () const
bool	empty () const
void	writeHeadings4multipleAnswers (StringList &headings)
void	writeResults4multipleAnswers (StringList &results)
void	writeExtendedResults4multipleAnswers (MultipleReporter &rep, int section_level=1)
String	getDescription () const
MenuItemBase*	getFirstItem ()
void	initParallelPrompt (const PromptBase &p)
bool	initFromCommandLineArg (const char option, real &number, real default_value, const char description=NULL, const char *variable_type=NULL)
bool	initFromCommandLineArg (const char option, int &number, int default_value, const char description=NULL, const char *variable_type=NULL)
bool	initFromCommandLineArg (const char option, bool &indicator, bool default_value, const char description=NULL, const char *variable_type=NULL)
bool	initFromCommandLineArg (const char option, String &string, const char default_value, const char description=NULL, const char variable_type=NULL)
Static Public Methods
void	makeSubMenuHeader (MenuSystem &menu, const String &description, const String &command, int &level, char hot_key)
Public Attributes
StringList	answers
Protected Methods
void	search4multipleAnswers (MenuAnswerTable &table)
MenuLists*	getMenuListsPtr ()
bool	levelCheck (int level)
Protected Attributes
VecSimplest(Handle(MenuLists))	menu_lists
bool	initialized
MenuAnswerTable	table
bool	disable_add_and_prompt
bool	is_inside_multiple_loop
String	command_prefix
String	save_input_to_file
int	ncomb
int	icomb
String	about_image
String	about_text
int	about_width
int	about_height
SetDistinct(String)	init_from_command_line_options
StringList	init_from_command_line_defaults
StringList	init_from_command_line_descriptions
StringList	init_from_command_line_vartypes

Detailed Description

a menu system (user interface) for input data.

NAME: MenuSystem - a menu system (user interface) for input data

DESCRIPTION:

Class "MenuSystem" makes it possible to create a fairly simple, general and still flexible user interface. The interface is implemented as a hierarchy of menus with submenus and menu items for user input. The interface is defined by the programmer in the program code in terms of a menu with submenus and menuitems. Different menus created in different parts of the program may be combined together to create one common global user interface. Hence it is convenient to let every class be responsible for its own I/O.

Constructor & Destructor Documentation

MenuSystem::MenuSystem ( )

The constructor takes no arguments. The object is not sufficiently initialized if unless the "init" function is called. It takes arguments containing a description of the menu and a label used when prompting the user in the interactive terminal dialog mode.

MenuSystem::~MenuSystem ( )

Member Function Documentation

MenuItemBase * MenuSystem::addItem ( int level,

const String & command,

const String & description,

const String & default_answer )

See documentation of one of the overloaded functions.

MenuItemBase * MenuSystem::addItem ( int level,

const String & command,

const String & cl_option_string,

const String & description,

const String & default_answer,

const String & valid_answer,

MenuCallBack * func = NULL )

See documentation of one of the overloaded functions.

MenuItemBase * MenuSystem::addItem ( int level,

const String & command,

const String & cl_option_string,

const String & description,

const String & default_answer,

const String & valid_answer,

char hot_key,

char cl_option_char,

MenuCallBack * func = NULL )

adds a menu item to the menu at the given level. There are convenient "const" variables for the three first levels: "MAIN" (1), "SUB" (2) and "SUBSUB" (3). See [HPL] H.P. Langtangen, "Computational Partial Differential Equations" for explanation of the arguments. There is an overloaded version where the hotkeys can be omitted (convenient in large menus).

bool MenuSystem::addSubMenu ( MenuSystem * menu )

See documentation of one of the overloaded functions.

bool MenuSystem::addSubMenu ( int level,

const String & name_label,

const String & command,

const String & description )

See documentation of one of the overloaded functions.

bool MenuSystem::addSubMenu ( int level,

const String & name_label,

const String & command,

const String & description,

char hot_key )

adds a submenu to the menu at the given level. See [HPL] for explanation of the arguments. There is an overloaded version where the hotkeys can be omitted (convenient in large menus). Another overloaded version imports a whole "MenuSystem" object as a new submenu.

bool MenuSystem::disableIfEqual ( String item_boss,

String value,

String item_disable )

bool MenuSystem::empty ( ) const

returns true if there are no items in the menu.

void MenuSystem::forceAnswer ( const String & command_and_answer )

enables the programmer to override the user''s input on the menu. Calling

menu.forceAnswer ("a parameter = 1.0");
in the program, will override any command "set a parameter = ..." at run time. One can of course use the "aform" function to construct answer strings that depend on other parameters in the simulator. The "forceAnswer" function is convenient for ruling out invalid answers or when the program itself computes answers to menu items (from, e.g., experimental design procedures). Inside the "MenuSystem" object, an "answers" list is used to hold all the information from calls to "forceAnswer". When calling "get", the "answers" list is searched before the menu tree.

void MenuSystem::forget ( )

erases all the previous menu items. In principle, the old items are still stored and will be printed in the input data manual for example, but the old items are not visible in the user interface. The function is usually called when the user has been prompted and new items are to be defined. All items prior to the last prompt should be forgotten.

String MenuSystem::get ( const String & command )

returns answer for a given command as a "String". There are two ways of feeding answers to a "MenuSystem" object: (1) use the standard approach where "prompt" is called and answers are filled in, or (2) use the "forceAnswer" function.

int MenuSystem::getAboutHeight ( ) const [inline]

String MenuSystem::getAboutImage ( ) const [inline]

String MenuSystem::getAboutText ( ) const [inline]

int MenuSystem::getAboutWidth ( ) const [inline]

String MenuSystem::getCommandPrefix ( ) const

String MenuSystem::getDescription ( ) const [inline]

MenuItemBase * MenuSystem::getFirstItem ( )

MenuLists * MenuSystem::getMenuListsPtr ( ) [protected]

int MenuSystem::getMultipleLoopIndex ( ) const [inline]

returns the current combination number in a multiple loop.

int MenuSystem::getMultipleLoopLimit ( ) const [inline]

returns the total number of possible combinations in the multiple loop.

void MenuSystem::init ( const String & description,

const String & label )

initializes the menu. Requires a description and a prompt label.

bool MenuSystem::initFromCommandLineArg ( const char * option,

String & string,

const char * default_value,

const char * description = NULL,

const char * variable_type = NULL )

bool MenuSystem::initFromCommandLineArg ( const char * option,

bool & indicator,

bool default_value,

const char * description = NULL,

const char * variable_type = NULL )

bool MenuSystem::initFromCommandLineArg ( const char * option,

int & number,

int default_value,

const char * description = NULL,

const char * variable_type = NULL )

bool MenuSystem::initFromCommandLineArg ( const char * option,

real & number,

real default_value,

const char * description = NULL,

const char * variable_type = NULL )

void MenuSystem::initParallelPrompt ( const PromptBase & p ) [inline]

bool MenuSystem::insideMultipleLoop ( ) const [inline]

returns true if the menu system is processing a multiple loop. Otherwise it returns false.

bool MenuSystem::levelCheck ( int level ) [protected]

static void MenuSystem::makeSubMenuHeader ( MenuSystem & menu,

const String & description,

const String & command,

int & level,

char hot_key ) [static]

sets a description, label etc. for a part of the menu. If this part is added as a submenu to the tree ("level" equals "SUB"), the label becomes the submenu name. It may be convenient to call "makeSubMenuHeader" in the beginning of a "defineStatic" function. If the "defineStatic" function is called with a level argument corresponding to one higher than the present level, all the items defined by the "defineStatic" functions will be put on a submenu. The submenu heading and command is then automatically set by the "makeSubMenuHeader" call in "defineStatic".
Be careful and add items on the menu immediately after the call to "makeSubMenuHeader" since this function may create a submenu. It's easy to make the error of first calling "makeSubMenuHeader" and then calling a "defineStatic" or "define" function in another class that also calls "makeSubMenuHeader". In such cases one may easily create two submenus with no items in between. The first submenu will then be empty.

void MenuSystem::multipleLoop ( SimCase & user )

the administrating function for execution of a large number of simulations, on basis of all possible combinations of multiple menu answers. The argument must be a class derived from class "SimCase". There are certain requirements of this derived class, for example, it must have certain virtual functions implemented. More details can be found in [HPL]. See class "MenuAnswer" for details on the syntax used for multiple answers.

bool MenuSystem::ok ( ) const

returns true if the object is properly initialized (that is, if the "init" function has been called). Otherwise it returns false.

void MenuSystem::print4awk ( Os os )

prints a list with all data stored in current menu. The output forms the basis for scripts that automatically generate manuals for the usage of the menu in question and `\`LaTeX`\` tables containing the values of the input data from the most recent execution. See [HPL] for more information on automatic manual generation.

void MenuSystem::prompt ( )

reads values into the menu, using the type of user interface determined by input source. This input source is usually set on the command line when executing the program. The effect of "prompt" depends on the type of user interface. In the interactive terminal dialog mode, the user is literally prompted. When using the command line option mode, the prompt has no effect, while when using the graphical motif interface, a call to prompt results in an X11 window with the menu system interface.

void MenuSystem::search4multipleAnswers ( MenuAnswerTable & table ) [protected]

void MenuSystem::set ( const String & command,

const String & value )

void MenuSystem::setAboutGeometry ( int width,

int height ) [inline]

void MenuSystem::setAboutImage ( const String & path ) [inline]

void MenuSystem::setAboutText ( const String & text ) [inline]

void MenuSystem::setCommandPrefix ( const String & prefix )

after calling this function all commands defined by "addItem" get a prefix string. Likewise, all calls to "get" will result in a search for the command combined with the prefix string.
Consider this situation: Let class "X" have "define" and "scan" functions that use the menu system. If you have two "X" objects in another class and want to define two "X" menus for different quantities, there will normally be two calls to "X define" and a duplicate of the menu entries. Also in calls to "X scan" it will be impossible to distinguish between the two "X" objects. However, if one puts a prefix "X1" (by calling the "setCommandPrefix" function) to the first "X" object and "X2" to the second "X" object, the commands made by "X define" will differ for the two objects. Remember to call "unsetCommandPrefix" when you do not want a prefix for every command! Using "setCommandPrefix" and "unsetCommandPrefix" before and after the calls to "X scan" enables reading the menu answers for the two "X" objects.

void MenuSystem::unsetCommandPrefix ( )

void MenuSystem::writeExtendedResults4multipleAnswers ( MultipleReporter & rep,

int section_level = 1 )

see documentation of the function "writeHeadings4multipleAnswers". The value of the menu items that are varied in a multiple loop is written in a separate section in the report. The extra argument "section_level" determines the level of the section; 0 means a section, and 1 means a subsection. For stand-alone solvers, 1 is appropriate, while 0 is used when solvers are combined (system of PDEs), because then it is appropriate with a common section with the multiple loop parameters before each solver presents its specific part of the report.

void MenuSystem::writeHeadings4multipleAnswers ( StringList & headings )

searches for all menu items that have multiple answers and appends the associated menu commands to the list given as argument. This function is very convenient when used in combination with the summary feature of class "MultipleReporter". In a simulator (derived from class "SimCase") one can in the "writeHeadings" function simply do

menu_system->writeHeadings4multipleAnswers (headings);
and all menu items that are varied in a multiple loop are automatically added on the headings list in the summary report. Similarly, in the "writeResults" function one makes a similar call,

menu_system->writeResults4multipleAnswers (results);
to fill the assoicated (current) answers in the summary report. Of course, the user may always want to include some specific input data in the "headings" and "results" lists. These values may then be a repetition of what has been already added to the list by the "MenuSystem" functions, but this is a minor inconvenience.

void MenuSystem::writeResults4multipleAnswers ( StringList & results )

Friends And Related Function Documentation

class PromptBase [friend]

Member Data Documentation

int MenuSystem::about_height [protected]

String MenuSystem::about_image [protected]

String MenuSystem::about_text [protected]

int MenuSystem::about_width [protected]

StringList MenuSystem::answers

String MenuSystem::command_prefix [protected]

bool MenuSystem::disable_add_and_prompt [protected]

int MenuSystem::icomb [protected]

StringList MenuSystem::init_from_command_line_defaults [protected]

StringList MenuSystem::init_from_command_line_descriptions [protected]

SetDistinct(String) MenuSystem::init_from_command_line_options [protected]

StringList MenuSystem::init_from_command_line_vartypes [protected]

bool MenuSystem::initialized [protected]

bool MenuSystem::is_inside_multiple_loop [protected]

VecSimplest(Handle(MenuLists)) MenuSystem::menu_lists [protected]

int MenuSystem::ncomb [protected]

String MenuSystem::save_input_to_file [protected]

MenuAnswerTable MenuSystem::table [protected]

The documentation for this class was generated from the following file:

MenuSystem.h

Diffpack Documentation

MenuSystem Class Reference

Public Methods

Static Public Methods

Public Attributes

Protected Methods

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation