Subversion Repositories planix.SVN

.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

] [

.B -scroll

] [

.B -noscroll

] [

.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 );

the units are pixels with the

upper left corner of the screen at (0, 0).

The

.B hide

option causes the window to be created off-screen.

The

.B scroll

and

.B noscroll

options set the scroll mode.

The

.B cd

option sets the working directory.

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

An ACK character (control-F) or Insert character triggers file name completion

for the preceding string (see

.IR complete (2)).

.PP

Typing a left or right arrow moves the cursor one character in that direction.

Typing an SOH character (control-A) moves the cursor to the beginning of the

current line; an ENQ character (control-E) moves to the end.

.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 page down

or down-arrow

scrolls forward

half a window, and page up or up-arrow scrolls back.

Typing the home key scrolls to the top of the window; typing the end key scrolls

to the bottom.

.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.

The left (right) arrow key moves the selection to one character

before (after) the current selection.

.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.