1 04/26/90 window_io_
2
3 Function: The window_io_ I/O module supports I/O to a window. In
4 addition to the usual iox_ entries, the module provides terminal
5 independent access to special video terminal features, such as a
6 moveable cursor, selective erasure, and scrolling of regions. The
7 module provides a real-time input line editor and performs output
8 conversion and "MORE" processing.
9
10 Entry points in this module are not called directly by users; rather,
11 this module is accessed through the I/O system interfaces iox_ and
12 window_.
13
14
15 Attach Description:
16 window_io_ switch -control_args
17
18
19 Arguments:
20 switch
21 is the name of an I/O switch attached to a terminal via the tc_io_
22 I/O module. The window created by this attach operation will be
23 mapped onto the screen of that terminal. Use window_$create to
24 attach and open, and use window_$destroy to detach and close windows
25 on the login terminal.
26
27
28 Control arguments:
29 -first_line LINE_NO
30 LINE_NO is the line number on the screen where the window is to
31 begin. If omitted, the window starts on the topmost line of the
32 screen line 1.
33 -height N_LINES, -n_lines N_LINES
34 N_LINES is the number of lines in the window. The default is to use
35 all lines to the end of the screen.
36 -first_column COL_NO
37 COL_NO is the column number on the screen where the window is to
38 begin. If omitted, the window starts on the leftmost column of the
39 screen column 1.
40 -width N_COLS, -n_columns N_COLS
41 N_COLS is the number of the columns in the window. The default is
42 all columns to the end of the screen.
43
44
45 Notes: The attach description control arguments must specify a region
46 which lies within the terminal screen. If not, the attachment is not
47 made, and the error code video_et_$out_of_terminal_bounds is returned.
48
49 When the window is attached, it is cleared and the cursor is left at
50 home.
51
52
53 Open Operation:
54 The following opening mode is supported: stream_input_output.
55
56
57 Put Chars Operation:
58 This operation is used to output a character string to the window.
59 If rawo mode is disabled, the characters are processed according to the
60 output conversions defined for the terminal. If necessary, the string
61 is continued on subsequent lines of the window. If output passes the
62 last line of the window, the placement of additional lines is
63 controlled by the setting of the more_mode mode. If an output line
64 must be erased from the window to make room for this new output, and
65 there has been no intervening input in this window, and more_mode is
66 enabled, the user is queried for the disposition of this new output.
67
68 In rawo mode, the characters are written directly to the terminal,
69 without any of the above processing.
70
71
72 Get Chars Operation:
73 This operation returns exactly one character, unechoed, regardless of
74 the size of the caller's buffer. The line editor is not invoked by
75 this call.
76
77
78 Get Line Operation:
79 The get_line operation invokes the real-time input line editor, and
80 returns a complete line typed by the user. The put_chars and get_line
81 operations retrieve and reset any statuses that they encounter, so that
82 applications that make these calls need not be changed to check for
83 video_et_$window_status_pending.
84
85
86 Control Operation: The control operations below are supported. Note
87 that many of the control operations can be issued at command level via
88 io_call commands; these include any control orders that do not require
89 an info structure. The following relations must hold when changing
90 windows set_window_info. These relations are always true when
91 obtaining information about a window get_window_info:
92
93 0 < column + width <= screen width
94 0 < line + height <= screen height
95
96 get_window_info
97 returns information about the position and extent of the window.
98 The info ptr points to the 'window_position_info' structure,
99 declared in window_control_info.incl.pl1.
100
101
102 set_window_info
103 causes the window to be relocated or to change size or both.
104 The info ptr points to the same structure used in
105 "get_window_info" control order. The values have the same
106 meaning, but are the new value for the window when setting Input,
107 and are returned by get_window_info Output.
108 get_window_status, set_window_status
109 window status is used to inform the application that some
110 asynchronous event has disturbed the contents of the window. When
111 window status is set for a window, all calls to window_ will
112 return video_et_$window_status_pending until the status is reset.
113 To reset the status, make a get_window_status control order on the
114 switch. The info pointer should point to the 'window_status_info'
115 structure, declared in window_control_info.incl.pl1.
116
117
118 Notes: The get_window_status and set_window_status control orders are
119 available from command level and as active functions with the following
120 io_call commands:
121
122 io_call control window_switch get_window_status status_key_1
123 status_key_2 N
124 io_call control window_switch set_window_status status_key_1
125 status_key_N
126
127 where status_key_N is either screen_invalid, asynchronous_change,
128 ttp_change, or reconnection.
129
130
131 get_capabilities
132 returns information about the generic capabilities of the terminal.
133 These are the "raw" physical characteristics of the terminal. The
134 video system may simulate those that are lacking. For example, the
135 system simulates insert and delete characters, but does not simulate
136 insert and delete lines. The info ptr should point to the
137 'capabilities_info' structure, declared in
138 terminal_capabilities.incl.pl1.
139 reset_more
140 causes MORE Processing to be reset. All lines on the window may be
141 freely discarded without querying the user.
142 get_editing_chars
143 is identical to the operation supported by the tty_ I/O module.
144 set_editing_chars
145 is identical to the operation supported by the tty_ I/O module.
146
147
148 Notes: The get_editing_chars and set_editing_chars control orders are
149 available from command level and as active functions with the following
150 io_call commands:
151
152 io_call control window_switch get_editing_chars
153 io_call control window_switch set_editing_chars erase_kill_characters
154
155
156 get_more_responses
157 returns information about the acceptable responses to MORE
158 processing. The info pointer should point to the
159 'more_responses_info' structure, declared in
160 window_control_info.incl.pl1.
161 set_more_responses
162 sets the responses. The data structure is the same as the one used
163 for the "get_more_responses" order except that all fields are Input.
164 At most, 32 yeses and 32 noes may be supplied. It is highly
165 recommended that there be at least one yes, so that output may
166 continue. The "yes" and "no" characters must be distinct. If they
167 are not, the error code video_et_$overlapping_more_responses is
168 returned, and the responses are not changed.
169
170
171 Notes: The get_more_response and set_more_response control orders are
172 available from command level and as active functions with the following
173 io_call command:
174
175 io_call control window_switch get_more_responses
176 io_call control window_switch set_more_responses yes_responses
177 no_responses
178
179 where the yes_responses and no_responses will be used as arguments to
180 the get_more_responses control order. If either of the response
181 strings contains blanks or special characters, it must be quoted.
182
183
184 get_more_prompt set_more_prompt
185 sets the prompt displayed when a more break occurs. The current
186 more responses can be displayed as part of the more prompt, by
187 including the proper ioa_ control codes as part of the prompt
188 string. For example the default video system more prompt string is
189 "More? ^a for more; ^a to discard output.". With the default
190 more responses of carriage return for more and the delete for
191 discard, the final string displayed is "More RETURN for more; DEL
192 to discard output.." The info pointer should point to the
193 'more_prompt_info' structure, declared in
194 window_control_info.incl.pl1.
195
196
197 The get_more_prompt and set_more_prompt control orders are available
198 from command level and as active functions with the following io_call
199 command:
200
201 io_call control window_switch get_more_prompt
202 io_call control window_switch set_more_prompt prompt_string
203
204 where window_switch is a valid window_io_ switch and prompt_string is
205 the ioa_ control string described above.
206
207
208 get_more_handler set_more_handler
209 Sets the handler for video system more breaks to the specified
210 routine. The info pointer should point to the 'more_handler_info'
211 structure, declared in window_control_io.incl.pl1.
212
213 The more handler routine is called with two arguments. The first is
214 a pointer to a 'more_info' structure, containing information of
215 interest to a more handler. The second is a flag which the more
216 handler sets to indicate whether or not output should be flushed
217 "1"b to continue output "0"b to flush output.
218
219 The 'more_info' structure can be found in the include file
220 window_more_info.incl.pl1.
221
222
223 Notes: The get_more_handler and set_more_handler control orders are
224 available from command level and as active functions with the following
225 io_call command:
226
227 io_call control window_switch get_more_handler
228 io_call control window_switch set_more_handler more_handler
229
230 where more_handler is the entryname of the routine to be used as the
231 more handler routine. The name is converted to an entry using the
232 user's search rules and is then used as described in the
233 set_more_handler control order.
234
235
236 get_break_table set_break_table
237 break table determines action of the get_echoed_chars,
238 get_unechoed_chars, and write_sync_read entry points of the window_
239 subroutine. The array 'breaks' has a 1 for each character that is
240 to be considered a break. By default, the break table has "1"b for
241 all the nonprintable characters, and "0"b elsewhere. Applications
242 that set the break table must be careful to reset it afterwards, and
243 establish an appropriate cleanup handler. The info pointer should
244 point to the 'break_table_info' structure, declared in
245 window_control_info.incl.pl1, which contains the array 'breaks'.
246 reset_more_handler
247 cancels the last user-defined more_handler. The reset_more_handler
248 control order is available from command level with the following
249 io_call command:
250 io_call control window_switch reset_more_handler
251
252
253 get_output_conversion
254 this order is used to obtain the current contents of the specified
255 table. The info_ptr points to a structure like the one described
256 for the corresponding "set" order, which is filled in as a
257 result of the call except for the version number which must be
258 supplied by the caller. If the specified table does not exist no
259 translation or conversion is required, the status code
260 error_table_$no_table is returned.
261 set_output_conversion
262 provides a table to be used in formatting output to identify certain
263 kinds of special characters. The info_ptr points to the
264 'cv_trans_struc' structure, declared in tty_convert.incl.pl1. If
265 the info_ptr is null, no transaction is to be done.
266
267
268 get_special
269 is used to obtain the contents of the special_chars table currently
270 in use. The info_ptr points to the 'get_special_info_struc'
271 structure, defined in tty_convert.incl.pl1.
272
273 set_special
274 provides a table that specifies sequences to be substituted for
275 certain output characters, and characters that are to be interpreted
276 as parts of escape sequences on input. Output sequences follow the
277 form of 'c_chars', defined in tty_convert.incl.pl1. The info_ptr
278 points to the 'special_chars_struc' structure, also defined in
279 tty_convert.incl.pl1.
280
281
282 Notes: Video ignores cr_seq, bs_seq, tab_seq, vt_seq, ff_seq,
283 printer_on, printer_off, end_of_page, input_escapes, and input results.
284
285
286 get_token_characters, set_token_characters
287 changes the set of characters that are used by the video system
288 input line editor to define a word for such requests as ESC DEL.
289 The set of characters supplied in the structure replace the existing
290 set of characters. The info_ptr points to the
291 'token_characters_info' structure, declared in
292 window_control_info.incl.pl1.
293
294
295 Notes: The set_token_characters and get_token_characters control
296 orders are available from command_level and as active functions with
297 the following io_call commands:
298
299 io_call control window_switch get_token_characters
300 io_call control window_switch set_token_characters token_char_string
301
302 where token_char_string is a character string containing the new set of
303 token characters. get_token_character returns its result as a string
304 if it was invoked as an active function, otherwise it prints out the
305 token characters.
306
307
308 get_editor_key_bindings
309 returns a pointer to the line_editor_key_binding structure
310 describing the key bindings. io_call support prints out the
311 pathname of each editor routine, listing only the names of builtin
312 requests in capital letters, with the word "builtin" in parentheses.
313 This control order prints or returns current information about the
314 key_bindings. Use the set_editor_key_bindings control order to
315 change the bindings.
316
317 The info_ptr points to the 'get_editor_key_bindings_info' structure,
318 declared in window_control_info.incl.pl1.
319
320
321 Notes: The get_editor_key_bindings control order is available from
322 command level and as an active function with following io_call command:
323
324 io_call control window_switch get_editor_key_bindings
325
326 The get_editor_key_bindings control order prints or returns information
327 about a key binding. When you use it as an active function the
328 information is returned in a form suitable as arguments to the
329 set_editor_key_bindings control order.
330
331
332 set_editor_key_bindings
333 A line editor routine is bound to a sequence of keystrokes via the
334 set_editor_key_bindings control order. The sequence of characters
335 that triggers an editor request may be of any length, with
336 multiple-key sequences working like the Emacs prefix characters.
337 This allows the use of terminal function keys which often send
338 three or more character sequences to invoke line editor requests.
339 More than one binding can be set in one invocation of this control
340 order.
341
342 The info_ptr points to the 'set_editor_key_bindings_info' structure,
343 declared in window_control_info.incl.pl1.
344
345
346 Notes:
347 The video system's internal data structures are freed at the following
348 times: video system revocation, and when a set_editor_key_bindings
349 control order with 'replace = "1"b' is done.
350
351 The set_editor_key_bindings control order is available from command
352 level and as an active function with the following io_call command:
353
354 io_call control window_switch set_editor_key_bindings key_sequence1
355 user_routine1 control_args1 ... key_sequenceN
356 user_routineN control_args1 control_argsN
357
358 where user_routine is the name of a user-written editor request.
359
360
361 Control args:
362 -external user_routine
363 -builtin builtin_request_name
364 -numarg_action numarg_action_name
365
366
367 At least one user_routine or one of -external/-builtin must be
368 specified for each key sequence, with the rightmost editor request
369 specifier taking precedence for example io control window_switch
370 set_editor_key_bindings foo -builtin FORWARD_word will bind control-a
371 to the forward word builtin, not the user routine foo.
372
373 numarg_action_name
374 the type of automatic numeric argument to be taken when the editor
375 routine is invoked, must be one of the following and can only be
376 given for external editor routines
377 REPEAT
378 This can be entered in upper or lower case.
379 Call the user routine n times, where n is the numeric argument
380 supplied by the user. The default is PASS.
381
382
383 REJECT
384 ring the terminal bell and don't call the user routine if a numeric
385 argument is given.
386 PASS
387 pass any numeric argument to the user routine, without any other
388 action.
389 IGNORE
390 same as PASS but implies the user routine will not make use of the
391 numeric argument.
392 -name STR
393 specifies the name of the editor command being assigned to the key.
394 If this is the null string, then a default name is used for
395 builtins this is the name of the builtin otherwise it is
396 segname$entrypoint. STR must be quoted if it contains whitespace.
397
398
399 -description STR
400 specifies a description string to be associated with the key
401 binding. If this is the null string, a default description is used.
402 The defaults can be found in the include file
403 window_editor_values.incl.pl1. STR must be quoted if it contains
404 whitespace.
405 -info_pathname PATH
406 specifies an info segment pathname to be associated with this key
407 binding. This info segment is expected to have more information
408 about the editor_routine. If this is not specified, it defaults to
409 >doc>info>video_editing.gi.info if -builtin, otherwise no info
410 segment is associated with the key. The info suffix is assumed on
411 PATH.
412
413
414 Modes Operation:
415 The modes operation is supported by window_io_. The recognized modes
416 are listed below. Some modes have a complement indicated by the
417 circumflex character ^ that turns the mode off e.g. ^more. For
418 these modes, the complement is displayed with that mode. Some modes
419 specify a parameter that can take on a value e.g. more_mode. These
420 modes are specified as MODE=VALUE, where MODE is the name of the mode
421 and VALUE is the value it is to be set to. Parameterized modes are
422 indicated by the notation P in the following description:
423
424
425 more, ^more
426 Turns MORE processing on. Default is on. If ^pl is set before you
427 invoke the video system, ^more will be set when you invoke the video
428 system.
429 more_mode = STR
430 controls behavior when the window is filled. The value for STR may
431 be one of the following:
432 clear
433 the window is cleared, and output starts at the home position.
434 fold
435 output begins at the first line and moves down the screen a line
436 at a time replacing existing text with new text. Prompts for a
437 MORE response when it is about to overwrite the first line
438 written since the last read or MORE break.
439
440
441 scroll
442 lines are scrolled off the top of the window, and new lines are
443 printed in the space that is cleared at the bottom of the screen.
444 This is the default for full width windows on all terminals
445 capable of scrolling.
446 wrap
447 output begins at the first line and moves down the screen a line
448 at a time replacing existing text with new text. Prompts for a
449 MORE response at the bottom of every window of output. This is
450 the default for all terminals that are incapable of scrolling or
451 when using partial width windows.
452
453
454 vertsp, ^vertsp
455 is only effective when more mode is on. When vertsp mode is on,
456 output of a FF or VT will cause an immediate MORE query. When
457 you invoke the video system, it copies the current setting of
458 this mode before attaching the window_io_ module. The default is
459 ^vertsp.
460 rawo, ^rawo
461 causes characters to be output with no processing whatsoever.
462 The result of output in this mode is undefined.
463 can, ^can
464 causes input lines to be canonicalized before they are returned.
465 When you invoke the video system, it copies the current setting
466 of this mode before attaching the window_io_ module. The default
467 is on.
468
469
470 ctl_char, ^ctl_char
471 specifies that ASCII control characters that do not cause newline
472 or linefeed motion are to be accepted as input except for the NUL
473 character. If the mode is off all such characters are discarded.
474 When you invoke the video system, it copies the current setting
475 of this mode before attaching the window_io_ module. The default
476 is off.
477 edited, ^edited
478 suppresses printing of characters for which there is no defined
479 Multics equivalent on the device referenced. If edited mode is
480 off, the 9-bit octal representation of the character is printed.
481 When you invoke the video system, it copies the current setting
482 of this mode before attaching the window_io_ module. The default
483 is off.
484
485
486 erkl, ^erkl
487 controls the editing functions of get_line. When you invoke the
488 video system, it copies the current setting of this mode before
489 attaching the window_io_ module. The default is on, which allows
490 erase and kill processing and the additional line editor
491 functions.
492 esc, ^esc
493 controls input escape processing. When you invoke the video
494 system, it copies the current setting of this mode before
495 attaching the window_io_ module. The default is on.
496 rawi, ^rawi
497 acts as a master control for can, erkl, and esc. If this mode is
498 on, none of the input conventions are provided. The default is
499 on.
500
501
502 ll = STR
503 is the width of the window, in characters, and it can only be
504 changed with the set_window_info control operation.
505 pl = STR
506 is the height of the window i.e. number of lines, and it can
507 only be changed with the set_window_info control operation.
508 red, ^red
509 controls interpretation of red shift and black shift characters
510 on output. When you invoke the video system, it copies the
511 current setting of this mode before attaching the window_io_
512 module. The default is ^red, which ignores them. In red mode,
513 the character sequence given in the TTF is output. The effect is
514 undefined and terminal-specific. In some cases, "red shifted"
515 output appears in inverse video, but this is not guaranteed.
516
517
518 Control Operations from Command Level:
519 Those control operations which require no info_ptr and those additional
520 orders described above may be performed from command level using the
521 io_call command, as follows:
522
523 io_call control switch_name control_order
524
525
526 Arguments:
527 switch_name
528 is the name of the I/O switch.
529 control_order
530 can be any control order described above under "Control Operation"
531 that can accept a null info_ptr.