CS 305 -- Software Engineering

User Interface Specifications

Version: 0.8, March 24, 1998

Maintained by: Joseph Squire

Other team members: Kunal Mittal

Changes from Previous Versions: No previous versions.

Non-standard Terminology: menubar, scrollbars, resized, browser, popup, uneditable, undoable, resizable.

Document purpose: This document describes how an end-user shall interact with "C++ Pointers". It describes where the user shall enter information to interact with the software, where graphical displays shall be placed on the screen, and how the graphical displays change with respect to actions taken by the user.

0. Overview:

This document specifies a graphical user interface that shall allow an end user to easily and intuitively interact with the program by exploiting familiar graphical user interface elements that include menus, windows, text entry fields, and buttons.

1. General Screen Layout:

1.1: The general layout of the screen shall be as follows (shown 2:1 scale; click on it to see a full-scale copy):

(Note: This picture is not to be used to define the exact appearance of the program (i.e., exactly what the scrollbars look like, the text font, things related to the particular browser, etc.). It is to be used as a guide for placing graphical elements on the screen.)

1.2: The title of the Web page is "C++ Pointers". The text "C++ Pointer Visualization Tutorial" shall appear on the Web page, centered at the top of the page above the work area in "Largest Heading" format (i.e., 18 point font size). The text "C++ Pointer Visualization Tutorial" shall be in the HTML part of the Web page.

1.3: A menubar shall appear above the work area. The menubar consists of the following menus: "Lesson", "Commands", "Loop", and "Help".

1.4: The node pointer variables, the node pointer variable boxes, links, and nodes shall appear in the work area. This area shall have horizontal and vertical scrollbars, and it shall be resized when the browser window is resized. A 12 pixel separation shall exist between the left edge of the browser window and the right edge of the work area. A 21 pixel separation shall exist between the right edge of the scrollbar attached to the work area and the left edge of the browser scrollbar.

1.5: A command text entry box shall be below the work area, with the words "Command Being Executed:" placed above the command text entry box. There shall be 10 pixels of space between the work area and the top of the tallest letter in the words "Command Being Executed:", 5 pixels of space between the bottom of the words "Command Being Executed:" and the command entry text box, and 20 pixels of space between the command entry text box and the bottom of the browser window, excluding the scrollbars. The command text entry box shall automatically scroll horizontally if the text that is being entered will not fit in the box. The command text entry box and the words "Command Being Executed:" shall be 25 pixels away from the left edge of the browser window. The command entry text box shall be anchored to the left side of the node attribute radio buttons (note: the command entry text box is shown 375 pixels long in the full-scale version of the general screen layout picture). The radio buttons shall be anchored to the right edge of the browser window and the bottom edge of the work area.

1.6: The minimum size of the visual region of the work area (i.e., this excludes the scrollbars, which are 16 pixels wide in the diagram) shall be 640 pixels across by 480 pixels high (the full-scale screenshot of the screen shows the work area visual region as 564 pixels across by 191 pixels high). If the bowser window is made smaller than the minimum size of the work area, then scroll bars shall appear in the work area. The minimum size of the browser window shall be 610 pixels across by 340 pixels high (note: this is the size of the browser window in the full-sized version of the general layout picture, and the dimensions include the scrollbars). Also, the command entry text box and the words "Command Being Executed:" shall remain in the same location relative to the bottom left corner of the work area.

1.7: The radio buttons to the right of the command line allow the user to change the current node attributes. The default node attributes shall be singly linked lists and IntNodes. The user may change the node attributes only when there are no commands currently in the command log (this condition occurs right after a program restart and when the program is initially launched). If there are commands in the command log, then the radio buttons shall be disabled.

2. Menus:

2.1: The "Lesson" menu, when it is pulled down, shall look like this: (Note: if a popup window is to be displayed but the window is already open, then the window shall be moved in front of all other windows. This rule applies to all the menu items):

"Open Lesson..." shall be used to open a default or custom designed lesson. "Save As Lesson..." shall allow the user to save the lesson onto their local hard drive. "Start Lesson Over.." shall allow the user to start the lesson over again. "Show Lesson Instructions" shall put the lesson instructions on the screen in a popup window (See section 3.0 for more details on popup windows). "Check Lesson..." is not implemented in this version of C++ Pointers, so it is always disabled. Note: if the user wishes to quit the current lesson, the user should either choose "Clear All..." from the Commands menu, or the user should open a new lesson.

2.2: The "Commands" menu shall look like the following:

"Undo" shall undo the last command entered in the command text entry area, or the entire action done by a loop. "Show Prior Typed Commands" shall display the commands that the user has entered in the command text entry area and the loops that have been executed (see the Specifications document for information on what happens when commands are undone). This shall be displayed in an uneditable text popup window, and this window shall allow copying text from it into the clipboard. The "Clear All..." command will allow the user to restart the entire program, which shall do the following: clear the text of the loop boxes (see Section 4.6 for more details about this), clear the command log and all the links and nodes, set the node variable pointers p, q, r, and s to an uninitialized state, and purge any lesson from memory that is currently loaded, if a lesson is loaded.

2.3: The "Loop" menu shall look like this:

"For Loop..." and "While Loop..." shall cause a window to be displayed where a loop can be entered and executed (see section 3 for more details).

2.4: The "Help" menu shall look like this:

"About C++ Pointers..." shall display a window stating the program name, the people who contributed, a picture of the team, and copyright information. "User Manual..." shall bring up a new browser window to the documentation table of contents. "Show Key" shall display a key to the graphics in the work area, or it shall move the window in front of all other windows if the key window is already open.

2.5: Menu items that are not applicable at a given time shall be disabled. The specific conditions when this occurs are the following:

2.5.1: The "Lesson" menu: "Open Lesson..." shall always be enabled. "Save As Lesson..." shall only be enabled if there is at least one command in the command log. "Start Lesson Over..." shall only be enabled if a lesson is open and there is at least one command in the command log. "Show Lesson Instructions" shall be enabled when a lesson is loaded, otherwise it shall be disabled. "Check Lesson..." shall always be disabled, because this feature will not be implemented in this version of the program.

2.5.2: The "Commands" menu: The "Undo" command shall be disabled at the beginning of the program or immediately after a lesson restart or a program restart. It also shall be disabled immediately after the "Undo" command has been selected by the user and the last action has been undone. The "Undo" command shall only be enabled after an undoable action has been done (see Specifications for a list of undoable actions). "Show Prior Typed Commands" shall always be enabled. "Clear All..." shall always be enabled.

2.5.3: The "Loop" menu: Both the commands "For Loop..." and "While Loop..." shall always be enabled, except when a loop control window is on the screen. If the For Loop control window is on the screen, then the "While Loop..." menu item shall be disabled and the "For Loop..." menu item shall be enabled. If the While Loop control window is on the screen, then the "For Loop..." menu item shall be disabled and the "While Loop..." menu item shall be enabled.

2.5.4: Help menu: All the commands in the Help menu shall always be enabled.

2.6: An example of enabled and disabled menu items is provided as a guide:

In this example, "Undo", "Cut", "Paste", and "Clear" are all disabled, whereas "Copy", "Select All", and "Show Clipboard" are all enabled.

3. Popup windows:

3.1: All popup windows shall be resizable, movable, scrollable, and closable unless otherwise stated.

3.2: There shall be popup windows for the following items: a key to the relevant items in the work area (see Section 3.3 for examples), lesson text for the current lesson, error messages, for loops, and while loops (see Specifications for the locations and the form of the Help text, the program documentation, and the form of the for loop and while loop boxes).

3.3: The keys:

3.3.1: The key shall look like this when the user is working with singly linked lists:

3.3.2: The key shall look like this when the user is working with doubly linked lists:

3.3.3: The key shall look like this when the user is working with binary trees:

3.3.4: Key windows shall be neither resizable nor scrollable.

3.4: Lesson instructions shall be in a popup HTML window.

3.5: Error messages shall be in an uneditable text window titled "Error", and the error window shall be displayed only when an error occurs. The user shall acknowledge the error window by clicking on the "OK" button before the user can edit text in either the loop control window or the command line (see Section 5.5 for an example picture of the "Error" window).

3.6: Popup windows related to the Lesson Menu:

3.6.1: The "Open Lesson..." window shall look like the following (shown 2:1 scale; click on it to see a full-scale copy):

All the "<Lesson Title>" items shall be the names of the lesson, which are hot links to the actual lesson data. When the user clicks on a default lesson or chooses another lesson by entering a URL, the Lesson popup window shall disappear and the lesson shall be loaded. The nodes and links shall appear in their default positions for the lesson, and the lesson instruction text window shall be displayed. If the user enters an invalid lesson URL, then the "Open Lesson..." window shall remain on the screen and an error window shall appear on the screen with the text "An invalid lesson URL has been entered. Please re-enter the lesson URL." (the error window that shall be used to display this error message is the same error window used to display runtime and syntax errors). If the user opens the "Open Lesson..." window again, then the contents of the URL entry box shall be the same as the last time the window was opened.

Ý3.6.2: When the user has not completed a lesson successfully and they choose the "Check Lesson..." menu item, the following dialog box shall be shown:

When the user has completed the lesson successfully and they choose the "Check Lesson..." menu item, then the following dialog box shall be shown:

3.6.3: If the user chooses the "Save As Lesson..." command, then the following sequence of dialog boxes shall be shown:

If the user chooses "Cancel", then this dialog box shall be dismissed and the saving of the lesson shall be aborted. If the user chooses "OK", then the next window shall be displayed:

At this point, the user should choose "Save As..." from the "File" menu of their browser to save the lesson to their local hard drive, or close the window if they want to cancel.

3.6.4: If the user chooses the "Start Lesson Over..." menu item from the "File" menu, then the following dialog box shall be displayed:

If the user chooses Cancel, then the dialog box shall be dismissed and nothing else shall happen. If "Start Over" is chosen, then the program shall be returned to the state when the lesson was first loaded, with the locations of nodes and links set appropriately.

3.7: Popup windows related to the Commands Menu:

3.7.1: If the user chooses "Clear All...", then the following dialog box shall be displayed:

If the user chooses "Cancel", then the dialog box shall be dismissed and nothing else shall happen. If the user chooses "Clear All", then the dialog box shall be dismissed and the program shall be returned to its original starting state (i.e., the state the program is at when it is first launched).

3.8: Popup windows related to the Loop menu:

3.8.1: If the user chooses "For Loop...", then the following window shall be shown:

3.8.2: If the user chooses "While Loop...", then the following dialog box shall be shown:

For interface specifics regarding loop control boxes, see Section 4.

3.9: Popup windows related to the Help menu:

3.9.1: If the user chooses "About C++ Pointers", then the following shall be displayed (shown 2:1 scale; click on it to see a full-scale copy):

A picture of the software engineering team shall appear in the area labeled "(Group picture goes here)".

3.9.2: The User Documentation shall appear in an HTML browser window that fills the screen, which should have this general form (shown 2:1 scale; click on it to see a full-scale copy):

"C++ Pointers Documentation" shall be the title of the Web page, with the text "C++ Pointer Visualization Tutorial User Documentation" at the top and centered in Largest Heading format, with the text "Table of Contents" centered and one line below the title in Large Heading format. The table of contents shall be two lines below the text "Table of Contents" in an outline format formed with hot links to the appropriate sections of the user documentation. The table of contents shall be flush with the left side of the Web page, with indentations in the outline where appropriate (see User Documentation for the exact text of the outline).

4. Loop Control Interface:

4.1: If the user presses the "Return" key when the text entry cursor is in one of the lines, then the text entry cursor shall advance to the line with the next highest number and highlight the entire line. The cursor shall wrap around to the loop control statement if the cursor were on line 6 when "Return" was pressed. If this happens, then the loop control statement shall become highlighted.

4.2: The "Command Being Executed:" box in the main window shall be disabled when the user is working with loops. If the user closes the loop box and chooses "Undo" from the "Commands" menu, or if the loop runs to completion, then the "Command Being Executed:" box in the main window shall be enabled.

4.3: No statements are checked until the user clicks the "Run" or the "Step" button. Each statement shall be checked as each line in the loop gets executed. If a syntax error is found in one of the lines during execution, then the action of the loop so far shall be undone and the error shall be presented to the user, along with the line number of the error. Note: this style of syntax checking and line execution is like that of an interpreter, as opposed to a compiler (Section 4.3.1 shall override this section if Section 4.3.1 is implemented).

Ý4.3.1: The syntax of all the lines is checked immediately after the user clicks on either the "Step" or "Run" button. If any errors are found, then the error message shall be displayed and the user shall be allowed to fix the error. When the following conditions are satisfied, then the user shall be allowed to step or run the loop statements: all the lines in the loop box parse correctly, there is a loop control statement, and there is at least one statement in the loop body. The "Step" and "Run" buttons are initially disabled when the loop box is initially opened. If the user chooses either the "Step" or the "Run" button, then the "Step" and "Run" buttons shall be disabled, and the commands in the loop body and the loop control statement (i.e., all the lines in the loop box) shall be disabled (i.e., the lines shall become uneditable). Note: this style of syntax checking and line execution is like that of a compiler, as opposed to an interpreter.

4.4: Assuming all the lines in the loop box parse correctly: if the user chooses "Run", then the main browser window shall be brought to the front, and the loop shall begin execution immediately. If the user chooses "Step", then the loop control statement shall be copied to the command line text entry field, and the main browser window shall be moved in front of all other windows. The user must then go back to the loop box to click either "Step" or "Run". Each subsequent click on "Step" shall cause the statement that is currently in the command line text entry field to be executed, and the next line to be executed shall be copied to the command line text entry field. The main browser window shall also be moved in front of all other windows. If the user chooses "Run" after stepping many instructions, the program shall clear the command line text entry field, bring the main browser window to the front, and execute the rest of the loop. If the loop runs to completion, either by stepping or running, then the loop box shall disappear.

4.5: If a runtime error occurs while in the loop, then the following things shall happen: the user shall be informed of the error, the loop dialog box shall remain on the screen after the user acknowledges the error window, the current state of the links and nodes in the work area shall be updated, and the "Step" and "Run" buttons shall become disabled. If the user closes the window at this point, then the action of the loop shall become undone. If the user chooses "Undo" from the "Commands" menu, either after a runtime error occurs or after the user has stepped through one or more instructions of the loop, then the following shall happen: the action of the loop shall be undone, the work area shall be updated with the current state of the links and nodes, the "Step" and "Run" buttons and all the text entry boxes in the loop box shall be enabled, and the loop box shall not be dismissed.

4.6: When the user chooses "For Loop..." from the "Loop" menu, the text that the user previously entered in the loop box shall appear in the loop box. The user needs to press "Return" on all the lines to re-parse the lines if the user wishes to run the loop again. When the user opens the loop box for the first time, then the text entry fields shall be empty. A similar action shall occur for the while-loop control box, except each loop box shall be treated independently. If the program is restarted using the "Clear All..." menu command from the "Commands" menu, then the text of the loop control boxes shall be cleared (i.e., the text saving feature of the loop boxes shall not survive beyond the "Clear All..." menu command).

ÝÝ4.7: When a syntax error occurs, the specific area of the error should be changed to the color blue (see below for some examples). If the error involves anything that is unbalanced (i.e., quotation marks, angle brackets, curly brackets, etc) or a missing semicolon, then the entire line shall be highlighted. Here are some examples of where a line should be highlighted when a compile-time error occurs (the place is also italicized to give it more emphasis in these examples):

p->nexr = NULL; (Error: undefined identifier)

while (p = NULL) { ... } (Error: unsupported operator)

if (q->next != NULL (Error: unbalanced parentheses)

5. Error messages:

5.1: The text "Runtime error: " shall appear before any runtime error message. The following are the text messages to all the runtime error messages, including a short description of when these errors occur:

5.1.1: If a node becomes unreachable, then the error "Memory leakage occurred" shall appear.

5.1.2: If the user attempts to execute a statement piece of the form "p->next" when "p" is uninitialized, then the error "Attempt to dereference an uninitialized pointer" error shall be issued; if "p" is NULL, then the program shall report the error "Attempt to dereference a NULL pointer".

5.1.3: If the user attempts to execute a statement of the form "delete(p)" when "p" is an uninitialized pointer, then the program shall report the error "Attempt to delete an uninitialized pointer"; if "p" is NULL, then the program shall report the error "Attempt to delete a NULL pointer".

5.1.4: If the user attempts to assign the data field of an IntNode a value greater than 999, then the program shall report the error "Number too large"; if the user attempts to assign the data field of an IntNode a value less than 0, then the program shall report the error "Number too small".

5.1.5: If the user attempts to allocate a new node and the maximum number of nodes has been allocated, then the program shall report the error "Out of memory".

5.1.6: If the user tries to allocate a new node, but a new link to the node cannot be allocated, then the program shall report the error "Node allocation failed: could not allocate a link to the node".

5.2: The text "Syntax error: " shall appear before any compile-time error message. The following are the text messages to all the compile-time error messages, including a short description of when these errors occur:

5.2.1: If a line does not end with a semicolon, except for flow control statements and braces (i.e., "if" and "while" statements, including "else" with the if-statement), then the program shall report the error "Semicolon expected".

5.2.2: If the keyword "else" is found without a corresponding "if" statement, then the program shall report the error "Else keyword found without an if-statement".

5.2.3: If a close-parenthesis appears in a line before an open-parenthesis, or too many close-parentheses exist, or not enough close-parentheses exist, then the program shall report the error "Unbalanced parentheses"; if angle brackets are unbalanced in a way similar to parentheses, then the program shall report the error "Unbalanced angle brackets"; if curly braces are unbalanced in a way similar to parentheses, then the program shall report the error "Unbalanced curly brackets".

5.2.4: If there is an uneven quantity of quotation marks, then the program shall report the error "Unbalanced quotation marks".

5.2.5: If the assignment operator appears in a flow control conditional expression instead of the equals comparison operator, then the program shall report the error "Illegal use of the assignment operator inside a flow control expression (i.e., you probably want to put \"==\" instead of \"=\" in the \"if\" or \"while\" statement)" (Note: this error can only occur in "if", "while", or "for" control expressions).

5.2.6: If the user enters a Boolean expression or a Boolean conditional that is too complex (see Section 4.10 for details), then the program shall report the error "Conditional too complex".

5.2.7: If the user enters a Boolean expression or a Boolean conditional that uses an unsupported operator except for the assignment operator (see Section 4.10 for details), then the program shall report the error "Unsupported conditional operator".

5.2.8: If the user enters an expression that contains an identifier that is unknown to the program (see Section 4.10 for defined identifiers), then the program shall report the error "Undefined identifier".

5.2.9: If a statement is too complex (see Section 4.10 for acceptable statements), then the program shall report the error "Statement too complex".

5.2.10: If the user attempts to assign a number to a string node (i.e., "p->data = 5;" when a string was expected), then the program shall report the error "Attempt to put a number in a StringNode"; if the user attempts to put a string in an IntNode, then the program shall report the error "Attempt to put a string in an IntNode".

5.2.11: If the user is working with string nodes but tries to allocate a new node using a statement of the form "p = new IntNode;", then the program shall report the error "Attempt to allocate a new string node using the type IntNode"; if the user is working with IntNodes but tries to allocate a new node using the StringNode type, then the program shall report the error "Attempt to allocate a new IntNode using the type StringNode".

5.2.12: The program shall report an error of the form "Attempt to use <PointerField> pointer in a <LinkType>" if the user attempts to use a pointer field that is not available for that particular "<LinkType>". If the user is working with singly linked lists, then "<LinkType>" is "singly linked list", and "<PointerField>" in this case shall get replaced by the appropriate illegal pointer field that the user tried to use, which can be either "prev", "left", or "right" for a singly linked list. If "<LinkType>" is "doubly linked list", then possible values for "<PointerField>" shall be "right" and "left". If "<LinkType>" is "binary tree", then possible values for "<PointerField>" shall be "next" and "prev".

5.2.13: If the user attempts a statement of the form "p->next = 5", then the program shall report the error "Attempt to assign an integer value to a pointer variable"; if the user attempts a statement of the form "p->next = "hi.", then the program shall report the error "Attempt to assign a string value to a pointer variable"; if the user attempts to execute a statement of the form "p->next = r->data", then the program shall report the error "Attempt to assign the pointer field with a data value"; if the user attempts a statement of the form "r->data = p->next", then the program shall report the error "Attempt to assign a pointer value to a \"data\" field".

5.2.14: If the user attempts a statement of the form "if (p->next == r->data)...", then the program shall report the error "Attempt to compare a data field with a pointer".

5.2.15: If an if-statement is nested in the "then" or "else" part of another if-statement, then the program shall report the error "Too much nesting of if-statements".

5.2.16: If a miscellaneous parsing error occurs, then the program shall report the general error "Not C++ compliant code or unrecognized code".

5.3: The text "Loop control runtime error: " shall appear before any runtime loop control error message. The following are the text messages to all the runtime loop control error messages, including a short description of when these errors occur:

5.3.1: After every 500 iterations in the while loop and for loop, the program shall report the error "Warning: a possible infinite loop may be occurring in the loop (<x> iterations have occurred so far). Do you want to exit the loop?", where <x> is the number of iterations that have occurred so far. An option to abort the loop or to continue execution shall be given to the user. The "Abort Loop" option shall dismiss the error box, and everything that normally happens when a runtime error occurs shall also occur here (see Section 4.5). Here is an example to be used as a guide:

5.3.2: After 10,000 iterations in the while loop, the program shall report the error "Maximum number of loop iterations has been exceeded (a maximum of 10,000 iterations are allowed)". This shall be treated like a runtime error (see Section 4.5). Here is an example to be used as a guide:

5.4: See the Specifications document for actions that are allowed and disallowed when errors occur. If an action is not allowed, then the default system beep shall be played.

5.5: An example of an error message window is provided as a guide (the example shows the memory leakage runtime error):

The text in the window shall wrap around if the message is too long to fit on one line.

Search engine sitemap created by AutoSitemap.com