IOL Functions oop344 20112

For the assignments in OOP344 this semester, you will work collaboratively in groups of 4 or 5 and submit your completed assignments as a group. You must choose the members of your group, give your group a "name" (any name will be acceptable provided it is respectful) and then send your instructor an e-mail danny abesdris with a list of the group member names, their learn id's and their group name. Each member of the group will be responsible for doing an equal share of the coding for all of the assignments submitted this semester. Your group will be responsible for allocating tasks to each group member.

The final submission (once your assignment is completed) must include comments (preceeding each function below), indicating which group member was responsible for the code as well as the date the code was written (adding multiple dates if the code was updated).

Assignment description

In class we have started to develop the following set of "Direct Console 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 (Matrix Linux System) and Windows (MS-DOS) platforms.

void iol_init(void)

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

void iol_end(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 iol_init( ) (defined above) must call this function before terminating.

int iol_rows(void)

Simply returns the number of rows on the screen.

int iol_cols(void)

Simply returns the number of columns on the screen.

void iol_clrscr(void)

Clears the screen, ensuring the cursor is left in the upper left corner of the screen.

void iol_flush(void)

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

int iol_getch(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 iol.h):

• UP_KEY - the value for the up arrow key
• DOWN_KEY - the value for the down arrow key
• LEFT_KEY - the value for the left arrow key
• RIGHT_KEY - the value for the right arrow key
• PGUP_KEY - the value for the page up (or previous screen) key
• PGDN_KEY - the value for the page down (or next screen) key
• ENTER_KEY - the value for the enter (or carriage return) key
• TAB_KEY - the value for the tab key
• BS_KEY - the value for the backspace key
• DEL_KEY - the value for the delete key
• HOME_KEY - the value for the home key
• END_KEY - the value for the end key
• ESC_KEY - the value for the escape key
• INS_KEY - the value for the insert key
• F1_KEY, F2_KEY, ... F12_KEY - the values for the F1 through F12 keys, respectively

void iol_movecur(int r, int c)

Positions the cursor at the row 'r' and column 'c' 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 iol_putch(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 iol_prnstr(const char* s)

Outputs the null-terminated string pointed to by 's', 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.

void iol_display(----)

 void iol_display(const char* str, int row, int col, int len)

This function displays the null-terminated string pointed to by "str" on the screen starting at row "row" and column "col", up to "len" characters. As with iol_movecur( ), 0 is the top row and 0 is the left-most column. If the string is longer than "len", then only "len" characters are displayed, otherwise, the entire string is displayed. If "len" is 0 or less, then the field length is considered to be the actual length of the string (i.e. the entire string is displayed). Afterwards, the cursor is positioned after the last character in the field. NOTE: On systems where output is buffered, this function should not flush the output buffer, and the results are undefined if the specified values indicate a field that does not fit on the screen.

int iol_edit(----)

int iol_edit(char* str, int row, int col, int fieldlen, int maxdatalen,
	     int* insertmode, int* offset, int* curpos, int IsTextEditor,
	     int ReadOnly)

This function allows the user to perform full screen editing of the null-terminated string pointed to by "str" at row "row" and column "col" on the screen. The parameter "maxdatalen" specifies the maximum length of the string "str". The parameter "fieldlen" specifies the length of the field in which editing is to be performed (visible area of "str"). The pointer "offset" points to an integer holding the index of the first character of "str" to be shown in the field. The pointer "curpos" points to an integer holding the position of the cursor in the field (0 is the first position). "insertmode" is a pointer pointing to an integer flag that is true (1) when insert mode on, and false (0) if not.

If any of the pointers, insertmode, curpos or offset is NULL then a local integer will be used instead. If local variables are used for any of insertmode, curpos, or offset, the default values are: 1 (insertmode), 0 (curpos), and 0 (offset).

Editing begins by displaying "str" starting at index "*offset", and the cursor will be placed at the value stored in "*curpos". NOTE: The following corrections should be made to "*curpos" and "*offset" in the event they hold invalid values before editing begins:

1. If "*curpos" is greater than or equal to the value of fieldlen,then change "*curpos" so that cursor is placed at the last position within the field.
2. If "*offset" is greater than the length of the string, then change "*offset" so the "last character of str" is hidden right before the first space in the field (see "IsTextEditor" section #1 for more about this).
3. If the cursor is past the last character of "str", then change "*curpos"

so the cursor is positioned after the last character of "str".

The cursor may never be positioned:

1. Before the start of the field.
2. More than one position past the last character in the string.
3. Beyond the end of the field.

Editing is terminated by pressing ENTER, TAB, UP, DOWN, PGUP, PGDN or any of the function keys (F1 to F12). Pressing ESCAPE will terminate iol_edit( ) and abort editing (i.e.) "str" will be set back to the originally value it had prior to editing.

Note that the conditions for termination are changed if the "IsTextEditor" flag is true (non-zero). See the "IsTextEditor" section for more details.

If "ReadOnly" has a true value (non-zero), then any attempt to change the content of "str" should end the function, returning the key pressed. Note that all other keys should work (Function and Non-ASCII keys). This flag (when true) makes the iol_edit( ) function "read only", however, the user may still scroll the text to the left or to the right.

The function returns an int identifying the key that was pressed to exit. This function uses the same key codes as iol_getch( ).

The function takes no action if the user tries to enter too many characters (i.e. if, for example, the string is in insert mode, or the cursor is positioned after the last character of a string that is full in overstrike mode). However, if the cursor reaches the end of the field and the string is not full, then after inserting, the string will be scrolled to the left, positioning the cursor right after the last character in the string.

This function handles at least the following special keys:

• LEFT - moves the cursor left one character. If the cursor is at the

beginning of the field and there is hidden data before the cursor, then the string shifts to the right instead.

• RIGHT - moves the cursor right one character. If cursor is at the end

of the field but not at the end of the string, then the string scrolls one character to the left.

• HOME - moves the cursor to the beginning of the string. This action scrolls

the string all the way to right if necessary (i.e. if there is hidden data at the beginning)

• END - moves the cursor to the end of the data in the string (i.e. just

past the last character in the string, scrolling to t left if necessary.

• DEL - deletes the character immediately to the right of the cursor

and moves all subsequent characters one position to the left.

• BACKSPACE - deletes the character immediately to the left of the cursor

and moves the rest of the field (including the cursor) one position to the left.

• TAB:

if IsTextEditor is false, TAB will simply terminate the function.

if IsTextEditor is true, TAB will insert CIO_TAB_SIZE number of spaces into

the string.

CIO_TAB_SIZE should be a #defined "tab size" value in iol.h (typically, 3, 4 or 8)

If CIO_TAB_SIZE spaces cannot be inserted into the string for any reason

then the tab should be ignored. (see "IsTextEditor" for more about this).

• ESCAPE - Terminates iol_edit( ) and aborts editing:

(i.e. "str" will be reset to the data it was originally storing when it was passed into the function.

• INSERT - this key toggles Insert/Overstrike mode.

In Insert mode, printable characters are inserted into the string, moving the remainder of the string to the right. In Overstrike mode, printable characters overwrite existing characters (if any).

NOTE: If you are past the end of the string, printable characters are

appended to the string (as long as the string isn't full) in either mode. Also note that, regardless of the mode, the cursor advances as printable characters are typed into the string.

Finally, if the cursor is at the end of the field, instead of the cursor moving to the right, instead, the characters are shifted to left.

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 string This 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.