For displaying menus and getting user menu choices in console applications. More...

#include <utilities.h>

Public Member Functions
	Menu ()
	Default constructor; creates a "blank" menu. More...

	Menu (const string &menuTitle)

void	setTitle (const string &menuTitle)
	Sets (or resets) the menu title. More...

void	addOption (const string &option)

void	display () const

int	getChoice (int maxNumTries=3, string userPrompt="Enter the number of your menu choice here and press Enter: ") const

Detailed Description

For displaying menus and getting user menu choices in console applications.

The Menu class provides a convenient way for simple text-based console programs to display for the user a menu of choices. A menu has a title and up to 20 numbered options which are separated from the title by a blank line when the menu is displayed. A menu knows what its range of valid options is, and can get from the user a valid choice from that range, or return an error value of -1 if the user fails to enter a valid option number during three attempts (by default), or during some client-chosen number of attempts.

Constructor & Destructor Documentation

◆ Menu() [1/2]

Scobey::Menu::Menu ( )

Default constructor; creates a "blank" menu.

Precondition: None

Postcondition: A "blank" menu has been constructed which has the (default) title "Empty Menu" and no options.

◆ Menu() [2/2]

Scobey::Menu::Menu ( const string & menuTitle )

Constructor for creating a menu with a user-supplied title
but no options.
@param menuTitle The text of the title for this menu.
@pre <em>menuTitle</em> has been initialized and does not exceed
70 characters in length.
@post
- Case 1 (typical): A menu has been constructed with a title
given by the contents of <em>menuTitle</em>, and having 0 options.
- Case 2 (error): If an attempt was made to use a title whose
length exceeded the maximum length of 70 characters, the following
message has been displayed and the user has pressed Enter:

===== Error: Menu title cannot exceed 70 characters in length.
The title
<<text_of_title_that_was_too_long_appears_here>>
was not added to the menu.
This menu has been given the following default title:
Empty Menu
Press Enter to continue ...

Member Function Documentation

◆ setTitle()

void Scobey::Menu::setTitle ( const string & menuTitle )

Sets (or resets) the menu title.

Returns: void

Parameters

menuTitle Contains the text of the title for the menu.

Precondition: menuTitle has been initialized and menuTitle.length() <= 70.

Postcondition

Case 1 (typical): The text in menuTitle has been assigned as the title of the menu.
Case 2 (error): If an attempt was made to set a title which exceeded the maximum length of 70 characters, the following message has been displayed, and the user has pressed Enter:
```
===== Error: Menu title cannot exceed 70 characters in length.
The title
<<text_of_title_that_was_too_long_appears_here>>
was not added to the menu. Previous title remains unchanged.
Press Enter to continue ...
```
In either case, the number of menu options is unchanged.

◆ addOption()

void Scobey::Menu::addOption ( const string & option )

Adds a new option to the menu and assigns it the next available
option number.
@return void
@param option The text of the next option to be added to the menu.
@pre
The number of options on the menu is < 20.\n
<em>option</em> has been initialized and has length <= 70 characters.
@post
- Case 1 (typical): The number of menu options has been
incremented by 1 and the text in <em>option</em> has become the
option with the new option number.
- Case 2 (error): If the number of options was 20, then the
following message has been displayed and the user has pressed
Enter:

===== Error: Number of menu options cannot exceed 20.
Option <<text_of_option_goes_here>> not added.
Press Enter to continue ...

Case 3 (error): If an attempt was made to add an option which exceeded the maximum length of 70 characters, the following message has been displayed and the user has pressed Enter:

===== Error: Menu option cannot exceed 70 characters in length.
The option
<<text_of_option_that_was_too_long_appears_here>>
was not added to the menu.
Press Enter to continue ...

◆ display()

void Scobey::Menu::display ( ) const

Displays a "centered" menu on the screen.
@return void
@pre The menu has been initialized.
@post The menu has been displayed on the screen, more or less
centered left-to-right and top-to-bottom, but with a slight
top-left bias. Note, however, that a blank menu, or a menu with
just a title, is displayed with its title left-justified and with
only the bias toward the top. Such a title is followed by a blank
line and the following 1-line message, which also starts at the
left margin:

This menu currently has no options ...

The (typical) display format is achieved in the following way:

First, by displaying (1/2)(24-numMenuLines)+1 blank lines at the bottom of the screen.
Second, by arranging that column 38 (rather than column 40, of a typical 80 line display) be the column about which the menu title and the menu options are "centered" in the display.

◆ getChoice()

int Scobey::Menu::getChoice	(	int	maxNumTries = `3`,
		string	userPrompt = `"Enter the number of your menu choice here and press Enter: "`
	)		const

Gets a menu choice from the user, or a default value if the user
fails to enter a valid menu choice before the permitted number
of attempts runs out.
@return The user's menu choice, or the default value of -1.
@param maxNumTries The maximum number of tries permitted to the
user to enter a valid menu choice.
@param userPrompt The text of the prompt to be used to ask the
user for a menu choice.
@pre
Typically, a menu has been initialized, and presumably
displayed, though in fact this is not technically a necessary
pre-condition for this function.
@post
- Case 1 (typical): A valid menu choice for the menu has been
entered by the user and returned.
- Case 2 (error): If a choice was sought from a blank menu, the
message

===== Error: The menu has no options from which to choose.
Press Enter to continue ...

has been displayed and the user has pressed Enter.

Case 3 (error): If an invalid menu choice has been entered, the displayed message is:
```
===== Error: Sorry! Invalid response. Please try again:
```
If maxNumTries unsuccessful attempts have been made, the displayed message is:
```
===== Error: Sorry, but you only get <<maxNumTries>> chances.
Press Enter to continue ...
```
and the user has pressed Enter, after which the value of -1 is returned. Note that if no prompt is supplied by the client, the default prompt
```
Enter the number of your menu choice here and press Enter:
```
is displayed slighty left-of-center on the screen below the menu. Note as well that anything other than a valid menu choice for the current menu will be read and rejected, including (for example) a valid menu choice followed by extraneous characters, as well as simply pressing Enter.

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

Public Member Functions