ref: d589632207181a7960607a5938f315422386b9cb
dir: /sys/man/4/rio/
.TH RIO 4 .SH NAME rio \- window system files .SH SYNOPSIS .B rio [ .B -i .BI ' cmd ' ] [ .B -k .BI ' kbdcmd ' ] [ .B -s ] [ .B -b ] [ .B -f .I font ] .SH DESCRIPTION The window system .I rio serves a variety of files for reading, writing, and controlling windows. Some of them are virtual versions of system files for dealing with the display, keyboard, and mouse; others control operations of the window system itself. .I Rio posts its service in the .B /srv directory, using a name constructed from a catenation of the user ID and a process id; the environment variable .BR $wsys is set to this service name within processes running under the control of each invocation of .IR rio . .PP A .I mount (see .IR bind (1)) of .B $wsys must specify a context under which the files are presented. There are three ways to specify a context via the attach specifier. An existing window id may be supplied to attach to their existing context, instructions may be given to create a new window (see wctl described below), or .B none may be given to gain a windowless context. .PP When a window is created either by the .I window command (see .IR rio (1)) or by using the menu supplied by .IR rio , this server is mounted on .BR /mnt/wsys and also .BR /dev ; the files mentioned here appear in both those directories. .PP Some of these files supply virtual versions of services available from the underlying environment, in particular the character terminal files .B cons and .B kbd (see .IR kbdfs (8)), and the mouse files .IR mouse (3) and .IR cursor , each specific to the window. Note that the .IR draw (3) device multiplexes itself; .IR rio places windows but does not mediate programs' access to the display device. .PP Other files are unique to .IR rio . .TF window .TP .B cons a virtual version of the standard terminal file from .IR kbdfs (8). .I Rio supplies extra editing features and a scroll bar (see .IR rio (1)). .TP .B consctl controls interpretation of console input. Writing strings to it sets these modes: .B rawon turns on raw mode; .B rawoff turns off raw mode; .B holdon turns on hold mode; .B holdoff turns off hold mode. Closing the file makes the window revert to default state (raw off, hold off). .TP .B kbd represents the raw keyboard events (see .IR kbdfs (8)) for the corresponding window. While open, navigation keys and input on the .IR cons file is disabled. .TP .B kbdtap provides access to the global keyboard input. When opened, global keyboard input to windows is instead given through writes to .BR kbdtap . .TP .B cursor Like .B mouse .RI ( q.v. ), a multiplexed version of the underlying device file, in this case representing the appearance of the mouse cursor when the mouse is within the corresponding window. .TP .B label initially contains a string with the process ID of the lead process in the window and the command being executed there. It may be written and is used as a tag when the window is hidden. .TP .B mouse is a virtual version of the standard mouse file (see .IR mouse (3)). Opening it turns off scrolling, editing, and .IR rio -supplied menus in the associated window. In a standard mouse message, the first character is .BR m , but .I rio will send an otherwise normal message with the first character .B r if the corresponding window has been resized. The application must then call .B getwindow (see .IR graphics (2)) to re-establish its state in the newly moved or changed window. Reading the .B mouse file blocks until the mouse moves or a button changes. Mouse movements or button changes are invisible when the mouse cursor is located outside the window, except that if the mouse leaves the window while a button is pressed, it will continue receiving mouse data until the button is released. .TP .B screen is a read-only file reporting the depth, coordinates, and raster image corresponding to the entire underlying display, in the uncompressed format defined in .IR image (6). .TP .B snarf returns the string currently in the snarf buffer. Writing this file sets the contents of the snarf buffer. When .I rio is run recursively, the inner instance uses the snarf buffer of the parent, rather than managing its own. .TP .B text returns the full contents of the window. Write appends to the window. Truncating clears the windows contents. .TP .B wctl may be read or written. When read, it returns the location of the window as four decimal integers, padded to 12 characters as described in .IR image (6): upper left .I x and .IR y , lower right .I x and .IR y . Following these numbers are strings, also padded to 12 characters, describing the window's state: .B current or .BR notcurrent ; .B hidden or .BR visible . A subsequent read will block until the window changes size, location, or state. When written to, .B wctl accepts messages to change the size or placement of the associated window, and to create new windows. The messages are in a command-line-like format, with a command name, possibly followed by options introduced by a minus sign. The options must be separated by blanks, for example .B -dx 100 rather than .BR -dx100 . .IP The commands are .B resize (change the size and position of the window), .B move (move the window), .B scroll (enable scrolling in the window), .B noscroll (disable scrolling), .B set (change selected properties of the window), .B top (move the window to the `top', making it fully visible), .B bottom (move the window to the `bottom', perhaps partially or totally obscuring it), .B hide (hide the window), .B unhide (restore a hidden window), .B current (make the window the recipient of keyboard and mouse input), .B delete (close the window and terminate its associated processes) and .B new (make a new window). The .B top and .B bottom commands do not change whether the window is current or not. Neither .B top nor .B bottom has any options. .IP The .BR resize , .BR move , and .B new commands accept .B -minx .RI [±] n , .B -miny .RI [±] n , .B -maxx .RI [±] n , and .B -maxy .RI [±] n options to set the position of the corresponding edge of the window. They also accept an option .B -r .I minx miny maxx maxy to set all four at once. The .B resize and .B new commands accept .B -dx .I n and .B -dy .I n to set the width and height of the window. By default, .I rio will choose a convenient geometry automatically. .IP Finally, the .B new command accepts an optional shell command and argument string, given as plain strings after any standard options, to run in the window instead of the default .B rc .B -i (see .IR rc (1)). The .B -pid .I pid option to .B new identifies the .I pid of the process whose `note group' should receive interrupt and hangup notes generated in the window. The initial working directory of the new window may be set by a .B -cd .I directory option. The .B -hide option causes the window to be created off-screen, in the hidden state, while .B -scroll and .B -noscroll set the initial scrolling state of the window; the default is that of the main program. .IP The .B set command accepts a set of parameters in the same style; only .B -pid .I pid is implemented. .TP .B wdir is a read/write text file containing .IR rio 's idea of the current working directory of the process running in the window. It is used to fill in the .B wdir field of .IR plumb (6) messages .I rio generates from the .B plumb menu item on button 2. The file is writable so the program may update it; .I rio is otherwise unaware of .IR chdir (2) calls its clients make. In particular, .IR rc (1) maintains .B /dev/wdir in default .IR rio (1) windows. .TP .B winid returns the unique and unchangeable ID for the window; it is a string of digits. .TP .B window is the virtual version of .BR /dev/screen . It contains the depth, coordinates, and uncompressed raster image corresponding to the associated window. .TP .B wsys is a directory containing a subdirectory for each window, named by the unique ID for that window. Within each subdirectory are entries corresponding to several of the special files associated with that window: .BR cons , .BR consctl , .BR label , .BR mouse , etc. .SH EXAMPLES Cause a window to be created in the upper left corner, and the word .L hi to be printed there. .IP .EX mount $wsys /tmp 'new -r 0 0 128 64 -pid '$pid echo hi > /tmp/cons .EE .PP Start .IR sam (1) in a large horizontal window. .IP .EX echo new -dx 800 -dy 200 -cd /sys/src/cmd sam > /dev/wctl .EE .PP Print the screen image of window with id 123. .IP .EX lp /dev/wsys/123/window .EE .PP Access wctl from outside of rio using a none attach: .IP .EX mount /srv/rio.$user.$riopid /tmp/ none echo new -dx 800 -dy 200 rc > /tmp/wctl .EE .SH SOURCE .B /sys/src/cmd/rio .SH SEE ALSO .IR rio (1), .IR draw (3), .IR mouse (3), .IR kbdfs (8), .IR event (2), .IR graphics (2).