1
edit
Changes
m
Edited some punctuation, spelling and grammar.
<br />
Allows the user to perform full screen editing of the null-terminated string pointed to by '''"str"'''. The parameter '''"row"''' identifies the row of the screen for the field (0 is the top row), while '''"col"''' indicates the starting column of the field (0 is the left-most column). 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"''', 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) for insert mode being on, or false (0) for insert mode being off.<br />
''If any of '''insertmode''', '''curpos''' or '''offset''' is <u>NULL</u> then a local integer variable 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 with the display of '''"str"''' from where '''"*offset"''' is referring to, and the cursor will be standing at the position which '''"*curpos"''' is indicating.
NOTE: Following The following corrections should be done to '''"*curpos"''' and '''"*offset"''' in case they hold invalid values before editing begins:
# If '''"*curpos"''' exceeds the value of fieldlen, correct the '''"*curpos"''' so that cursor stands at the last position inside the field.
# If '''"*offset"''' is greater than the length of the string, set the '''"*offset"''' so the “last character of str” is hidden right before the first space in the field. (See[[OOP344 BIO 20101#IsTextEditor:|IsTextEditor]] for more)
# After the above, if cursor is past the last character of '''“str”''' , set '''"*curpos"''' so the cursor stands right after the last character of "str".
The cursor is never allowed to: 1- move before the start of the field, 2- be more than one position past the last character in the string, 3- be after the end of the field.
<u>Editing is terminated by pressing ENTER, TAB, UP, DOWN, PGUP, PGDN or any of the function keys (F1 to F12)</u>. Pressing<u>ESCAPE will terminate the iof_edit(), and abort editing</u>; : '''"str"'''will contain orinally originally passed data when leaving function.
Note that the conditions of termination are changed if the '''“IsTextEditor”''' flag is true (non-zero). See '''“IsTextEditor”'''section for detail.
If '''"ReadOnly"''' has a true value (non-zero) , then any attempt to change the content of '''"str"''' should end the function and return the key . Note that all other keys should work. (Function and Non-ASCII keys). This make makes the '''iof_edit()'''funciton "read only", but the user still user can scroll the text to left or right and etc....
The function returns an int identifying the key that was pressed to exit. (This function uses the same key codes as iof_getch())
The function takes no action if the user tries to enter too many characters (if, for example, the string is in full in insert mode, or the cursor is positioned after the last character of a full string in overstrike mode). However , if the cursor reaches the end of the field and the string is not full , then after inserting , the character string will be scrolled to the left, positioning the cursor right after the last character in the string.
The function handles at least the following special keys:
** if '''IsTextEditor''' is false, TAB will simply terminate the function like a Function key
** 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 ciol.h. If '''CIO_TAB_SIZE''' spaces cannot be inserted into the string for any reason then the inputted tab should be ignored. (See below for more about '''IsTextEditor''' flag)
* ESCAPE - Terminates the iof_edit(), and abort aborts editing; : '''"str"'''will contain originally passed data when leaving function. (See[[OOP344 BIO 20101#IsTextEditor:|IsTextEditor]] for exception)
* INSERT - toggle Insert/Overstrike mode<br />In Insert mode, printable characters are inserted into the string, moving the remainder of the string to the right to make room. In Overstrike mode, printable characters overwrite existing characters (if any). Note that if you are past the end of the string, printable characters are appended to the string (as long as the string isn't full) regardless of the 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 moving to right, the characters are shifted to left.
==== IsTextEditor: ====
If IsTextEditor is true, then it means that the function is being used to edit a text by editing one line of the text at a time. In this case, shifting a line to the left or right should not only cause the editing line to be shifted, but also the rest of the lines in the text. To do this, iof_edit () should let the calling function know that a shift has happened. 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 iof_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.
''when '''IsTextEditor''' is true, and Escape is hit do not abort the editing but simply terminate the function returning the Escape key.''
The iof_edit() function always shows blanks in any the part of the field that is not occupied by the data in the string.<u>UNDER NO CIRCUMSTANCES DOES THE FUNCTION CHANGE ANY POSITION ON THE SCREEN OUTSIDE OF THE FIELD</u>.
Like most C library functions, your iof_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, etc.
'''''Note:'''''
