OOP344[ABC] Winter 2006 [061] Assignment #1
Description:
In class we have started to develop the following set of "Direct Terminal I/O" C functions, designed to provide a platform independent interface for writing full-screen programs, including such features as cursor positioning, directly capturing keyboard keys as they are pressed, displaying text, and text field editing among others.

In this first assignment you will write several functions that will allow you to do full-screen editing on both the UNIX (IBM AIX System) and Windows (MS-DOS) platforms.

void dt_start(void)
Initializes the full screen routines. This should be called before calling any of the other "dt" functions (and may not be called again before dt_stop( ) is called to stop using the full screen rountines).

void dt_stop(void)
Shuts down the use of the screen control routines, and ensures that the cursor is not left in the middle of the screen. Note: A program which has called dt_start( ) (defined above) must call this function before terminating.

int dt_rows(void)
Simply returns the number of rows on the screen.

int dt_cols(void)
Simply returns the number of columns on the screen.

void dt_clear(void)
Clears the screen, ensuring the cursor is left in the upper left corner of the screen.

void dt_update(void)
Ensures that any screen output that has been sent to the screen actually gets there (i.e. flushes the screen output buffer).

int dt_getkey(void)
Flushes the screen output buffer, waits for a key to be pressed and returns an int value uniquely identifying the key pressed. Note that the value for each non-ASCII key is system dependent, but the following symbolic names should be set up appropriately (in dtio.h):

UP - the value for the up arrow key
DOWN - the value for the down arrow key
LEFT - the value for the left arrow key
RIGHT - the value for the right arrow key
PGUP - the value for the page up (or previous screen) key
PGDN - the value for the page down (or next screen) key
ENTER - the value for the enter (or carriage return) key
TAB - the value for the tab key
BS - the value for the backspace key
DEL - the value for the delete key
HOME - the value for the home key
END - the value for the end key
ESC - the value for the escape key
INS - the value for the insert key
F1, F2, ... F10 - the values for the F1 through F10 keys, respectively

void dt_cursor(int row, int column)
Positions the cursor at the row and column specified, where row 0 is the top row and column 0 is the left-most column. Note that the results are not defined if the row or column is invalid. Note also that on systems where output is buffered, this function does NOT flush the output buffer.

void dt_putchar(int c)
Outputs the character, with the ASCII code stored in 'c', at the current position on the screen. This function advances the cursor by one position, although the results are system dependent if the cursor is already at the right edge of the screen. Note that on systems where output is buffered, this function does not flush the output buffer.

void dt_putstring(char *sp)
Outputs the null-terminated string pointed to by 'sp', starting at the current position on the screen. Afterwards, the cursor must be positioned just after the last character that was displayed. The results are not defined if the length of the string exceeds the available space left on the current line of output. Note that on systems where output is buffered, this function does not flush the output buffer.

int dt_box(int row, int col, int l, int h,
char edge, char top_btm, char ls_rs)
This function displays a box that will be used to frame a text field on the screen. The box must be drawn starting at coordinates 'row' and 'col', be 'l' and 'h' units in length and height respectively, and be comprised of the characters 'edge' (for all 4 corners), 'top_btm' (for the top and bottom lines), and 'ls_rs' for the left and right sides. For example, the function call dt_box(2, 3, 10, 3, '+', '-', '|'), would draw the following box (excluding contents) starting at row 2 and column 3:

0123456789012
1
2 +--------+
3 |abcdefgh|
4 +--------+
The function returns a true value if there is sufficient space to draw the box on the screen, and a false value otherwise. Note how a box which is 10 units in length, can only surround an 8 character text field!

void dt_draw(char *sd, int row, int col, int len)
This function is used to display a text field containing the string 'sd' on the screen.

'sd' is the null-terminated string to be displayed

'row' and 'col' specify the starting position on the screen where the string should be displayed. Assume that (row 0 and col 0) is the top left corner of the screen.

'len' is the maximum number of characters to be displayed. Note that the number of characters in the string could be more or less than 'len'.


int dt_edit(char *se, int slen, int row, int col, int flen, int *start, int *offset, int *insert, int ctype)
This function is used to edit the null-terminated string 'se' in a field.

'se' is the null-terminated string to be edited.
'slen' is the maximum length of the string 'se' (not including the null character).

'row' and 'col' specify where this field is to be placed. Assume that (row 0 and col 0) is the top left corner of the screen.

'flen' is the width of the field (i.e. the maximum number of characters that this field can display).

'*start' is a pointer to an integer that indicates where in the field the cursor should initially be located when the function is called. You may assume that this pointer will not be NULL and the value passed will be valid for this field.

'*offset' is a pointer to an integer that indicates where within the field the first character is to be displayed. You may assume that this pointer will not be NULL and the value passed will be valid for this field (see example below). Suppose the string passed to this function is "Lord Of The Rings". The following describes what to display given different offsets:

*offset of 0
+-----------------------+
|Lord Of The Rings |
+-----------------------+

*offset of 5
+-----------------------+
|Of The Rings |
+-----------------------+

'*insert' is a pointer to an integer indicating the insert/overstrike mode to be used. A true value indicates that insert mode is "on". A false value indicates that overstrike mode is "on". See the table below for an explanation of the two modes.

'ctype' is an integer that holds a numeric value which indicates the type of characters this field is permitted to accept (see below for values and allowed character types).

Value: Permitted Characters:
0 No characters of any kind permitted.
1 All characters permitted.
2 Only binary digits (0 and 1) permitted.
4 All numeric digits (0 to 9) permitted.
8 Only Octal digits (0 to 7) permitted.
16 Only Hexadecimal digits (0 to 9 and A to F) permitted.

Editing begins with the string being displayed according to the value pointed to by offset. The cursor should be placed at the position in the field indicated by the value pointed to by start. Cursor location is numbered starting from 0. Editing of the string can then occur (see below for details).

The function ends when one of the following keys is pressed: ENTER, TAB, ESCAPE, UP, DOWN, PGUP, PGDN,
or any of the function keys F1 to F10.

If the ESCAPE key is pressed, any changes made to the string during editing should be undone so that the string is reset to its original form, '*start' and '*offset' must be reset to their original values and the field must be redisplayed using the original characters contained within the string pointed to by 'se' when the function was first called.

If any key other than ESCAPE is pressed, the function should simply terminate returning the integer code for the key that caused the function to end. The editing process involves allowing the user to interactively insert/overstrike characters in the string, and move the cursor across the field. Printable characters modify the string based on the cursor position relative to the string. However, because only 'flen' characters of the string can be displayed, editing may involve scrolling the string itself.

Note, you are not permitted to edit a string beyond its allowable size. If the string is already full and the user presses keys that would increase the string's size, the keypress should simply be ignored. The cursor is never allowed outside the bounds of the field as defined by 'col' and 'flen'.

It is also not permitted to position the cursor more than one character past the last character in the string.

The following is a field in an HTML document. You can use it to observe some basic properties of what a field is. However, because this is just an HTML field, it will not handle all the special keys that your program must handle so use it ONLY as a guide but READ THE SPECS CAREFULLY!!!

Type some text in this field:


The following table describes what each of the special keys is required to do:
INS
Toggles the insert/overstrike mode. If the mode is insert, the characters typed are inserted into the string at the current cursor position. If the mode is overstrike, the character typed overwrites the character at the current cursor position. The cursor in both cases should be placed one position past the character that was added. Examples:

Suppose that the field is as follows (underlined char indicates the cursor location): 

This is the string
Suppose the key X is pressed.  The following shows what the different modes would change the field to

        Insert Mode           Overstrike Mode

This iXs the stringThis iX the string
LEFT
Moves the cursor to the left by one character if possible.
RIGHT
Moves the cursor to the right by one character if possible. Note that the cursor cannot move more than one character past the last character in the string. The following describes the right most possible location for the cursor in the following field.
string ends here_
HOME
Moves the cursor to the very beginning of the string, scrolling the string if necessary.
END
Moves the cursor to one character past the last character in the string, scrolling if necessary. 
move it past here_
BS
Moves the entire field starting at current cursor location one character to the left if possible. The character just to the left of the cursor is deleted. Note the positioning of the cursor after the operation. See below for an example.

Before

The field of text

After

The fied of text
DEL
Deletes the character at the current cursor location and moves all characters right of it one character to the left if possible. Note the positioning of the cursor after the operation. See below for an example.

Before

The field of text

After

The fiel of text

UNDER NO CIRCUMSTANCES DOES THE FUNCTION CHANGE ANY POSITION ON THE SCREEN OUTSIDE OF THE FIELD.

These functions are to be declared in a file named dtio.h along with the symbolic key codes mentioned above. The functions are to be defined in a file named dtio.c.

They must compile and work properly in both the MS-DOS environment (using the Borland C/C++ compiler) and the UNIX environment (using IBM's C/C++ compiler). At most only one or two lines of dtio.h should need to be modified when changing from one environment to the other.

Whichever terminal program (telnet) you are using must be capable of handling all of the keypresses properly (note that many do not!!).

It is highly recommended that you use putty as your telnet client.

See the "PuTTY" link on my webpage, under the "resources" folder.

Submission Instructions:
A main( ) program will be released shortly before the due date to test that you have written your functions correctly. You are encouraged to write your own test code in the meantime however. If you wait for the assignment main( ) to be released before you start testing your code in detail, you will likely not have enough time to finish this assignment.

Please follow your professor's instructions and guidelines before submitting your assignment.

In addition, you must make your AIX executable accessible to your teacher, in a file called a1main in your home directory. (Note that your instructor is not in the student group, so that you may deny "group" access, but allow "other" access, allowing your instructor to run it, without other students being able to copy it.)

This can be accomplised by changing permissions on this file as follows:

chmod 701 a1main

This will give this file permissions of:

-rwx-----x 1 userid students size Jan 14 20:29 a1main

The base mark for a program that meets all of these specifications and has no hidden logic flaws will be 90%. To earn additional marks, your code must show elements of innovation WITHOUT VIOLATING THE SPECS. Failure to meet the above specs may result in a 2 letter grade penalty and having to resubmit your assignment. Late submissions will receive a one letter grade penalty, so it is better to be late with a correct solution than to rush and be on time with an incorrect solution.

Due Date: Friday February 3rd, 2006 @ 11:59:59 p.m. This assignment is worth 10% of your final grade in OOP344 this semester. GOOD LUCK!