10/22/92  window_editor_utils_


A library of editor utility routines is provided for the benefit of
user-written editor routines.  Some operations can be performed
simply by a user-written editor routine.  For example, to position
the cursor to the end of the line, set the cursor_index
variable to one greater than the value of the line_length variable.
Most actions are more complex than this, however, it is
recommended that the editor utility routines be used to perform most
of them.  The following is a description of these routines.  In
all cases, line_editor_info_ptr is the pointer to the editor data
structure that is supplied as an argument to user-written editor
routines.


Entry points in window_editor_utils_:


:Entry:  insert_text:  07/31/92 window_editor_utils_$insert_text

Function: Inserts the supplied character string into the input buffer
at the current cursor location.  If the string is too large to fit in
the remaining buffer space, the code
error_table_$action_not_performed is returned.  This routine updates
the line_length field of the line_editor_info structure, and the
cursor_index if necessary.


Syntax:
dcl window_editor_utils_$insert_text entry (ptr, char(*), fixed bin (35));

call window_editor_utils_$insert_text (line_editor_info_ptr, "text",
     code);


Arguments:
line_editor_info_ptr
    pointer to editor data structure. (Input/Output)
"text"
    text string to be inserted.  (Input)
code
    status code.  (Output)


:Entry:  delete_text:  07/31/92  window_editor_utils_$delete_text

Function: Deletes a specified number of characters from the input
buffer at the current cursor location.  If there are not enough
characters remaining between the cursor and the end of the line,
error_table_$action_not_performed is returned and no characters are
deleted.  The line_length component of the line_editor_info_structure
is updated, and the cursor_index if necessary.


Syntax:
dcl window_editor_utils_$delete_text entry (ptr, fixed bin, fixed bin (35));

call window_editor_utils_$delete_text (line_editor_info_ptr, count,
     code);


Arguments:
line_editor_info_ptr
    pointer to editor data structure.  (Input/Output)
count
    number of characters to be deleted.  (Input)
code
    status code.  (Output)


:Entry: delete_text_save: 07/31/92  window_editor_utils_$delete_text_save

Function: This entrypoint is identical to delete_text, except that
the deleted text is added to the kill ring.  The kill_direction flag
is used during kill merging to decide whether the killed text will be
concatenated onto the beginning or end of the current kill ring
element.  "1"b is used to specify a forward kill (e.g.
FORWARD_DELETE_WORD), "0" a backward kill.


Syntax:
dcl window_editor_utils_$delete_text_save entry
     (ptr, fixed bin, bit(1), fixed bin (35));
call window_editor_utils_$delete_text_save
    (line_editor_info_ptr, count, kill_direction, code);


Arguments:
line_editor_info_ptr
    pointer to editor data structure.  (Input/Output)
count
    number of characters to be deleted.  (Input)
kill_direction
    flag to determine which end of current kill ring element
    deleted text will be concatenated to.  (Input)
code
    status code.  (Output)


:Entry: move_forward: 07/31/92  window_editor_utils_$move_forward

Function: Advances the cursor forward a specified number of
characters in the input line.  If there are not enough characters
between the cursor and the end of the line,
error_table_$action_not_performed is returned.


Syntax:
dcl window_editor_utils_$move_forward entry (ptr, fixed bin, fixed bin (35));

call window_editor_utils_$move_forward (line_editor_info_ptr,
     count, code);


Arguments:
line_editor_info_ptr
    pointer to editor data structure.  (Input/Output)
count
    number of characters to move forward.  (Input)
code
    status code.  (Output)


:Entry: move_backward: 07/31/92  window_editor_utils_$move_backward

Function: Moves the cursor backward a specified number of characters
in the input line.  If there are not enough characters between the
cursor and the end of the line, error_table_$action_not_performed is
returned.


Syntax:
dcl window_editor_utils_$move_backward entry (ptr, fixed bin, fixed bin (35));

call window_editor_utils_$move_backward
    (line_editor_info_ptr, count, code);


Arguments:
line_editor_info_ptr
    pointer to editor data structure.  (Input/Output)
count
    number of characters to move backward.  (Input)
code
    status code.  (Output)


:Entry: move_forward_word: 07/31/92  window_editor_utils_$move_forward_word

Function: Updates the cursor_index to a position after the next word
(or token) in the input line.  A word is defined via the editor's set
of token delimiters, set via the set_token_delimiters control order.


Syntax:
dcl window_editor_utils_$move_forward_word entry (ptr, fixed bin (35));

call window_editor_utils_$move_forward_word (line_editor_info_ptr,
     code);


Arguments:
line_editor_info_ptr
    pointer to editor data structure.  (Input/Output)
code
    status code.  (Output)


:Entry: move_backward_word: 07/31/92  window_editor_utils_$move_backward_word

Function: Updates the cursor_index to a position before the
preceeding word (or token) in the input line.  A word is defined via
the editor's set of token delimiters, set via the
set_token_delimiters control order.


Syntax:
dcl window_editor_utils_$move_backward_word entry (ptr, fixed bin (35));

call window_editor_utils_$move_backward_word
    (line_editor_info_ptr, code);


Arguments:
line_editor_info_ptr
    pointer to editor data structure.  (Input/Output)
code
    status code.  (Output)


:Entry: get_top_kill_ring_element: 07/31/92  window_editor_utils_$get_top_kill_ring_element

Function: Returns the top kill ring element.


Syntax:
dcl window_editor_utils_$get_top_kill_ring_element entry
    (ptr, char(*), fixed bin (35));
call window_editor_utils_$get_top_kill_ring_element
    (line_editor_info_ptr, text, code);


Arguments:
line_editor_info_ptr
    pointer to editor data structure.  (Input/Output)
text
    string containing contents of top kill ring element.  (Output)
code
    status code.  (Output)


:Entry: rotate_kill_ring: 07/31/92  window_editor_utils_$rotate_kill_ring

Function: Rotates the kill ring.


Syntax:
dcl window_editor_utils_$rotate_kill_ring entry (ptr, fixed bin (35));

call window_editor_utils_$rotate_kill_ring
    (line_editor_info_ptr, code);


Arguments:
line_editor_info_ptr
    pointer to editor data structure.  (Input/Output)
code
    status code.  (Output)

