rio 8.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407
  1. .TH RIO 4
  2. .SH NAME
  3. rio \- window system files
  4. .SH SYNOPSIS
  5. .B rio
  6. [
  7. .B -i
  8. .BI ' cmd '
  9. ]
  10. [
  11. .B -s
  12. ]
  13. [
  14. .B -f
  15. .I font
  16. ]
  17. .SH DESCRIPTION
  18. The window system
  19. .I rio
  20. serves a variety of files for reading, writing, and controlling
  21. windows.
  22. Some of them are virtual versions of system files for dealing
  23. with the display, keyboard, and mouse; others control operations
  24. of the window system itself.
  25. .I Rio
  26. posts its service in the
  27. .B /srv
  28. directory, using a
  29. name constructed from a catenation of the user ID
  30. and a process id; the environment variable
  31. .BR $wsys
  32. is set to this service name within processes running under the control
  33. of each invocation of
  34. .IR rio .
  35. Similarly,
  36. .I rio
  37. posts a named pipe to access the window creation features
  38. (see
  39. .B window
  40. in
  41. .IR rio (1))
  42. from outside
  43. its name space; this is named in
  44. .BR $wctl .
  45. .PP
  46. A
  47. .I mount
  48. (see
  49. .IR bind (1))
  50. of
  51. .B $wsys
  52. causes
  53. .I rio
  54. to create a new window; the attach specifier in the
  55. .I mount
  56. gives the coordinates of the created window.
  57. The syntax of the specifier is the same as the arguments to
  58. .B window
  59. (see
  60. .IR rio (1)).
  61. By default, the window is sized and placed automatically.
  62. It is always necessary, however, to provide the process id of the
  63. process to whom to deliver notes generated by DEL characters and hangups
  64. in that window.
  65. That pid is specified by including the string
  66. .B -pid
  67. .I pid
  68. in the attach specifier. (See the Examples section
  69. .IR q.v. )
  70. .PP
  71. When a window is created either by
  72. the
  73. .I window
  74. command
  75. (see
  76. .IR rio (1))
  77. or by using the menu supplied by
  78. .IR rio ,
  79. this server is mounted on
  80. .BR /mnt/wsys
  81. and also
  82. .BR /dev ;
  83. the files mentioned here
  84. appear in both those directories.
  85. .PP
  86. Some of these files supply virtual versions of services available from the underlying
  87. environment, in particular the character terminal files
  88. .IR cons (3),
  89. and the mouse files
  90. .IR mouse (3)
  91. and
  92. .IR cursor ,
  93. each specific to the window.
  94. Note that the
  95. .IR draw (3)
  96. device multiplexes itself;
  97. .IR rio
  98. places windows but does not mediate programs' access to the display device.
  99. .PP
  100. Other files are unique to
  101. .IR rio .
  102. .TF window
  103. .TP
  104. .B cons
  105. is a virtual version of the standard terminal file
  106. .IR cons (3).
  107. .I Rio
  108. supplies extra editing features and a scroll bar
  109. (see
  110. .IR rio (1)).
  111. .TP
  112. .B consctl
  113. controls interpretation of keyboard input.
  114. Writing strings to it sets these modes:
  115. .B rawon
  116. turns on raw mode;
  117. .B rawoff
  118. turns off raw mode;
  119. .B holdon
  120. turns on hold mode;
  121. .B holdoff
  122. turns off hold mode.
  123. Closing the file makes the window revert to default state
  124. (raw off, hold off).
  125. .TP
  126. .B cursor
  127. Like
  128. .B mouse
  129. .RI ( q.v. ),
  130. a multiplexed version of the underlying device file, in this case representing the
  131. appearance of the mouse cursor when the mouse is within the corresponding window.
  132. .TP
  133. .B label
  134. initially contains a string with the process ID of the lead process
  135. in the window and the command being executed there.
  136. It may be written and is used as a tag when the window is hidden.
  137. .TP
  138. .B mouse
  139. is a virtual version of the standard mouse file (see
  140. .IR mouse (3)).
  141. Opening it turns off scrolling, editing, and
  142. .IR rio -supplied
  143. menus in the associated
  144. window.
  145. In a standard mouse message, the first character is
  146. .BR m ,
  147. but
  148. .I rio
  149. will send an otherwise normal message with the first character
  150. .B r
  151. if the corresponding window has been resized.
  152. The application must then call
  153. .B getwindow
  154. (see
  155. .IR graphics (2))
  156. to re-establish its state in the newly moved or changed window.
  157. Reading the
  158. .B mouse
  159. file blocks until the mouse moves or a button changes.
  160. Mouse movements or button changes are invisible when the mouse cursor
  161. is located outside the window, except that if the mouse leaves the window
  162. while a button is pressed, it will continue receiving mouse data until the button is released.
  163. .TP
  164. .B screen
  165. is a read-only file reporting the depth, coordinates, and raster image corresponding to the entire
  166. underlying display,
  167. in the uncompressed format defined in
  168. .IR image (6).
  169. .TP
  170. .B snarf
  171. returns the string currently in the snarf buffer.
  172. Writing this file sets the contents of the snarf buffer.
  173. When
  174. .I rio
  175. is run recursively, the inner instance uses the snarf buffer of the parent, rather than
  176. managing its own.
  177. .TP
  178. .B text
  179. returns the full contents of the window.
  180. It may not be written.
  181. .TP
  182. .B wctl
  183. may be read or written.
  184. When read, it returns the location of the window as four decimal integers formatted
  185. in the usual 12-character style: upper left
  186. .I x
  187. and
  188. .IR y ,
  189. lower right
  190. .I x
  191. and
  192. .IR y .
  193. Following these numbers are strings describing the window's state:
  194. .B hidden
  195. or
  196. .BR visible ;
  197. .B current
  198. or
  199. .BR notcurrent .
  200. A subsequent read will block until the window changes size, location, or state.
  201. When written to,
  202. .B wctl
  203. accepts messages to change the size or placement of the associated window,
  204. and to create new windows.
  205. The messages are in a command-line like format, with a command name,
  206. possibly followed by options introduced by a minus sign.
  207. The options must be separated by blanks, for example
  208. .B -dx 100
  209. rather than
  210. .BR -dx100 .
  211. .IP
  212. The commands are
  213. .B resize
  214. (change the size and position of the window),
  215. .B move
  216. (move the window),
  217. .B scroll
  218. (enable scrolling in the window),
  219. .B noscroll
  220. (disable scrolling),
  221. .B set
  222. (change selected properties of the window),
  223. .B top
  224. (move the window to the `top', making it fully visible),
  225. .B bottom
  226. (move the window to the `bottom', perhaps partially or totally obscuring it),
  227. .B hide
  228. (hide the window),
  229. .B unhide
  230. (restore a hidden window),
  231. .B current
  232. (make the window the recipient of keyboard and mouse input),
  233. and
  234. .B new
  235. (make a new window).
  236. The
  237. .B top
  238. and
  239. .B bottom
  240. commands do not change whether the window is current or not;
  241. the others always make the affected window current.
  242. .IP
  243. Neither
  244. .B top
  245. nor
  246. .B bottom
  247. has any options.
  248. The
  249. .BR resize ,
  250. .BR move ,
  251. and
  252. .B new
  253. commands accept
  254. .B -minx
  255. .IR n ,
  256. .B -miny
  257. .IR n ,
  258. .B -maxx
  259. .IR n ,
  260. and
  261. .BR -maxy
  262. .I n
  263. options to set the position of the corresponding edge of the window.
  264. They also accept an option
  265. .B -r
  266. .I minx miny maxx maxy
  267. to set all four at once.
  268. The
  269. .B resize
  270. and
  271. .B new
  272. commands accept
  273. .B -dx
  274. .I n
  275. and
  276. .B -dy
  277. .I n
  278. to set the width and height of the window.
  279. By default,
  280. .I rio
  281. will choose a convenient geometry automatically.
  282. .IP
  283. Finally, the
  284. .B new
  285. command accepts an optional shell command and argument string,
  286. given as plain strings after any standard options, to run in the window
  287. instead of the default
  288. .B rc
  289. .B -i
  290. (see
  291. .IR rc (1)).
  292. The
  293. .B -pid
  294. .I pid
  295. option to
  296. .B new
  297. identifies the
  298. .I pid
  299. of the process whose `note group' should receive interrupt
  300. and hangup notes generated in the window.
  301. The initial working directory of the new window may be set by a
  302. .B -cd
  303. .I directory
  304. option.
  305. The
  306. .B -hide
  307. option causes the window to be created off-screen, in the hidden state, while
  308. .B -scroll
  309. and
  310. .B -noscroll
  311. set the initial scrolling state of the window; the default is that of the main program.
  312. .IP
  313. The
  314. .B set
  315. command accepts a set of parameters in the same style; only
  316. .B -pid
  317. .I pid
  318. is implemented.
  319. .IP
  320. So programs outside name spaces controlled by
  321. .I rio
  322. may create windows,
  323. .B wctl
  324. .B new
  325. messages may also be written to the named pipe identified by
  326. .BR $wctl .
  327. .TP
  328. .B wdir
  329. is a read/write text file containing
  330. .IR rio 's
  331. idea of the current working directory of the process running in the window.
  332. It is used to fill in the
  333. .B wdir
  334. field of
  335. .IR plumb (6)
  336. messages
  337. .I rio
  338. generates from the
  339. .B plumb
  340. menu item on button 2.
  341. The file is writable so the program may update it;
  342. .I rio
  343. is otherwise unaware of
  344. .IR chdir (2)
  345. calls its clients make.
  346. In particular,
  347. .IR rc (1)
  348. maintains
  349. .B /dev/wdir
  350. in default
  351. .IR rio (1)
  352. windows.
  353. .TP
  354. .B winid
  355. returns the unique and unchangeable ID for the window;
  356. it is a string of digits.
  357. .TP
  358. .B window
  359. is the virtual version of
  360. .BR /dev/screen .
  361. It contains the depth, coordinates, and
  362. uncompressed raster image corresponding to the associated
  363. window.
  364. .TP
  365. .B wsys
  366. is a directory containing a subdirectory for each window, named
  367. by the unique ID for that window. Within each subdirectory
  368. are entries corresponding to several of the special files associated
  369. with that window:
  370. .BR cons ,
  371. .BR consctl ,
  372. .BR label ,
  373. .BR mouse ,
  374. etc.
  375. .SH EXAMPLES
  376. Cause a window to be created in the upper left corner,
  377. and the word
  378. .L hi
  379. to be printed there.
  380. .IP
  381. .EX
  382. mount $riosrv /tmp 'new -r 0 0 128 64 -pid '$pid
  383. echo hi > /tmp/cons
  384. .EE
  385. .PP
  386. Start
  387. .IR sam (1)
  388. in a large horizontal window.
  389. .IP
  390. .EX
  391. echo new -dx 800 -dy 200 -cd /sys/src/cmd sam > /dev/wctl
  392. .EE
  393. .PP
  394. Print the screen image of window with id 123.
  395. .IP
  396. .EX
  397. lp /dev/wsys/123/window
  398. .EE
  399. .SH SOURCE
  400. .B /sys/src/cmd/rio
  401. .SH SEE ALSO
  402. .IR rio (1),
  403. .IR draw (3),
  404. .IR mouse (3),
  405. .IR cons (3),
  406. .IR event (2),
  407. .IR graphics (2).