1
edit
Changes
→Line Editor: int io_edit(........)
===Line Editor: int io_edit(........)===
<big>int io_edit(char* '''str''', int '''row''', int '''col''', <br /> int '''fieldlen''', int '''maxdatalen''', int '''*insertmode''', int'''* offset''',<br /> int'''* curpos''', int '''IsTextEditor''')</big>
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 will be are: 1('''insertmode'''), 0('''curpos'''), and 0 respectively.('''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 corrections should be done to '''"*curpos" ''' and '''"*offset" ''' in case they hold invalid values before editing begins:
# Set the '''"*curpos" ''' so that cursor stands at the last position of the field if it exceeds fieldlen.# 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 Assignment One#IsTextEditor:|IsTextEditor]] for more)# After the above, if cursor is past last character of '''“str” ''' set '''"*curpos" ''' so the cursor stands right after the last character of "str".
The cursor is never allowed to move before the start of the field, more than one position past the last character in the string, or 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 io_edit(). If ESCAPE is used, Then and abort editing is aborted - the string is left containing the </u>; '''"str"''' will contain orinally passed data originally passed to io_edit()when leaving function.
Note that the conditions of termination are changed if '''“IsTextEditor” ''' flag is true (non-zero). See '''“IsTextEditor” ''' section for detail.
The function returns an int identifying the key that was pressed to exit. (This function uses the same key codes as [[#io_getch()| io_getch()]])
The function takes no action if the user tries to enter too many characters (if, for example, the string is full in insert mode, or the cursor is positioned after the last character of a full string in overstrike mode). However if cursor reaches the end of the field and the string is not full then after inserting the character string will be scrolled to left, positioning the cursor right after the last character in the string.
====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, io_edit should let the calling function take care of shifting instead of doing it by itself. 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 instead. With termination, the function should return the terminating key.
The only exception is when upon the beginning of the execution of io_edit, when validating '''*offset''', make sure to correct the offset before 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.''
Any normal printable key is simply placed into the string according to the rules laid out 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".)
The io_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 io_edit() may assume that it is the calling program's responsibility 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.
