IOL Functions oop344 20112

OOP344 | Weekly Schedule | Student List | Teams | Project | Student Resources

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.

• IsTextEditor:

• [Section #1] IsTextEditor and *offset

  If IsTextEditor is true, then the function is being used to edit textone line at a time. In this case, shifting a line to the left or right should not only cause the line being edited to be shifted, but also the rest of the lines in the text. To do this, iol_edit( ) should let the calling function know that a shift has occured. Since shifting essentially means modifying "*offset" when "IsTextEditor" is true, and that there are times when you find that "*offset" needs to be modified, you should terminate the function afterwards. With termination, the function should return the terminating key. Note that at the beginning of the execution of iol_edit( ), validating *offset may require the value of *offset to change. If so, make sure to correct the offset and then terminate the function before any editing happens returning the

default value of key.

• [Section #2]

1. The iol_edit( ) function always displays blanks in any the part of the field that is not occupied by the data in the string.
2. UNDER NO CIRCUMSTANCES DOES THE FUNCTION CHANGE ANY POSITION ON THE SCREEN OUTSIDE OF THE FIELD.

• [Section #3] IsTextEditor and ESCAPE

1. When "IsTextEditor" is true and the ESCAPE KEY is pressed, the function simply terminates (returning the ESCAPE key), but the editing is NOT to be undone.
2. If the dynamic memory allocation fails, quit the function returning -1.

• [Section #4] Others

1. Any normal printable key is simply placed into the string according to the rules outlined in the discussion of the INSERT key above (The keys from the space character to the tilde character in the ASCII table are considered "printable").
2. Like most C library functions, your iol_edit( ) may assume that it is the

calling program's responsibility is to ensure that the array is large enough to handle the specified number of characters, and that the starting screen position provides enough room (on the screen) for the field.

Selection Editor:

void iol_displayflag(-----)

void iol_displayflag(const char* format, int row, int col, int status)

This function allows the user to display a checkbox at row and col on the screen. the checkbox will be checked or unchecked based on the value of the "status" parameter (non-zero for checked 0 for unchecked).

The checkbox will be always shown using 3 characters (two surrounding characters and one character in the middle as the checkmark). If the status argument is zero, then instead of the check-mark a space will be printed on the screen.

The 3 characters held in the "format" array: format[0] and format[2] are the surrounding characters and format[1] is the check-mark. const char* format is used to specify the character used for the checkbox, so for example if the format argument is "[X]", then an unchecked checkbox will be

[ ]

and a checked checkbox will be

[X]

After the checkbox is displayed, the cursor is always placed under the check-mark (in centre).

int iol_flag(-----)

int iol_flag(const char* format, int row, int col, int* status, int radio)

iol_flag( ) allows the user to make a single true/false selection. "status" points to the status of the selection and can be zero or non-zero. If "*status" is initially set to anything other than zero, iol_flag( ) corrects the value to hold 1. "format" holds the shape of the checkbox as in the iol_displayflag() function.

iol_flag( ) begins the selection by displaying the checkbox according to its "*status" (Remember that the value of "*status" is corrected before the editing begins). Then the function waits for the user input.

• If the user enters any of the printable keys (' ' < key <= '~') excluding the space key, it should be ignored (no action taken). If the user enters any of the function keys, the function is terminated returning that key.
• If the user input is a SPACE:

1. If the "radio" parameter is true, then the "*status" is set to one, the checkbox is displayed, and the function is terminated returning the keycode for the space character.
2. If the "radio" parameter is false, then the value of "*status" is toggled (changing from 0 to 1 or 1 to 0), the checkbox is displayed, and the function terminated returning the space key.

void iol_displayMenuItem(----)

void iol_displayMenuItem(const char* format, const char* menuItem, int row,
			 int col, int len, int status)

Allows the user to display a menu-item at row and col on the screen with a width of len. The menu-item will be surrounded by either format characters (when "status" is zero) or by spaces (when "status" is non-zero).

The menuItem argument will be always shown surrounded by two characters.

• If "status" is zero, then a space, followed by the menuItem, followed by another space will be shown at row and col on the screen. If the length of the menuItem is less than (len - 2), then enough spaces will be printed to make up the difference; making the entire field (len - 2) characters.

For example:

"Hello"

with 10 as len will be displayed as:

" Hello    "

• If "status" is non-zero, then format[0], followed by the menuItem, followed by format[1] will be shown at row and col on the screen.

If the length of the menuItem is less than (len - 2), then enough spaces will be printed to make up the difference; making the entire field (len - 2) characters.

For example:

"[Hello]"

with 10 as len and "[]" as format chars, will be printed as :

"[Hello   ]"

After the Menu item is displayed, the cursor is always placed under the first character of menutItem. (position row and col + 1)

int iol_menuItem(----)

int iol_menuItem(const char* format, const char* menuItem, int row,
		 int col, int len, int* status)

iol_menuItem( ) allows the user to make a single item selection. "*status" points to the status of the selection (zero or non-zero). If "*status" is initially set to anything but zero, iol_menuItem( ) corrects the value so that it is set to one.

"*format" holds the shape of the selection indicator as outlined in the iol_displayMenuItem( ) function.

iol_menuItem( ) begins the selection by displaying the menu item according to its "*status" using iol_displayMenuItem( ) (Remember that the value of "*status" is corrected before the editing begins). The function waits for the user input.

• If the user presses any of the printable keys (' ' < key <= '~') excluding the space key,

then no action is taken and the function waits for the user to press another key.

• If the user presses any of the non-ASCII keys, the function is terminated

returning that key.

• If the user presses the SPACE key, then the *status is set to one, the menu item

is displayed, and the function is terminated returning the ASCII value of space character.

Submission Instructions: These functions are to be declared in a file named iol.h along with the symbolic key codes mentioned above. The functions are to be defined in a file named iol.c. They must compile and work properly in both the MS-DOS environment (using the Visual Studio 2010 C/C++ compiler) and the UNIX (on Matrix) environment (using GNU C/C++ compiler). At most only one or two lines of iol.h should need to be modified when changing from one environment to the other.

Whichever terminal program (ssh only) 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 ssh 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.

Late Submission Penalty: 1 letter grade per week.

Due Date: Thursday June 16, 2011 @ 11:59:59 p.m. This assignment is worth 5% of your final grade in OOP344 this semester. GOOD LUCK!