Requirement	User Interface
Section	3.2.3.1
JIRA Task	EIR-62 - Getting issue details... STATUS EIR-67 - Getting issue details... STATUS

Reviewed For	Date
Conventional spacing between sections	2016-08-31

Introduction

The user interface (UI) of the Classic Analysis module consists of the Command Explorer, which displays a "menu" of commands organized hierarchically by function; the Program Editor, which receives commands generated by the Command Explorer dialogs or commands entered directly by the user; and a panel that displays output from the commands as they are executed. Having the command browser (the Explorer) coupled to a command shell allows the user to choose from the functional repertoire of Classic Analysis and be prompted for parameters as the system records (and executes) the commands as they would appear in a program. The sequence of commands is, in fact, a program that can be modified and/or rerun interactively or in batch mode, independently of the UI.

Interface and User Interaction

Overview

The user interface to the Epi Info™ 7 Classic Analysis module consists of four components:

Command Explorer contains a list of available data processing commands organized into folders by function and command type,
Program Editor is a command shell with error log that receives code generated using the Command Explorer UI or entered manually by the user and executed by the command interpreter,
Output Window captures and displays parameters, status and analytical output (as appropriate for the command) in HTML format and renders it in text and graphics, and
Message Area captures and displays error messages and diagnostic output including syntax errors from the program editor and stack traces from Java exceptions in the application itself.

Functional Requirements

In the following requirements, text in fixed-pitch font, surrounded by square brackets (e.g.: [Example]) represents a button in the interface for the associated command. Commands accessed using menus are represented by regular text connected by arrows (e.g.: File→Example).

The Command Explorer shall enable the user to:
1. browse the available commands,
2. select a command for use with the current dataset,
3. supply required and optional parameters/arguments to the command via a graphical user interface (GUI) known as the command definition dialog, and do one of the following:
  1. save the command, parameters and arguments to the program editor [Save Only],
  2. trigger the command's execution and save the command, parameters and arguments to the program editor [OK],
  3. clear all input fields and reset the GUI to its initial state [Clear],
  4. close the command definition dialog and do nothing [Cancel],
The Program Editor shall enable the user to:
1. manually enter commands;
2. enter comment lines prefixed with three asterisks (e.g., "*** This is a comment");
3. load commands from the current project or an external file [Open Pgm], File→Open Pgm... ;
4. save commands to the current project or an external file [Save Pgm], File→Save Pgm or File→Save Pgm As... ;
5. execute a subset of the commands in the editor (by selecting several lines at once using mouse or arrow keys) [Run Commands];
6. execute all commands in the editor [Run Commands];
7. clear the Program Editor [New Pgm], File→New... ;
8. print the contents of the Program Editor buffer, File→Print;
9. modify the "page setup" (page orientation, margins, etc.), File→Page Setup... ;
10. undo and redo previous commands, Edit→Undo and Edit→Redo, respectively;
11. cut, copy and paste, Edit→Cut, Edit→Copy and Edit→Paste, respectively;
12. find a string, Edit→Find, with the following options:
  1. find the first occurrence starting from the beginning of the buffer,
  2. find the next occurrence starting from the the current cursor position,
  3. find the last occurrence in the buffer,
  4. render the search case sensitive, and
  5. find the string, only if it constitutes an entire word (i.e., the string is bounded by whitespace or line terminus);
13. find a string and replace the first instance with another string, Edit→Replace, with the following options:
  1. render the search case sensitive,
  2. find the string, only if it constitutes an entire word, and
  3. find and replace all instances of the string in the entire buffer;
14. select the entire contents of the Program Editor buffer, Edit→Select All,
15. move the cursor to the beginning of the program (buffer), Edit→Program Beginning,
16. move the cursor to the end of the program (buffer), Edit→Program End, and
17. toggle insert command at cursor (determines where commands are written when the command definition dialog closes), Edit→Insert Command at Cursor;
18. modify the following characteristics of the Program Editor font, Fonts→Set Editor Font:
  1. base font
  2. font style (regular, italic, bold, condensed, etc.),
  3. size in points,
  4. toggle strikeout,
  5. toggle underline,
  6. select script (e.g.: "Western", "Central European", etc.; support for non-"Western" scripts varies by font).
The Output Window shall:
1. immediately before recording the output of each READ command,
  1. close the sequentially-numbered output record file ("<InstallDir>\Output\output1.html", in a new installation, by default), and
  2. increment the output record file name, then create and open a file (in this case, "output2.html").
2. display a cumulative record of:
  1. command and parameters (for most commands generating tabular or graphical output), and
  2. command output (tables, text, graphics).
3. organize the output of individual commands into sections with anchors enabling the user to navigate between them.
4. have a history function that presents the output sections (described in c.) in a table with columns containing:
  1. timestamp,
  2. command string hyperlinked to the corresponding output section (URL containing the file system address and section anchor), and
  3. name of the file containing the output displayed in the output window.
The Message Window shall:
1. alert the user to errors that occur during command execution, and
2. allow for copying the contents of the message window into the Clipboard for using in another document.

Future Development

Functional Requirements

Enable the user to:

select a statement from the Program Editor and
1. using one of the following mechanisms:
  1. selecting "Open Command Dialog" from the right-mouse-button menu,
  2. typing a Ctrl+Key combination (e.g., Ctrl+E),
  3. choosing a button from the Program Editor panel, or
  4. choosing an item from the Program Editor menu (e.g., Edit→Open Command Dialog),
2. open the corresponding dialog for the command as if the command were chosen from the Command Explorer,
3. set or populate all elements of the dialog implied by the parameters and arguments of the selected statement,
4. allow the user to modify the current settings, and
5. continue using the dialog as normal to:
  1. execute the command with the new setting and write the revised statement to the Program Editor [OK],
  2. do not execute the command and write the revised statement to the Program Editor [Save Only],
  3. close the dialog and do nothing [Cancel],
  4. reset the dialog to its default settings [Clear], or
  5. open the online User Guide to the corresponding Command Reference page [Help].
execute statements in the Program Editor with a button and hot key (e.g.,[Step] and F5, respectively) that shall:
1. begin by executing one statement on the line indicated by the current cursor position,
2. on completion, the cursor shall move to the beginning of the next statement, and thus will
3. enable the user to step through a program, line-by-line (statement-by-statement)^[1].
print a program or the contents of the Program Editor with control over the page layout, including:
1. left, right, top, and bottom margins,
2. page orientation, portrait and landscape,
3. page header and footer, including page numbering, and
4. line wrapping^[2].
initiate a Find and Replace operation in the Program Editor in which:
1. the editor will skip to the next occurrence of the query string, highlighting the found text, then
2. stop and prompt the user to do one of the following:
1. 1. accept the replacement at that location,
  2. skip the replacement at that location,
  3. replace all instances of the string in the remainder of the document (without stopping further), or
  4. cancel the current Find and Replace operation,
2. then, in cases 1 and 2, return to step i, or
3. in cases 3 and 4, return to the Program Editor.

Notes:

Normally, the next statement begins on the next line. However, some statements, such as RECODE or the IF-THEN-ELSE construct, can span multiple lines and are executed as a unit.
In Epi Info™ 7.2, line wrapping is notenabled, causing long lines to disappear off the right margin.

Browser not supported