04/26/90  window_io_

Function:  The window_io_ I/O module supports I/O to a window.  In
addition to the usual iox_ entries, the module provides terminal
independent access to special video terminal features, such as a
moveable cursor, selective erasure, and scrolling of regions.  The
module provides a real-time input line editor and performs output
conversion and "MORE" processing.

Entry points in this module are not called directly by users; rather,
this module is accessed through the I/O system interfaces iox_ and
window_.


Attach Description:
        window_io_ switch {-control_args}


Arguments:
switch
   is the name of an I/O switch attached to a terminal via the tc_io_
   I/O module.  The window created by this attach operation will be
   mapped onto the screen of that terminal.  Use window_$create to
   attach and open, and use window_$destroy to detach and close windows
   on the login terminal.


Control arguments:
-first_line LINE_NO
   LINE_NO is the line number on the screen where the window is to
   begin.  If omitted, the window starts on the topmost line of the
   screen (line 1).
-height N_LINES, -n_lines N_LINES
   N_LINES is the number of lines in the window.  The default is to use
   all lines to the end of the screen.
-first_column COL_NO
   COL_NO is the column number on the screen where the window is to
   begin.  If omitted, the window starts on the leftmost column of the
   screen (column 1).
-width N_COLS, -n_columns N_COLS
   N_COLS is the number of the columns in the window.  The default is
   all columns to the end of the screen.


Notes:  The attach description control arguments must specify a region
which lies within the terminal screen.  If not, the attachment is not
made, and the error code video_et_$out_of_terminal_bounds is returned.

When the window is attached, it is cleared and the cursor is left at
home.


Open Operation:
The following opening mode is supported:  stream_input_output.


Put Chars Operation:
This operation is used to output a character string to the window.
If rawo mode is disabled, the characters are processed according to the
output conversions defined for the terminal.  If necessary, the string
is continued on subsequent lines of the window.  If output passes the
last line of the window, the placement of additional lines is
controlled by the setting of the more_mode mode.  If an output line
must be erased from the window to make room for this new output, and
there has been no intervening input in this window, and more_mode is
enabled, the user is queried for the disposition of this new output.

In rawo mode, the characters are written directly to the terminal,
without any of the above processing.


Get Chars Operation:
This operation returns exactly one character, unechoed, regardless of
the size of the caller's buffer.  The line editor is not invoked by
this call.


Get Line Operation:
The get_line operation invokes the real-time input line editor, and
returns a complete line typed by the user.  The put_chars and get_line
operations retrieve and reset any statuses that they encounter, so that
applications that make these calls need not be changed to check for
video_et_$window_status_pending.


Control Operation: The control operations below are supported.  Note
that many of the control operations can be issued at command level via
io_call commands; these include any control orders that do not require
an info structure.  The following relations must hold when changing
windows (set_window_info).  These relations are always true when
obtaining information about a window (get_window_info):

      0 < column + width <= screen width
      0 < line + height <= screen height

get_window_info
   returns information about the position and extent of the window.
   The info ptr points to the 'window_position_info' structure,
   declared in window_control_info.incl.pl1.


set_window_info
   causes the window to be relocated or to change size (or both).
   The info ptr points to the same structure used in
   "get_window_info" control order.  The values have the same
   meaning, but are the new value for the window when setting (Input),
   and are returned by get_window_info (Output).
get_window_status, set_window_status
   window status is used to inform the application that some
   asynchronous event has disturbed the contents of the window.  When
   window status is set for a window, all calls to window_ will
   return video_et_$window_status_pending until the status is reset.
   To reset the status, make a get_window_status control order on the
   switch.  The info pointer should point to the 'window_status_info'
   structure, declared in window_control_info.incl.pl1.


Notes:  The get_window_status and set_window_status control orders are
available from command level and as active functions with the following
io_call commands:

      io_call control window_switch get_window_status status_key_1
         {status_key_2} N
      io_call control window_switch set_window_status status_key_1
         {status_key_N}

where status_key_N is either screen_invalid, asynchronous_change,
ttp_change, or reconnection.


get_capabilities
   returns information about the generic capabilities of the terminal.
   These are the "raw" physical characteristics of the terminal.  The
   video system may simulate those that are lacking.  For example, the
   system simulates insert and delete characters, but does not simulate
   insert and delete lines.  The info ptr should point to the
   'capabilities_info' structure, declared in
   terminal_capabilities.incl.pl1.
reset_more
   causes MORE Processing to be reset.  All lines on the window may be
   freely discarded without querying the user.
get_editing_chars
   is identical to the operation supported by the tty_ I/O module.
set_editing_chars
   is identical to the operation supported by the tty_ I/O module.


Notes:  The get_editing_chars and set_editing_chars control orders are
available from command level and as active functions with the following
io_call commands:

 io_call control window_switch get_editing_chars
 io_call control window_switch set_editing_chars erase_kill_characters


get_more_responses
   returns information about the acceptable responses to MORE
   processing.  The info pointer should point to the
   'more_responses_info' structure, declared in
   window_control_info.incl.pl1.
set_more_responses
   sets the responses.  The data structure is the same as the one used
   for the "get_more_responses" order except that all fields are Input.
   At most, 32 yeses and 32 noes may be supplied.  It is highly
   recommended that there be at least one yes, so that output may
   continue.  The "yes" and "no" characters must be distinct.  If they
   are not, the error code video_et_$overlapping_more_responses is
   returned, and the responses are not changed.


Notes:  The get_more_response and set_more_response control orders are
available from command level and as active functions with the following
io_call command:

      io_call control window_switch get_more_responses
      io_call control window_switch set_more_responses yes_responses
         no_responses

where the yes_responses and no_responses will be used as arguments to
the get_more_responses control order.  If either of the response
strings contains blanks or special characters, it must be quoted.


get_more_prompt set_more_prompt
   sets the prompt displayed when a more break occurs.  The current
   more responses can be displayed as part of the more prompt, by
   including the proper ioa_ control codes as part of the prompt
   string.  For example the default video system more prompt string is
   "More?  (^a for more; ^a to discard output.)".  With the default
   more responses of carriage return for more and the delete for
   discard, the final string displayed is "More (RETURN for more; DEL
   to discard output.)."  The info pointer should point to the
   'more_prompt_info' structure, declared in
   window_control_info.incl.pl1.


The get_more_prompt and set_more_prompt control orders are available
from command level and as active functions with the following io_call
command:

     io_call control window_switch get_more_prompt
     io_call control window_switch set_more_prompt prompt_string

where window_switch is a valid window_io_ switch and prompt_string is
the ioa_ control string described above.


get_more_handler set_more_handler
   Sets the handler for video system more breaks to the specified
   routine.  The info pointer should point to the 'more_handler_info'
   structure, declared in window_control_io.incl.pl1.

   The more handler routine is called with two arguments.  The first is
   a pointer to a 'more_info' structure, containing information of
   interest to a more handler.  The second is a flag which the more
   handler sets to indicate whether or not output should be flushed
   ("1"b to continue output, "0"b to flush output).

   The 'more_info' structure can be found in the include file
   window_more_info.incl.pl1.


Notes:  The get_more_handler and set_more_handler control orders are
available from command level and as active functions with the following
io_call command:

     io_call control window_switch get_more_handler
     io_call control window_switch set_more_handler more_handler

where more_handler is the entryname of the routine to be used as the
more handler routine.  The name is converted to an entry using the
user's search rules and is then used as described in the
set_more_handler control order.


get_break_table set_break_table
   break table determines action of the get_echoed_chars,
   get_unechoed_chars, and write_sync_read entry points of the window_
   subroutine.  The array 'breaks' has a 1 for each character that is
   to be considered a break.  By default, the break table has "1"b for
   all the nonprintable characters, and "0"b elsewhere.  Applications
   that set the break table must be careful to reset it afterwards, and
   establish an appropriate cleanup handler.  The info pointer should
   point to the 'break_table_info' structure, declared in
   window_control_info.incl.pl1, which contains the array 'breaks'.
reset_more_handler
   cancels the last user-defined more_handler.  The reset_more_handler
   control order is available from command level with the following
   io_call command:
        io_call control window_switch reset_more_handler


get_output_conversion
   this order is used to obtain the current contents of the specified
   table.  The info_ptr points to a structure like the one described
   for the corresponding "set" order, which is filled in as a
   result of the call (except for the version number, which must be
   supplied by the caller).  If the specified table does not exist (no
   translation or conversion is required), the status code
   error_table_$no_table is returned.
set_output_conversion
   provides a table to be used in formatting output to identify certain
   kinds of special characters.  The info_ptr points to the
   'cv_trans_struc' structure, declared in tty_convert.incl.pl1.  If
   the info_ptr is null, no transaction is to be done.


get_special
   is used to obtain the contents of the special_chars table currently
   in use.  The info_ptr points to the 'get_special_info_struc'
   structure, defined in tty_convert.incl.pl1.

set_special
   provides a table that specifies sequences to be substituted for
   certain output characters, and characters that are to be interpreted
   as parts of escape sequences on input.  Output sequences follow the
   form of 'c_chars', defined in tty_convert.incl.pl1.  The info_ptr
   points to the 'special_chars_struc' structure, also defined in
   tty_convert.incl.pl1.


Notes:  Video ignores cr_seq, bs_seq, tab_seq, vt_seq, ff_seq,
printer_on, printer_off, end_of_page, input_escapes, and input results.


get_token_characters, set_token_characters
   changes the set of characters that are used by the video system
   input line editor to define a word for such requests as ESC DEL.
   The set of characters supplied in the structure replace the existing
   set of characters.  The info_ptr points to the
   'token_characters_info' structure, declared in
   window_control_info.incl.pl1.


Notes:  The set_token_characters and get_token_characters control
orders are available from command_level and as active functions with
the following io_call commands:

  io_call control window_switch get_token_characters
  io_call control window_switch set_token_characters token_char_string

where token_char_string is a character string containing the new set of
token characters.  get_token_character returns its result as a string
if it was invoked as an active function, otherwise it prints out the
token characters.


get_editor_key_bindings
   returns a pointer to the line_editor_key_binding structure
   describing the key bindings.  io_call support prints out the
   pathname of each editor routine, listing only the names of builtin
   requests in capital letters, with the word "builtin" in parentheses.
   This control order prints or returns current information about the
   key_bindings.  Use the set_editor_key_bindings control order to
   change the bindings.

   The info_ptr points to the 'get_editor_key_bindings_info' structure,
   declared in window_control_info.incl.pl1.


Notes:  The get_editor_key_bindings control order is available from
command level and as an active function with following io_call command:

     io_call control window_switch get_editor_key_bindings

The get_editor_key_bindings control order prints or returns information
about a key binding.  When you use it as an active function the
information is returned in a form suitable as arguments to the
set_editor_key_bindings control order.


set_editor_key_bindings
   A line editor routine is bound to a sequence of keystrokes via the
   set_editor_key_bindings control order.  The sequence of characters
   that triggers an editor request may be of any length, with
   multiple-key sequences working like the Emacs prefix characters.
   This allows the use of terminal function keys (which often send
   three or more character sequences) to invoke line editor requests.
   More than one binding can be set in one invocation of this control
   order.

   The info_ptr points to the 'set_editor_key_bindings_info' structure,
   declared in window_control_info.incl.pl1.


Notes:
The video system's internal data structures are freed at the following
times: video system revocation, and when a set_editor_key_bindings
control order with 'replace = "1"b' is done.

The set_editor_key_bindings control order is available from command
level and as an active function with the following io_call command:

   io_call control window_switch set_editor_key_bindings key_sequence1
      {user_routine1} {control_args1} ... key_sequenceN
        {user_routineN} {control_args1} {control_argsN}

where user_routine is the name of a user-written editor request.


Control args:
        -external user_routine
        -builtin builtin_request_name
        -numarg_action numarg_action_name


At least one user_routine or one of -external/-builtin must be
specified for each key sequence, with the rightmost editor request
specifier taking precedence (for example, io control window_switch
set_editor_key_bindings foo -builtin FORWARD_word,) will bind control-a
to the forward word builtin, not the user routine foo.

numarg_action_name
   the type of automatic numeric argument to be taken when the editor
   routine is invoked, must be one of the following and can only be
   given for external editor routines
REPEAT
   This can be entered in upper or lower case.
   Call the user routine n times, where n is the numeric argument
   supplied by the user.  (The default is PASS).


REJECT
   ring the terminal bell and don't call the user routine if a numeric
   argument is given.
PASS
   pass any numeric argument to the user routine, without any other
   action.
IGNORE
   same as PASS but implies the user routine will not make use of the
   numeric argument.
-name STR
   specifies the name of the editor command being assigned to the key.
   If this is the null string, then a default name is used (for
   builtins this is the name of the builtin, otherwise it is
   segname$entrypoint).  STR must be quoted if it contains whitespace.


-description STR
   specifies a description string to be associated with the key
   binding.  If this is the null string, a default description is used.
   The defaults can be found in the include file
   window_editor_values.incl.pl1.  STR must be quoted if it contains
   whitespace.
-info_pathname PATH
   specifies an info segment pathname to be associated with this key
   binding.  This info segment is expected to have more information
   about the editor_routine.  If this is not specified, it defaults to
   >doc>info>video_editing.gi.info if -builtin, otherwise no info
   segment is associated with the key.  The info suffix is assumed on
   PATH.


Modes Operation:
The modes operation is supported by window_io_.  The recognized modes
are listed below.  Some modes have a complement indicated by the
circumflex character (^) that turns the mode off (e.g.  ^more).  For
these modes, the complement is displayed with that mode.  Some modes
specify a parameter that can take on a value (e.g.  more_mode).  These
modes are specified as MODE=VALUE, where MODE is the name of the mode
and VALUE is the value it is to be set to.  Parameterized modes are
indicated by the notation (P) in the following description:


more, ^more
   Turns MORE processing on.  Default is on.  If ^pl is set before you
   invoke the video system, ^more will be set when you invoke the video
   system.
more_mode = STR
   controls behavior when the window is filled.  The value for STR may
   be one of the following:
   clear
      the window is cleared, and output starts at the home position.
   fold
      output begins at the first line and moves down the screen a line
      at a time replacing existing text with new text.  Prompts for a
      MORE response when it is about to overwrite the first line
      written since the last read or MORE break.


   scroll
      lines are scrolled off the top of the window, and new lines are
      printed in the space that is cleared at the bottom of the screen.
      This is the default for full width windows on all terminals
      capable of scrolling.
   wrap
      output begins at the first line and moves down the screen a line
      at a time replacing existing text with new text.  Prompts for a
      MORE response at the bottom of every window of output.  This is
      the default for all terminals that are incapable of scrolling or
      when using partial width windows.


vertsp, ^vertsp
      is only effective when more mode is on.  When vertsp mode is on,
      output of a FF or VT will cause an immediate MORE query.  When
      you invoke the video system, it copies the current setting of
      this mode before attaching the window_io_ module.  The default is
      ^vertsp.
   rawo, ^rawo
      causes characters to be output with no processing whatsoever.
      The result of output in this mode is undefined.
   can, ^can
      causes input lines to be canonicalized before they are returned.
      When you invoke the video system, it copies the current setting
      of this mode before attaching the window_io_ module.  The default
      is on.


   ctl_char, ^ctl_char
      specifies that ASCII control characters that do not cause newline
      or linefeed motion are to be accepted as input except for the NUL
      character.  If the mode is off all such characters are discarded.
      When you invoke the video system, it copies the current setting
      of this mode before attaching the window_io_ module.  The default
      is off.
   edited, ^edited
      suppresses printing of characters for which there is no defined
      Multics equivalent on the device referenced.  If edited mode is
      off, the 9-bit octal representation of the character is printed.
      When you invoke the video system, it copies the current setting
      of this mode before attaching the window_io_ module.  The default
      is off.


   erkl, ^erkl
      controls the editing functions of get_line.  When you invoke the
      video system, it copies the current setting of this mode before
      attaching the window_io_ module.  The default is on, which allows
      erase and kill processing and the additional line editor
      functions.
   esc, ^esc
      controls input escape processing.  When you invoke the video
      system, it copies the current setting of this mode before
      attaching the window_io_ module.  The default is on.
   rawi, ^rawi
      acts as a master control for can, erkl, and esc.  If this mode is
      on, none of the input conventions are provided.  The default is
      on.


   ll = STR
      is the width of the window, in characters, and it can only be
      changed with the set_window_info control operation.
   pl = STR
      is the height of the window (i.e., number of lines), and it can
      only be changed with the set_window_info control operation.
   red, ^red
      controls interpretation of red shift and black shift characters
      on output.  When you invoke the video system, it copies the
      current setting of this mode before attaching the window_io_
      module.  The default is ^red, which ignores them.  In red mode,
      the character sequence given in the TTF is output.  The effect is
      undefined and terminal-specific.  In some cases, "red shifted"
      output appears in inverse video, but this is not guaranteed.


Control Operations from Command Level:
Those control operations which require no info_ptr and those additional
orders described above may be performed from command level using the
io_call command, as follows:

        io_call control switch_name control_order


Arguments:
switch_name
   is the name of the I/O switch.
control_order
   can be any control order described above under "Control Operation"
   that can accept a null info_ptr.
