RIO(1)                                                     RIO(1)

     NAME
          rio, label, window, wloc - window system

     SYNOPSIS
          rio [ -i 'cmd' ] [ -k 'kbdcmd' ] [ -s ] [ -b ] [ -f font ]

          label name

          window [ -m ] [ -r minx miny maxx maxy ] [ -dx n ] [ -dy n ]
          [ -minx n ] [ -miny n ] [ -maxx n ] [ -maxy n ] [ -cd dir ]
          [ -hide ] [ -scroll ] [ -noscroll ] [ cmd arg ... ]

          wloc

     DESCRIPTION
          Rio manages asynchronous layers of text, or windows, on a
          raster display.  It also serves a variety of files for com-
          municating with and controlling windows; these are discussed
          in section rio(4).

        Commands
          The rio command starts a new instance of the window system.
          Its -i option names a startup script, which typically con-
          tains several window commands generated by wloc. The -k
          option causes rio to run the command kbdcmd at startup and
          allow it to provide characters as keyboard input; the
          keyboard program described in bitsyload(1) is the usual
          choice.

          The -s option initializes windows so that text scrolls; the
          default is not to scroll.  The -b option reverses the normal
          color scheme for windows, painting white text on a black
          background.  The font argument names a font used to display
          text, both in rio's menus and as a default for any programs
          running in its windows; it also establishes the environment
          variable $font.  If -f is not given, rio uses the imported
          value of $font if set; otherwise it imports the default font
          from the underlying graphics server, usually the terminal's
          operating system.

          The label command changes a window's identifying name.

          The window command creates a window.  By default, it creates
          a shell window and sizes and places it automatically.  The
          geometry arguments control the size (dx, dy) and placement
          (minx, miny, maxx, maxy); the units are pixels with the
          upper left corner of the screen at (0, 0).  The hide option
          causes the window to be created off-screen.  The scroll and
          noscroll options set the scroll mode.  The cd option sets
          the working directory.  The optional command and arguments

     Page 1                       Plan 9             (printed 3/28/24)

     RIO(1)                                                     RIO(1)

          define which program to run in the window.

          By default, window uses /dev/wctl (see rio(4)) to create the
          window and run the command.  Therefore, the window and com-
          mand will be created by rio and run in a new file name
          space, just as if the window had been created using the
          interactive menu.  However, the -m option uses the file
          server properties of rio to mount (see bind(1)) the new
          window's name space within the name space of the program
          calling window. This means, for example, that running window
          in a CPU window will create another window whose command
          runs on the terminal, where rio is running; while window -m
          will create another window whose command runs on the CPU
          server.

          The wloc command prints the coordinates and label of each
          window in its instance of rio and is used to construct argu-
          ments for window.

        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 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 /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 rio(4).

          One window is current, and is indicated with a dark border
          and text; characters typed on the keyboard are available in
          the /dev/cons file of the process in the current window.
          Characters written on /dev/cons appear asynchronously in the
          associated window whether or not the window is current.

          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 opera-
          tions provided by rio. Releasing button 3 then selects an
          operation.  At this point, a gunsight or cross cursor indi-
          cates that an operation is pending.  The button 3 menu oper-
          ations are:

          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

     Page 2                       Plan 9             (printed 3/28/24)

     RIO(1)                                                     RIO(1)

                  diagonally opposite corner.  Releasing button 3 cre-
                  ates the window, and makes it current.  Very small
                  windows may not be created.
          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 New
                  operation.  The window is made current.
          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 par-
                  tially off-screen.
          Delete  Delete a window.  Click in the window to be deleted
                  (gunsight cursor).  Deleting a window causes a
                  `hangup' note to be sent to all processes in the
                  window's process group (see notify(2)).
          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 but-
                  ton 3 menu according to the value of the file
                  /dev/label, which rio maintains (see rio(4)).
          label   Restore a hidden window.

          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.

        Text windows
          Characters typed on the keyboard or written to /dev/cons
          collect in the window to form a long, continuous document.

          There is always some selected 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 hair-
          line cursor between two characters.  The selected text may
          be edited by mousing and typing.  Text is selected by point-
          ing 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 {[(<«`'" on the left and
          }])>»`'" 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.

          Characters typed on the keyboard replace the selected text;
          if this text is not empty, it is placed in a snarf buffer
          common to all windows but distinct from that of sam(1).

          Programs access the text in the window at a single point

     Page 3                       Plan 9             (printed 3/28/24)

     RIO(1)                                                     RIO(1)

          maintained automatically by rio. The output point is the
          location in the text where the next character written by a
          program to /dev/cons will appear; afterwards, the output
          point is the null string beyond the new character.  The out-
          put point is also the location in the text of the next char-
          acter that will be read (directly from the text in the win-
          dow, not from an intervening buffer) by a program from
          /dev/cons.  When such a read will occur is, however, under
          control of rio and the user.

          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
          /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, there-
          fore, 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 dif-
          ferent from most systems.

          Even when there are newlines in the output text, rio will
          not honor reads if the window is in hold mode, which is
          indicated by a white cursor and blue text and border.  The
          ESC character toggles hold mode.  Some programs, such as
          mail(1), automatically turn on hold mode to simplify the
          editing of multi-line text; type ESC when done to allow mail
          to read the text.

          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

     Page 4                       Plan 9             (printed 3/28/24)

     RIO(1)                                                     RIO(1)

          selected places the word in the snarf buffer, removes it
          from the screen, and erases the character before the word.

          An ACK character (control-F) or Insert character triggers
          file name completion for the preceding string (see
          complete(2)).

          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. The STX charac-
          ter (control-B) moves the cursor to the output point.

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

          The DEL character sends an `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 selec-
          tion to one character before (after) the current selection.

          Normally, written output to a window blocks when the text
          reaches the end of the screen; a button 2 menu item toggles
          scrolling.

          Other editing operations are selected from a menu on button
          2.  The cut operation deletes the selected text from the
          screen and puts it in the snarf buffer; snarf copies the
          selected text to the buffer without deleting it; paste
          replaces the selected text with the contents of the buffer;
          and send copies the snarf buffer to just after the output
          point, adding a final newline if missing.  Paste will some-
          times and 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.

     Page 5                       Plan 9             (printed 3/28/24)

     RIO(1)                                                     RIO(1)

          The plumb menu item sends the contents of the selection (not
          the snarf buffer) to the plumber(4). If the selection is
          empty, it sends the white-space-delimited text containing
          the selection (typing cursor).  A typical use of this fea-
          ture is to tell the editor to find the source of an error by
          plumbing the file and line information in a compiler's diag-
          nostic.

        Raw text windows
          Opening or manipulating certain files served by rio sup-
          presses some of the services supplied to ordinary text win-
          dows.  While the file /dev/mouse is open, any mouse opera-
          tions are the responsibility of another program running in
          the window.  Thus, 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.

          The file /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.

        Graphics windows
          A program that holds /dev/mouse and /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.

     FILES
          /lib/font/bit/*        font directories
          /mnt/wsys              Files served by rio (also unioned in
                                 /dev in a window's name space, before
                                 the terminal's real /dev files)
          /srv/rio.user.pid      Server end of rio.
          /srv/riowctl.user.pid  Named pipe for wctl messages.

     SOURCE
          /sys/src/cmd/rio
          /rc/bin/label
          /rc/bin/window
          /rc/bin/wloc

     SEE ALSO
          rio(4), rc(1), cpu(1), sam(1), mail(1), proof(1),
          graphics(2), frame(2), window(2), notify(2), cons(3),
          draw(3), mouse(3), keyboard(6)

     BUGS
          The standard input of window is redirected to the newly cre-
          ated window, so there is no way to pipe the output of a

     Page 6                       Plan 9             (printed 3/28/24)

     RIO(1)                                                     RIO(1)

          program to the standard input of the new window.  In some
          cases, plumb(1) can be used to work around this limitation.

     Page 7                       Plan 9             (printed 3/28/24)