Application-Independent Key Meanings and Their Use
Certain keys and combinations of keys should be handled by any application. Some are taken care of by the operating system (for example, Action-Finish), but others are the responsibility of the application. Table 7-1 describes the common key usage convention for CTOS applications.
Table 7-1. Application-Independent Key Meanings (Page 1 of 2)
Key Sequence
Action-Finish
Usage
Application takes no action, unless it has disabled Action-Finish. Operating System terminates application.
Tips for the Application Writer 7-3
Table 7-1. Application-Independent Key Meanings
(Page 2 of 2)
Key Sequence
Cancel
Code-"feature key"
F1 to F10
Finish
Go Help Next
Shift-Code-"feature key"
Usage
Stop current operation, and return to previous prompt, menu, or state.
Perform the application-defined operation specified by the
Code-"feature key" combination.
Display menu, or prepare to perform an operation. Wait until the Go key is pressed to perform the operation.
Display exit prompt, and wait for the Go key to be pressed.
Perform the requested action.
Display help information.
Move to the next text field.
Perform the application-defined operation specified by the
Shift-Code-"feature key" combination.
Application-Dependent Key Use Conventions
Certain keys and key combinations may not be needed by all applications, but should perform a consistent function when they are used. For example, not all applications need to implement screen scrolling, but those that do should use the scrolling keys in a consistent manner.
Table 7-2 describes the usage conventions for these keys.
7-4 eTOS/ Open Programming Practices and Standards - Part I
Table 7-2. Application-Dependent Key Meanings (Page 1 of 2)
Key Sequence Usage
Arrow Key Move the cursor one character position
(or one line) in the direction of the current cursor position and a previously-marked cursor position. Prepare to perform an editing function on the marked block of text.
Move the cursor as far as it can go in the direction of the arrow. For example, to the end of the current line or to the top of the current video frame.
Unmark a previously-marked block of text.
Insert New Page character (OCh).
Scroll the contents of the screen up!
down one full screen.
Copy a previously-marked block of text to the current cursor location. Dis-places, but does not destroy existing text.
Delete the single character or the marked block of text at the current cursor location.
Highlight the character at the current cursor position, and prepare to perform an editing function on it.
Move a previously-marked block of text to the current cursor location. Dis-places, but does not destroy existing text.
Tips for the Application Writer 7-5
Table 7-2. Application-Dependent Key Meanings (Page 2 of 2)
Key Sequence
Next Pagel Prev Page
Scroll Upl Scroll Down
Shift-Arrow Key
Shift-Scroll Upl Shift-Scroll Down
Usage
Scroll the contents of the screen upl down one full page or one full screen.
Scroll the contents of the screerl upl down one line.
Move the cursor five character positions (or five lines) in the direction of the arrow.
Scroll the contents of the screen upl down five lines.
Keyboard Events an Application Must Handle
An application should make a reasonable response to any input it receives from the keyboard. If the input is not what the application expects, it should beep. It should also display an error or prompt message, if one is not already displayed.
Screen Layout Conventions
While no strict guidelines currently exist for an application's screen layout, certain conventions have been widely used historically. Following these conventions promotes a consistent look between applications.
Function Key Menus
If an application uses function keys, it should provide a function key menu on the screen. The function key menu should appear at the bottom of the screen, so that it is easy to relate the menu to the function keys on the keyboard. If an application needs to use the entire screen, it should display its function key menu when the Help key is pressed.
7-6 eTOS/Open Programming Practices and Standards - Part I
For an example showing how to display a function key menu on the screen, see "Video Management - V AM and VDM" in Chapter 2.
Help
Applications should provide some form of help to the user. At the least, the application should display a list of commands or function key meanings when the user presses the Help key.
Listing 7-1 shows a V AM procedure which displays a help window when called. The procedure sets up its window, displays a message, then prompts the user for a response. In this case, the only accepted response is Cancel, which causes the routine to restore the previous contents of the screen and then return to the caller.
/* display a help message */
void PutHelp() [
char *pHelpMsg
=
"You Pressed the Help key. Press Cancel to continue.";Word sHelpMsg = 51;
Word sFrameBuf;
char inchar;
/* frame buffer is number of chars in frame */
sFrameBuf
=
3 * Cols;CheckErc(InitVidFrame(HELPFRAME,0,Lines-6,Cols, 3,0,0,0, 0,0»;
CheckErc(QueryFrameCharsAndAttrs(HELPFRAME, 0, 0,
pbTextBuf, sFrameBuf, pbAttrBuf, sFrameBuf»;
CheckErc(ResetFrame(HELPFRAME»;
CheckErc(PutFrameChars(HELPFRAME, 0, 0, thinline, Cols»;
CheckErc(PutFrameChars(HELPFRAME,0,2,pHelpMsg,sHelpMsg));
CheckErc(ReadKbd{&inchar) );
while{inchar != Cancel) [ Beep() ;
CheckErc(ReadKbd(&inchar) );
)
CheckErc( PutFrameCharsAndAttrs(HELPFRAME, 0, 0,
pbTextBuf, sFrameBuf, pbAttrBuf, sFrameBuf) );
Listing 7-1. Sample Help Window Display Procedure
Tips for the Application Writer 7-7
Status Information
Status information that applies to an entire program, such as the time of day, should be displayed at the top of the screen. Status information that applies to a particular video frame, such as a filename in an editor, should be displayed at the top of that video frame.
Creating An Executive Screen
Many utilities use the same screen display as the Executive for their user interface. Such utilities can use the CreateExecScreen procedure to set up the screen, rather than implementing the setup code themselves.
The CreateExecScreen procedure takes three parameters: the size of the video character map, the number of columns on the screen, and the number of lines on the screen. These parameters should NOT be hard-coded in the program, but should instead be retrieved by the QueryVidHdw procedure. Using QueryVidHdw allows the program to work with displays that have varying numbers of rows and columns.
Listing 7-2 shows a code fragment that sets up an Executive-type screen display using CreateExecScreen.
/* first find out the screen dimensions */
CheckErc(QueryVidHdw(&rgbVidHdw, sizeof(rgbVidHdw) »i nLines
=
rgbVidHdw[l]inCols
=
rgbVidHdw[2]i/*now reset the video and get the size of the char map */
CheckErc(ResetVideo(nCols, nLines, TRUE, BLANK, &sMap»i /* now create the executive screen */
CheckErc(CreateExecScreen(sMap, nCols, nLines»i
Listing 7-2. Creating an Executive Screen
The Executive screen consists of three display frames, numbered 0 through 2. Each is described below.
7-8 eTOS/Open Programming Practices and Standards - Part I
• Frame 0 - the user input frame
This is the primary frame, and consists of the entire screen except for the top three lines. All user input and user output should be displayed in this frame.
• Frame 1 - the status frame
This frame consists of the top two lines of the screen. This frame should display status information, such as the current path and the current date and time.
• Frame 2 - the event frame
This frame consists of the third line of the screen, and generally contains a horizontal line separating the status frame from the user input frame. This frame is used to display system events, such as mail notification.
After the call to CreateExecScreen, these frames are initialized, but empty. It is the application's responsibility to fill in the frames with the appropriate information.
To be consistent with other applications that use the Executive screen, the application should display its name in the upper left-hand corner of the status frame. It should also display the current date and time in the lower right-hand corner of the status frame.
If an application requires a customized video display, see "Yideo Management - YAM and YDM" in Chapter 2, "Basic Input and Output."
Cleanliness
Programs should observe general programming cleanliness guidelines, so that future enhancements to the operating system do not break them.
Guidelines for Screen Handling
In most implementations of CTOS, it is possible to get the address of the memory in which the screen image is stored, and to write directly to video memory. It is common practice in some operating systems, such as MS-DOS, for applications to write directly to video memory.
Tips for the Application Writer 7-9
Portable CTOS applications should never write directly to video memory.
They should instead use the V AM and VDM calls to display information on the video screen. This allows compliant applications to continue executing in the background when they are used with a context management shell, such as the Context Manager. Applications that write directly to the screen execute only when they are the foreground process.
File Suffix Conventions
Applications that have special-purpose files should append a descriptive suffix to those files. Table 7-3 describes some filename suffixes commonly used by application programs for their files.
Filename Suffix
. bin . config .fls
. lib . Ist -Old
. sub . sys .tmp
Table 7-3. Common File Suffixes (Page 1 of 2)
Usage
A binary message file . A configuration file .
A file that contains a list of file specifications .
A library of object module procedures . A listing file.
The original version of a file that is currently being modified .
A submit file.
A system file .
A temporary file created by an application.
7-10 eTOS/Open Programming Practices and Standards - Part I
Filename Suffix
.ts
. txt
Table 7-3. Common File Suffixes (Page 2 of 2)
Usage
A typescript file, used for error recovery.
A text file .