Synopsis:

       input_string = term_kbedit(row, column, width, initial_str[, attribute]);

Arguments:

       row                - The row where the edit will start

       column        - The column where the edit will start

       width                - The number of characters to get

       initial_str        - The initial value of the edit string

       [attribute]        - Option attribute ID (as defined by term_attr_def())

Description:   This function allows for string input to be obtained from the keyboard.   The calling task will be suspended while the input is being entered and will only return when one of the input termination keys is pressed.       Only one task at a time can be calling a blocking keyboard input function so if any other task is currently executing term_kbget(), term_kbgetx() or term_kbedit() then the function will return immediately with a bloank string and will output an error message

The editing area on the screen is defined by the row, column and width arguments and the initial_str value will be displayed in this area when the function is first called with the cursor positioned at the end for the initial_str.                

Editing keys are the following:

[Enter]                  - Terminates the input and returns the edited string

[Esc]                           - Aborts the edit and returns the initial string

[Backspace]        - Deletes the character at the previous position

[Del]                - Deletes the character at the current position

[←] [→]                - Moves the cursor left or right through the editing string.

If any other special (non-ascii key) is pressed then this will terminate the edit as if Enter had been pressed.    

Note:  The key that terminated the input is not returned with the input string and is left in the keyboard buffer.     This key nust then be removed from the keyboard buffer using term_kbget() before term_kbedit() is called again (otherwise the next and subsequent calls to term_kbedit() will return immediately as though enter had been hit).          This is a common cause of bugs when using this function.

Below is an example program which loops continuously returning input from the term_kbedit() function and printing the returned string to the scrolling log area:

main

   var input_str:60;

   term_box(5,0,80,20);

   term_scroll_area(6,1,78,18);

   term_cur_pos(3,0);

   term_print("Enter a string:");

   while(1)

       input_str=term_kbedit(3,16,50,"This is the initial value");

       term_kbget();

       applog("Input=",input_str);

   endwhile

endmain