rio 14 KB

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