rio 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513
  1. .TH RIO 1
  2. .SH NAME
  3. rio, label, window, wloc \- window system
  4. .SH SYNOPSIS
  5. .B rio
  6. [
  7. .BI "-i '"cmd '
  8. ]
  9. [
  10. .BI "-k '"kbdcmd '
  11. ]
  12. [
  13. .B -s
  14. ]
  15. [
  16. .B -f
  17. .I font
  18. ]
  19. .PP
  20. .B label
  21. .I name
  22. .PP
  23. .B window
  24. [
  25. .B -m
  26. ] [
  27. .B -r
  28. .I minx miny maxx maxy
  29. ] [
  30. .B -dx
  31. .I n
  32. ] [
  33. .B -dy
  34. .I n
  35. ] [
  36. .B -minx
  37. .I n
  38. ] [
  39. .B -miny
  40. .I n
  41. ] [
  42. .B -maxx
  43. .I n
  44. ] [
  45. .B -maxy
  46. .I n
  47. ] [
  48. .B -cd
  49. .I dir
  50. ] [
  51. .B -hide
  52. ] [
  53. .I cmd
  54. .I arg ...
  55. ]
  56. .PP
  57. .B wloc
  58. .SH DESCRIPTION
  59. .I Rio
  60. manages asynchronous layers of text, or windows, on a raster display.
  61. It also serves a variety of files for communicating with
  62. and controlling windows; these are discussed in section
  63. .IR rio (4).
  64. .SS Commands
  65. The
  66. .I rio
  67. command starts a new instance of the window system.
  68. Its
  69. .B -i
  70. option names a startup script, which typically contains several
  71. .I window
  72. commands generated by
  73. .IR wloc .
  74. The
  75. .B -k
  76. option causes
  77. .I rio
  78. to run the command
  79. .I kbdcmd
  80. at startup and allow it to provide characters as keyboard input; the
  81. .B keyboard
  82. program described in
  83. .IR bitsyload (1)
  84. is the usual choice.
  85. .PP
  86. The
  87. .B -s
  88. option initializes windows so that text scrolls;
  89. the default is not to scroll.
  90. The
  91. .I font
  92. argument names a font used to display text, both in
  93. .IR rio 's
  94. menus
  95. and as a default for any programs running in its windows; it also
  96. establishes the
  97. environment variable
  98. .BR $font .
  99. If
  100. .B -f
  101. is not given,
  102. .I rio
  103. uses the imported value of
  104. .BR $font
  105. if set; otherwise it imports the default font from the underlying graphics
  106. server, usually the terminal's operating system.
  107. .PP
  108. The
  109. .I label
  110. command changes a window's identifying name.
  111. .PP
  112. The
  113. .I window
  114. command creates a window.
  115. By default, it creates a shell window and sizes and places it automatically.
  116. The geometry arguments control the size
  117. .IB ( dx ,
  118. .BR dy )
  119. and placement
  120. .RB ( minx ,
  121. .BR miny ,
  122. .BR maxx ,
  123. .BR maxy ;
  124. .BR hide
  125. causes the window to be created off-screen); and working directory
  126. .RB ( cd ).
  127. the units are pixels with the
  128. upper left corner of the screen at (0, 0).
  129. The optional command and arguments define which program to run in the window.
  130. .PP
  131. By default,
  132. .I window
  133. uses
  134. .B /dev/wctl
  135. (see
  136. .IR rio (4))
  137. to create the window and run the command. Therefore, the window and command
  138. will be created by
  139. .I rio
  140. and run in a new file name space, just as if the window had been created using the interactive menu.
  141. However, the
  142. .B -m
  143. option uses the file server properties of
  144. .I rio
  145. to
  146. .B mount
  147. (see
  148. .IR bind (1))
  149. the new window's name space within the name space of the program calling
  150. .IR window .
  151. This means, for example, that running
  152. .B window
  153. in a CPU window will create another window whose command runs on the terminal, where
  154. .I rio
  155. is running; while
  156. .B window
  157. .B -m
  158. will create another window whose command runs on the CPU server.
  159. .PP
  160. The
  161. .I wloc
  162. command prints the coordinates and label of each window in its instance of
  163. .I rio
  164. and is used to construct arguments for
  165. .IR window .
  166. .SS Window control
  167. Each window behaves as a separate terminal with at least one process
  168. associated with it.
  169. When a window is created, a new process (usually a shell; see
  170. .IR rc (1))
  171. is established and bound to the window as a new process group.
  172. Initially, each window acts as a simple terminal that displays character text;
  173. the standard input and output of its processes
  174. are attached to
  175. .BR /dev/cons .
  176. Other special files, accessible to the processes running in a window,
  177. may be used to make the window a more general display.
  178. Some of these are mentioned here; the complete set is
  179. discussed in
  180. .IR rio (4).
  181. .PP
  182. One window is
  183. .IR current ,
  184. and is indicated with a dark border and text;
  185. characters typed on the keyboard are available in the
  186. .B /dev/cons
  187. file of the process in the current window.
  188. Characters written on
  189. .B /dev/cons
  190. appear asynchronously in the associated window whether or not the window
  191. is current.
  192. .PP
  193. Windows are created, deleted and rearranged using the mouse.
  194. Clicking (pressing and releasing) mouse button 1 in a non-current
  195. window makes that window current and brings it in front of
  196. any windows that happen to be overlapping it.
  197. When the mouse cursor points to the background area or is in
  198. a window that has not claimed the mouse for its own use,
  199. pressing mouse button 3 activates a
  200. menu of window operations provided by
  201. .IR rio .
  202. Releasing button 3 then selects an operation.
  203. At this point, a gunsight or cross cursor indicates that
  204. an operation is pending.
  205. The button 3 menu operations are:
  206. .TF Resize
  207. .TP
  208. .B New
  209. Create a window.
  210. Press button 3 where one corner of the new rectangle should
  211. appear (cross cursor), and move the mouse, while holding down button 3, to the
  212. diagonally opposite corner.
  213. Releasing button 3 creates the window, and makes it current.
  214. Very small windows may not be created.
  215. .TP
  216. .B Resize
  217. Change the size and location of a window.
  218. First click button 3 in the window to be changed
  219. (gunsight cursor).
  220. Then sweep out a window as for the
  221. .B New
  222. operation.
  223. The window is made current.
  224. .TP
  225. .B Move
  226. Move a window to another location.
  227. After pressing and holding button 3 over the window to be moved (gunsight cursor),
  228. indicate the new position by dragging the rectangle to the new location.
  229. The window is made current.
  230. Windows may be moved partially off-screen.
  231. .TP
  232. .B Delete
  233. Delete a window. Click in the window to be deleted (gunsight cursor).
  234. Deleting a window causes a
  235. .L hangup
  236. note to be sent to all processes in the window's process group
  237. (see
  238. .IR notify (2)).
  239. .TP
  240. .B Hide
  241. Hide a window. Click in the window to be hidden (gunsight cursor);
  242. it will be moved off-screen.
  243. Each hidden window is given a menu entry in the button 3 menu according to the
  244. value of the file
  245. .BR /dev/label ,
  246. which
  247. .I rio
  248. maintains
  249. (see
  250. .IR rio (4)).
  251. .TP
  252. .I label
  253. Restore a hidden window.
  254. .PD
  255. .PP
  256. Windows may also be arranged by dragging their borders.
  257. Pressing button 1 or 2 over a window's border allows one to
  258. move the corresponding edge or corner, while button 3
  259. moves the whole window.
  260. .PD
  261. .SS Text windows
  262. Characters typed on the keyboard or written to
  263. .B /dev/cons
  264. collect in the window to form
  265. a long, continuous document.
  266. .PP
  267. There is always some
  268. .I selected
  269. .IR text ,
  270. a contiguous string marked on the screen by reversing its color.
  271. If the selected text is a null string, it is indicated by a hairline cursor
  272. between two characters.
  273. The selected text
  274. may be edited by mousing and typing.
  275. Text is selected by pointing and clicking button 1
  276. to make a null-string selection, or by pointing,
  277. then sweeping with button 1 pressed.
  278. Text may also be selected by double-clicking:
  279. just inside a matched delimiter-pair
  280. with one of
  281. .B {[(<«`'"
  282. on the left and
  283. .B }])>»`'"
  284. on the right, it selects all text within
  285. the pair; at the beginning
  286. or end of a line, it selects the line; within or at the edge of an alphanumeric word,
  287. it selects the word.
  288. .PP
  289. Characters typed on the keyboard replace the selected text;
  290. if this text is not empty, it is placed in a
  291. .I snarf buffer
  292. common to all windows but distinct from that of
  293. .IR sam (1).
  294. .PP
  295. Programs access the text in the window at a single point
  296. maintained automatically by
  297. .IR rio .
  298. The
  299. .I output point
  300. is the location in the text where the next character written by
  301. a program to
  302. .B /dev/cons
  303. will appear; afterwards, the output point is the null string
  304. beyond the new character.
  305. The output point is also the location in the text of the next character
  306. that will be read (directly from the text in the window,
  307. not from an intervening buffer)
  308. by a program from
  309. .BR /dev/cons .
  310. When such a read will occur is, however, under control of
  311. .I rio
  312. and the user.
  313. .PP
  314. In general there is text in the window after the output point,
  315. usually placed there by typing but occasionally by the editing
  316. operations described below.
  317. A pending read of
  318. .B /dev/cons
  319. will block until the text after the output point contains
  320. a newline, whereupon the read may
  321. acquire the text, up to and including the newline.
  322. After the read, as described above, the output point will be at
  323. the beginning of the next line of text.
  324. In normal circumstances, therefore, typed text is delivered
  325. to programs a line at a time.
  326. Changes made by typing or editing before the text is read will not
  327. be seen by the program reading it.
  328. If the program in the window does not read the terminal,
  329. for example if it is a long-running computation, there may
  330. accumulate multiple lines of text after the output point;
  331. changes made to all this text will be seen when the text
  332. is eventually read.
  333. This means, for example, that one may edit out newlines in
  334. unread text to forestall the associated text being read when
  335. the program finishes computing.
  336. This behavior is very different from most systems.
  337. .PP
  338. Even when there are newlines in the output text,
  339. .I rio
  340. will not honor reads if the window is in
  341. .I hold
  342. .IR mode ,
  343. which is indicated by a white cursor and blue text and border.
  344. The ESC character toggles hold mode.
  345. Some programs, such as
  346. .IR mail (1),
  347. automatically turn on hold mode to simplify the editing of multi-line text;
  348. type ESC when done to allow
  349. .I mail
  350. to read the text.
  351. .PP
  352. An EOT character (control-D) behaves exactly like newline except
  353. that it is not delivered to a program when read.
  354. Thus on an empty line an EOT serves to deliver an end-of-file indication:
  355. the read will return zero characters.
  356. Like newlines, unread EOTs may be successfully edited out of the text.
  357. The BS character (control-H) erases the character before the selected text.
  358. The ETB character (control-W) erases any nonalphanumeric characters, then
  359. the alphanumeric word just before the selected text.
  360. `Alphanumeric' here means non-blanks and non-punctuation.
  361. The NAK character (control-U) erases the text after the output point,
  362. and not yet read by a program, but not more than one line.
  363. All these characters are typed on the keyboard and hence replace
  364. the selected text; for example, typing a BS with a word selected
  365. places the word in the snarf buffer, removes it from the screen,
  366. and erases the character before the word.
  367. .PP
  368. Text may be moved vertically within the window.
  369. A scroll bar on the left of the window shows in its clear portion what fragment of the
  370. total output text is visible on the screen, and in its gray part what
  371. is above or below view;
  372. it measures characters, not lines.
  373. Mousing inside the scroll bar moves text:
  374. clicking button 1 with the mouse pointing inside the scroll bar
  375. brings the line at the top of the
  376. window to the cursor's vertical location;
  377. button 3 takes the line at the cursor to the top of the window;
  378. button 2, treating the scroll bar as a ruler, jumps to the indicated portion
  379. of the stored text.
  380. Holding a button pressed in the scroll bar will cause the text
  381. to scroll continuously until the button is released.
  382. Also, a VIEW key (possibly with a different label; see
  383. .IR keyboard (6))
  384. or down-arrow
  385. scrolls forward
  386. half a window, and up-arrow scrolls back.
  387. .PP
  388. The DEL character sends an
  389. .L interrupt
  390. note to all processes in the window's process group.
  391. Unlike the other characters, the DEL, VIEW, and up- and down-arrow
  392. keys do not affect the selected text.
  393. .PP
  394. Normally, written output to a window blocks when
  395. the text reaches the end of the screen;
  396. a button 2 menu item toggles scrolling.
  397. .PP
  398. Other editing operations are selected from a menu on button 2.
  399. The
  400. .B cut
  401. operation deletes the selected text
  402. from the screen and puts it in the snarf buffer;
  403. .B snarf
  404. copies the selected text to the buffer without deleting it;
  405. .B paste
  406. replaces the selected text with the contents of the buffer;
  407. and
  408. .B send
  409. copies the snarf buffer to just after the output point, adding a final newline
  410. if missing.
  411. .B Paste
  412. will sometimes and
  413. .B send
  414. will always place text after the output point; the text so placed
  415. will behave exactly as described above. Therefore when pasting
  416. text containing newlines after the output point, it may be prudent
  417. to turn on hold mode first.
  418. .PP
  419. The
  420. .B plumb
  421. menu item sends the contents of the selection (not the snarf buffer) to the
  422. .IR plumber (4).
  423. If the selection is empty, it sends the white-space-delimited text
  424. containing the selection (typing cursor).
  425. A typical use of this feature is to tell the editor to find the source of an error
  426. by plumbing the file and line information in a compiler's diagnostic.
  427. .SS Raw text windows
  428. Opening or manipulating certain files served by
  429. .IR rio
  430. suppresses some of the services supplied to ordinary text windows.
  431. While the file
  432. .B /dev/mouse
  433. is open, any mouse operations are the responsibility of another program
  434. running in the window. Thus,
  435. .I rio
  436. refrains from maintaining
  437. the scroll bar,
  438. supplying text editing or menus, interpreting the
  439. VIEW key as a request to scroll, and also turns scrolling on.
  440. .PP
  441. The file
  442. .B /dev/consctl
  443. controls interpretation of keyboard input.
  444. In particular, a raw mode may be set:
  445. in a raw-input window, no typed keyboard characters are special,
  446. they are not echoed to the screen, and all are passed
  447. to a program immediately upon reading, instead of being gathered into
  448. lines.
  449. .SS Graphics windows
  450. A program that holds
  451. .B /dev/mouse
  452. and
  453. .B /dev/consctl
  454. open after putting the console in raw mode
  455. has complete control of the window:
  456. it interprets all mouse events, gets all keyboard characters,
  457. and determines what appears on the screen.
  458. .SH FILES
  459. .TF /srv/riowctl.\fIuser\fP.\fIpid\fP
  460. .TP
  461. .B /lib/font/bit/*
  462. font directories
  463. .TP
  464. .B /mnt/wsys
  465. Files served by
  466. .I rio
  467. (also unioned in
  468. .B /dev
  469. in a window's name space, before the terminal's real
  470. .B /dev
  471. files)
  472. .TP
  473. .B /srv/rio.\fIuser\fP.\fIpid\fP
  474. Server end of
  475. .IR rio .
  476. .TP
  477. .B /srv/riowctl.\fIuser\fP.\fIpid\fP
  478. Named pipe for
  479. .I wctl
  480. messages.
  481. .SH SOURCE
  482. .TF /sys/src/cmd/rio
  483. .TP
  484. .B /sys/src/cmd/rio
  485. .TP
  486. .B /rc/bin/label
  487. .TP
  488. .B /rc/bin/window
  489. .TP
  490. .B /rc/bin/wloc
  491. .SH "SEE ALSO"
  492. .IR rio (4),
  493. .IR rc (1),
  494. .IR cpu (1),
  495. .IR sam (1),
  496. .IR mail (1),
  497. .IR proof (1),
  498. .IR graphics (2),
  499. .IR frame (2),
  500. .IR window (2),
  501. .IR notify (2),
  502. .IR cons (3),
  503. .IR draw (3),
  504. .IR mouse (3),
  505. .IR keyboard (6)
  506. .SH BUGS
  507. The standard input of
  508. .I window
  509. is redirected to the newly created window, so there is no way to pipe the output
  510. of a program to the standard input of the new window.
  511. In some cases,
  512. .IR plumb (1)
  513. can be used to work around this limitation.