diff options
Diffstat (limited to 'static/plan9-4e/man1/rio.1')
| -rw-r--r-- | static/plan9-4e/man1/rio.1 | 513 |
1 files changed, 513 insertions, 0 deletions
diff --git a/static/plan9-4e/man1/rio.1 b/static/plan9-4e/man1/rio.1 new file mode 100644 index 00000000..6438c29f --- /dev/null +++ b/static/plan9-4e/man1/rio.1 @@ -0,0 +1,513 @@ +.TH RIO 1 +.SH NAME +rio, label, window, wloc \- window system +.SH SYNOPSIS +.B rio +[ +.BI "-i '"cmd ' +] +[ +.BI "-k '"kbdcmd ' +] +[ +.B -s +] +[ +.B -f +.I font +] +.PP +.B label +.I name +.PP +.B window +[ +.B -m +] [ +.B -r +.I minx miny maxx maxy +] [ +.B -dx +.I n +] [ +.B -dy +.I n +] [ +.B -minx +.I n +] [ +.B -miny +.I n +] [ +.B -maxx +.I n +] [ +.B -maxy +.I n +] [ +.B -cd +.I dir +] [ +.B -hide +] [ +.I cmd +.I arg ... +] +.PP +.B wloc +.SH DESCRIPTION +.I Rio +manages asynchronous layers of text, or windows, on a raster display. +It also serves a variety of files for communicating with +and controlling windows; these are discussed in section +.IR rio (4). +.SS Commands +The +.I rio +command starts a new instance of the window system. +Its +.B -i +option names a startup script, which typically contains several +.I window +commands generated by +.IR wloc . +The +.B -k +option causes +.I rio +to run the command +.I kbdcmd +at startup and allow it to provide characters as keyboard input; the +.B keyboard +program described in +.IR bitsyload (1) +is the usual choice. +.PP +The +.B -s +option initializes windows so that text scrolls; +the default is not to scroll. +The +.I font +argument names a font used to display text, both in +.IR rio 's +menus +and as a default for any programs running in its windows; it also +establishes the +environment variable +.BR $font . +If +.B -f +is not given, +.I rio +uses the imported value of +.BR $font +if set; otherwise it imports the default font from the underlying graphics +server, usually the terminal's operating system. +.PP +The +.I label +command changes a window's identifying name. +.PP +The +.I window +command creates a window. +By default, it creates a shell window and sizes and places it automatically. +The geometry arguments control the size +.IB ( dx , +.BR dy ) +and placement +.RB ( minx , +.BR miny , +.BR maxx , +.BR maxy ; +.BR hide +causes the window to be created off-screen); and working directory +.RB ( cd ). +the units are pixels with the +upper left corner of the screen at (0, 0). +The optional command and arguments define which program to run in the window. +.PP +By default, +.I window +uses +.B /dev/wctl +(see +.IR rio (4)) +to create the window and run the command. Therefore, the window and command +will be created by +.I rio +and run in a new file name space, just as if the window had been created using the interactive menu. +However, the +.B -m +option uses the file server properties of +.I rio +to +.B mount +(see +.IR bind (1)) +the new window's name space within the name space of the program calling +.IR window . +This means, for example, that running +.B window +in a CPU window will create another window whose command runs on the terminal, where +.I rio +is running; while +.B window +.B -m +will create another window whose command runs on the CPU server. +.PP +The +.I wloc +command prints the coordinates and label of each window in its instance of +.I rio +and is used to construct arguments for +.IR window . +.SS Window control +Each window behaves as a separate terminal with at least one process +associated with it. +When a window is created, a new process (usually a shell; see +.IR rc (1)) +is established and bound to the window as a new process group. +Initially, each window acts as a simple terminal that displays character text; +the standard input and output of its processes +are attached to +.BR /dev/cons . +Other special files, accessible to the processes running in a window, +may be used to make the window a more general display. +Some of these are mentioned here; the complete set is +discussed in +.IR rio (4). +.PP +One window is +.IR current , +and is indicated with a dark border and text; +characters typed on the keyboard are available in the +.B /dev/cons +file of the process in the current window. +Characters written on +.B /dev/cons +appear asynchronously in the associated window whether or not the window +is current. +.PP +Windows are created, deleted and rearranged using the mouse. +Clicking (pressing and releasing) mouse button 1 in a non-current +window makes that window current and brings it in front of +any windows that happen to be overlapping it. +When the mouse cursor points to the background area or is in +a window that has not claimed the mouse for its own use, +pressing mouse button 3 activates a +menu of window operations provided by +.IR rio . +Releasing button 3 then selects an operation. +At this point, a gunsight or cross cursor indicates that +an operation is pending. +The button 3 menu operations are: +.TF Resize +.TP +.B New +Create a window. +Press button 3 where one corner of the new rectangle should +appear (cross cursor), and move the mouse, while holding down button 3, to the +diagonally opposite corner. +Releasing button 3 creates the window, and makes it current. +Very small windows may not be created. +.TP +.B Resize +Change the size and location of a window. +First click button 3 in the window to be changed +(gunsight cursor). +Then sweep out a window as for the +.B New +operation. +The window is made current. +.TP +.B Move +Move a window to another location. +After pressing and holding button 3 over the window to be moved (gunsight cursor), +indicate the new position by dragging the rectangle to the new location. +The window is made current. +Windows may be moved partially off-screen. +.TP +.B Delete +Delete a window. Click in the window to be deleted (gunsight cursor). +Deleting a window causes a +.L hangup +note to be sent to all processes in the window's process group +(see +.IR notify (2)). +.TP +.B Hide +Hide a window. Click in the window to be hidden (gunsight cursor); +it will be moved off-screen. +Each hidden window is given a menu entry in the button 3 menu according to the +value of the file +.BR /dev/label , +which +.I rio +maintains +(see +.IR rio (4)). +.TP +.I label +Restore a hidden window. +.PD +.PP +Windows may also be arranged by dragging their borders. +Pressing button 1 or 2 over a window's border allows one to +move the corresponding edge or corner, while button 3 +moves the whole window. +.PD +.SS Text windows +Characters typed on the keyboard or written to +.B /dev/cons +collect in the window to form +a long, continuous document. +.PP +There is always some +.I selected +.IR text , +a contiguous string marked on the screen by reversing its color. +If the selected text is a null string, it is indicated by a hairline cursor +between two characters. +The selected text +may be edited by mousing and typing. +Text is selected by pointing and clicking button 1 +to make a null-string selection, or by pointing, +then sweeping with button 1 pressed. +Text may also be selected by double-clicking: +just inside a matched delimiter-pair +with one of +.B {[(<«`'" +on the left and +.B }])>»`'" +on the right, it selects all text within +the pair; at the beginning +or end of a line, it selects the line; within or at the edge of an alphanumeric word, +it selects the word. +.PP +Characters typed on the keyboard replace the selected text; +if this text is not empty, it is placed in a +.I snarf buffer +common to all windows but distinct from that of +.IR sam (1). +.PP +Programs access the text in the window at a single point +maintained automatically by +.IR rio . +The +.I output point +is the location in the text where the next character written by +a program to +.B /dev/cons +will appear; afterwards, the output point is the null string +beyond the new character. +The output point is also the location in the text of the next character +that will be read (directly from the text in the window, +not from an intervening buffer) +by a program from +.BR /dev/cons . +When such a read will occur is, however, under control of +.I rio +and the user. +.PP +In general there is text in the window after the output point, +usually placed there by typing but occasionally by the editing +operations described below. +A pending read of +.B /dev/cons +will block until the text after the output point contains +a newline, whereupon the read may +acquire the text, up to and including the newline. +After the read, as described above, the output point will be at +the beginning of the next line of text. +In normal circumstances, therefore, typed text is delivered +to programs a line at a time. +Changes made by typing or editing before the text is read will not +be seen by the program reading it. +If the program in the window does not read the terminal, +for example if it is a long-running computation, there may +accumulate multiple lines of text after the output point; +changes made to all this text will be seen when the text +is eventually read. +This means, for example, that one may edit out newlines in +unread text to forestall the associated text being read when +the program finishes computing. +This behavior is very different from most systems. +.PP +Even when there are newlines in the output text, +.I rio +will not honor reads if the window is in +.I hold +.IR mode , +which is indicated by a white cursor and blue text and border. +The ESC character toggles hold mode. +Some programs, such as +.IR mail (1), +automatically turn on hold mode to simplify the editing of multi-line text; +type ESC when done to allow +.I mail +to read the text. +.PP +An EOT character (control-D) behaves exactly like newline except +that it is not delivered to a program when read. +Thus on an empty line an EOT serves to deliver an end-of-file indication: +the read will return zero characters. +Like newlines, unread EOTs may be successfully edited out of the text. +The BS character (control-H) erases the character before the selected text. +The ETB character (control-W) erases any nonalphanumeric characters, then +the alphanumeric word just before the selected text. +`Alphanumeric' here means non-blanks and non-punctuation. +The NAK character (control-U) erases the text after the output point, +and not yet read by a program, but not more than one line. +All these characters are typed on the keyboard and hence replace +the selected text; for example, typing a BS with a word selected +places the word in the snarf buffer, removes it from the screen, +and erases the character before the word. +.PP +Text may be moved vertically within the window. +A scroll bar on the left of the window shows in its clear portion what fragment of the +total output text is visible on the screen, and in its gray part what +is above or below view; +it measures characters, not lines. +Mousing inside the scroll bar moves text: +clicking button 1 with the mouse pointing inside the scroll bar +brings the line at the top of the +window to the cursor's vertical location; +button 3 takes the line at the cursor to the top of the window; +button 2, treating the scroll bar as a ruler, jumps to the indicated portion +of the stored text. +Holding a button pressed in the scroll bar will cause the text +to scroll continuously until the button is released. +Also, a VIEW key (possibly with a different label; see +.IR keyboard (6)) +or down-arrow +scrolls forward +half a window, and up-arrow scrolls back. +.PP +The DEL character sends an +.L interrupt +note to all processes in the window's process group. +Unlike the other characters, the DEL, VIEW, and up- and down-arrow +keys do not affect the selected text. +.PP +Normally, written output to a window blocks when +the text reaches the end of the screen; +a button 2 menu item toggles scrolling. +.PP +Other editing operations are selected from a menu on button 2. +The +.B cut +operation deletes the selected text +from the screen and puts it in the snarf buffer; +.B snarf +copies the selected text to the buffer without deleting it; +.B paste +replaces the selected text with the contents of the buffer; +and +.B send +copies the snarf buffer to just after the output point, adding a final newline +if missing. +.B Paste +will sometimes and +.B send +will always place text after the output point; the text so placed +will behave exactly as described above. Therefore when pasting +text containing newlines after the output point, it may be prudent +to turn on hold mode first. +.PP +The +.B plumb +menu item sends the contents of the selection (not the snarf buffer) to the +.IR plumber (4). +If the selection is empty, it sends the white-space-delimited text +containing the selection (typing cursor). +A typical use of this feature is to tell the editor to find the source of an error +by plumbing the file and line information in a compiler's diagnostic. +.SS Raw text windows +Opening or manipulating certain files served by +.IR rio +suppresses some of the services supplied to ordinary text windows. +While the file +.B /dev/mouse +is open, any mouse operations are the responsibility of another program +running in the window. Thus, +.I rio +refrains from maintaining +the scroll bar, +supplying text editing or menus, interpreting the +VIEW key as a request to scroll, and also turns scrolling on. +.PP +The file +.B /dev/consctl +controls interpretation of keyboard input. +In particular, a raw mode may be set: +in a raw-input window, no typed keyboard characters are special, +they are not echoed to the screen, and all are passed +to a program immediately upon reading, instead of being gathered into +lines. +.SS Graphics windows +A program that holds +.B /dev/mouse +and +.B /dev/consctl +open after putting the console in raw mode +has complete control of the window: +it interprets all mouse events, gets all keyboard characters, +and determines what appears on the screen. +.SH FILES +.TF /srv/riowctl.\fIuser\fP.\fIpid\fP +.TP +.B /lib/font/bit/* +font directories +.TP +.B /mnt/wsys +Files served by +.I rio +(also unioned in +.B /dev +in a window's name space, before the terminal's real +.B /dev +files) +.TP +.B /srv/rio.\fIuser\fP.\fIpid\fP +Server end of +.IR rio . +.TP +.B /srv/riowctl.\fIuser\fP.\fIpid\fP +Named pipe for +.I wctl +messages. +.SH SOURCE +.TF /sys/src/cmd/rio +.TP +.B /sys/src/cmd/rio +.TP +.B /rc/bin/label +.TP +.B /rc/bin/window +.TP +.B /rc/bin/wloc +.SH "SEE ALSO" +.IR rio (4), +.IR rc (1), +.IR cpu (1), +.IR sam (1), +.IR mail (1), +.IR proof (1), +.IR graphics (2), +.IR frame (2), +.IR window (2), +.IR notify (2), +.IR cons (3), +.IR draw (3), +.IR mouse (3), +.IR keyboard (6) +.SH BUGS +The standard input of +.I window +is redirected to the newly created window, so there is no way to pipe the output +of a program to the standard input of the new window. +In some cases, +.IR plumb (1) +can be used to work around this limitation. |