control 42 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828
  1. .TH CONTROL 2
  2. .SH NAME
  3. Control,
  4. Controlset,
  5. activate,
  6. closecontrol,
  7. closecontrolset,
  8. controlcalled,
  9. controlwire,
  10. createbox,
  11. createboxbox,
  12. createbutton,
  13. createcolumn,
  14. createentry,
  15. createkeyboard,
  16. createlabel,
  17. createmenu,
  18. createradiobutton,
  19. createrow,
  20. createscribble,
  21. createslider,
  22. createstack,
  23. createtab,
  24. createtext,
  25. createtextbutton,
  26. ctlerror,
  27. ctlmalloc,
  28. ctlrealloc,
  29. ctlstrdup,
  30. ctlprint,
  31. deactivate,
  32. freectlfont,
  33. freectlimage,
  34. initcontrols,
  35. namectlfont,
  36. namectlimage,
  37. newcontrolset,
  38. resizecontrolset
  39. \- interactive graphical controls
  40. .SH SYNOPSIS
  41. .EX
  42. .ta 4n +4n +4n +4n +4n +4n +4n
  43. #include <u.h>
  44. #include <libc.h>
  45. #include <draw.h>
  46. #include <thread.h>
  47. #include <keyboard.h>
  48. #include <mouse.h>
  49. #include <control.h>
  50. .sp 0.8
  51. typedef struct Control Control;
  52. typedef struct Controlset Controlset;
  53. .sp 0.8
  54. struct Control
  55. {
  56. char *name;
  57. Rectangle rect; /* area on screen */
  58. Rectangle size; /* min/max Dx, Dy (not a rect) */
  59. Channel *event; /* chan(char*) to client */
  60. Channel *data; /* chan(char*) to client */
  61. \&...
  62. };
  63. .sp 0.8
  64. struct Controlset
  65. {
  66. \&...
  67. Channel *ctl;
  68. Channel *data;
  69. \&...
  70. int clicktotype;
  71. \&...
  72. };
  73. .sp 0.8
  74. void initcontrols(void)
  75. .sp 0.8
  76. Controlset* newcontrolset(Image *i,
  77. Channel *kc, Channel *mc, Channel *rc)
  78. .sp 0.8
  79. void closecontrolset(Controlset *cs)
  80. .sp 0.8
  81. int namectlfont(Font *font, char *name)
  82. .sp 0.8
  83. int freectlfont(char *name)
  84. .sp 0.8
  85. int namectlimage(Image *image, char *name)
  86. .sp 0.8
  87. int freectlimage(char *name)
  88. .sp 0.8
  89. Control* createbox(Controlset *cs, char *name)
  90. .sp 0.8
  91. Control* createboxbox(Controlset *cs, char *name)
  92. .sp 0.8
  93. Control* createbutton(Controlset *cs, char *name)
  94. .sp 0.8
  95. Control* createcolumn(Controlset*, char*)
  96. .sp 0.8
  97. Control* createentry(Controlset *cs, char *name)
  98. .sp 0.8
  99. Control* createkeyboard(Controlset *cs, char *name)
  100. .sp 0.8
  101. Control* createlabel(Controlset *cs, char *name)
  102. .sp 0.8
  103. Control* createmenu(Controlset *cs, char *name)
  104. .sp 0.8
  105. Control* createradiobutton(Controlset *cs, char *name)
  106. .sp 0.8
  107. Control* createrow(Controlset*, char*)
  108. .sp 0.8
  109. Control* createscribble(Controlset *cs, char *name)
  110. .sp 0.8
  111. Control* createslider(Controlset *cs, char *name)
  112. .sp 0.8
  113. Control* createstack(Controlset*, char*)
  114. .sp 0.8
  115. Control* createtab(Controlset*, char *)
  116. .sp 0.8
  117. Control* createtext(Controlset *cs, char *name)
  118. .sp 0.8
  119. Control* createtextbutton(Controlset *cs, char *name)
  120. .sp 0.8
  121. void closecontrol(Control *c)
  122. .sp 0.8
  123. int ctlprint(Control*, char*, ...);
  124. .sp 0.8
  125. void ctlerror(char *fmt, ...)
  126. .sp 0.8
  127. Control* controlcalled(char *name)
  128. .sp 0.8
  129. void controlwire(Control *c, char *cname, Channel *ch)
  130. .sp 0.8
  131. void activate(Control *c)
  132. .sp 0.8
  133. void deactivate(Control *c)
  134. .sp 0.8
  135. void resizecontrolset(Controlset *cs)
  136. .sp 0.8
  137. void* ctlmalloc(uint n)
  138. .sp 0.8
  139. void* ctlrealloc(void *p, uint n)
  140. .sp 0.8
  141. char* ctlstrdup(char *s)
  142. .sp 0.8
  143. int ctldeletequits
  144. .EE
  145. .SH DESCRIPTION
  146. .PP
  147. This library provides a set of interactive
  148. controls for graphical displays: buttons, sliders, text entry boxes, and so on.
  149. It also provides aggregator controls: boxes, columns, rows and stacks of controls.
  150. A stack is a collection of colocated controls, of which one is normally visible.
  151. A
  152. .B controlset
  153. collects a group of controls that share mouse and keyboard. Each controlset
  154. has a separate thread of control that processes keyboard and mouse events as
  155. well as commands to be passed on to the controls.
  156. Since each controlset uses a thread, programs using the control library must
  157. be linked with the thread library,
  158. .IR thread (2).
  159. .PP
  160. Controls are manipulated by reading and writing to the control channel,
  161. .BR ctl ,
  162. of their controlset.
  163. Channels are defined in
  164. .IR thread (2).
  165. Each control has two output channels:
  166. .B Event
  167. delivers messages about actions within the control (such as a button press) and
  168. .B data
  169. delivers (if requested by an appropriate write to
  170. .BR ctl )
  171. control-specific data such as the contents of a field.
  172. .PP
  173. The library provides a simple mechanism for automatic layout:
  174. the minimum and maximum sizes of each simple control can be specified.
  175. .BR Boxbox ,
  176. .BR row ,
  177. .B column
  178. and
  179. .B stack
  180. controls then use these sizes to lay out their constituent controls when called upon
  181. to do so. See the description of these grouping controls for further details.
  182. .SS "Message format
  183. All messages are represented as
  184. .SM UTF\c
  185. -8
  186. text.
  187. Numbers are formatted in decimal, and strings are transmitted in the
  188. quoted form of
  189. .IR quote (2).
  190. .PP
  191. Messages sent to a controlset are of the form,
  192. .IP
  193. .IR sender :
  194. .I destination
  195. .I verb
  196. .RI [ argument
  197. \&... ]
  198. .LP
  199. The sender (and the colon following it) may be ommitted.
  200. For example, the initial field of a text entry control called
  201. .I entry
  202. could be set by sending the message,
  203. .IP
  204. .B "entry value 'Hello, world!'
  205. .PP
  206. to its controlset's
  207. .B ctl
  208. file.
  209. This message contains the verb
  210. .B value
  211. and the single argument
  212. .B "Hello, world!"
  213. .PP
  214. To make it easy to write messages, the function
  215. .IR chanprint
  216. (see
  217. .IR thread (2))
  218. can be used to print formatted text to a controlset's channel.
  219. .PP
  220. The
  221. .B %q
  222. and
  223. .B %Q
  224. formats are convenient for properly quoting string arguments,
  225. as in
  226. .IP
  227. .EX
  228. chanprint(e->event, "value %q", "Don't touch!");
  229. .EE
  230. .PP
  231. It is wise to use
  232. .B %q
  233. always instead of
  234. .BR %s
  235. when sending messages, and avoid dealing with the quoting explicitly.
  236. In the other direction,
  237. .B tokenize
  238. (see
  239. .IR getfields (2))
  240. parses these messages and interprets the quotes correctly.
  241. .PP
  242. The destination of a message can be a named control, or a set of controls identified
  243. by name or type. The command
  244. .IP
  245. .B "'entry slider' show
  246. .PP
  247. (note the quotation) sends the `show' command to the entry named
  248. .I entry
  249. and all controls of type
  250. .IR slider .
  251. If there were a control whose name was
  252. .I slider
  253. that control would also be shown.
  254. .LP
  255. \f2
  256. Note that we are still experimenting with destination names. One proposal is that
  257. a destination of the form
  258. \fR"`name1 name2 ⋯ type1 type2 ⋯'\fP
  259. selects all controls of the named types in the control hierarchies (of columns, rows and
  260. stacks) whose names precede the types.
  261. .LP
  262. .sp
  263. Messages sent by a control on its
  264. .B event
  265. channel are of the form
  266. .IP
  267. .IB sender :
  268. .IB event
  269. .PP
  270. The
  271. .I sender
  272. is the name of the control sending the message;
  273. the
  274. .I event
  275. describes the event. Its format can often be controlled by setting the
  276. control's
  277. .IR "format string" .
  278. For example, when the user types a newline at a text entry control named
  279. .BR entry,
  280. the control sends the message
  281. .IP
  282. .B entry:\ value\ 'Hello\ again!'
  283. on its
  284. .B event
  285. channel.
  286. .SS "Initialization and Control sets
  287. After
  288. .B initdraw
  289. (see
  290. .IR graphics (2))
  291. is called,
  292. the function
  293. .I initcontrols
  294. should be called to initialize the library.
  295. It calls
  296. .I quotefmtinstall
  297. to install the
  298. .B %q
  299. and
  300. .B %Q
  301. formats; see
  302. .IR quote (2).
  303. .PP
  304. Each control is represented by a
  305. .B Control
  306. data structure and is associated with a
  307. .B Controlset
  308. that groups a set of controls sharing mouse, keyboard, and display.
  309. Most applications will need only one
  310. .BR Controlset ;
  311. only those with multiple windows or unusual configurations will need
  312. more than one.
  313. The function
  314. .I newcontrolset
  315. creates a
  316. .BR Controlset .
  317. Its arguments are the image (usually a window)
  318. on which its controls will appear, typically the
  319. .B screen
  320. variable in the draw library, and three channels:
  321. .BR kc ,
  322. a channel of
  323. .B Runes
  324. from the keyboard;
  325. .BR mc ,
  326. a channel of
  327. .B Mouse
  328. structures from the mouse;
  329. and
  330. .BR rc ,
  331. a channel of
  332. .B int
  333. that indicates when the window has been resized.
  334. Any of the channels may be nil,
  335. in which case
  336. .I newcontrolset
  337. will call
  338. .B initkeyboard
  339. and/or
  340. .B initmouse
  341. (see
  342. .IR keyboard (2)
  343. and
  344. .IR mouse (2))
  345. to initialize the keyboard and mouse
  346. and connect them to the control set.
  347. The mouse and resize channels must both be nil or both be non-nil.
  348. .PP
  349. The function
  350. .I closecontrolset
  351. frees all the controls in the control set and tears down all the associated threads.
  352. It does not close the mouse and keyboard.
  353. .PP
  354. The public elements of a
  355. .B Controlset
  356. are the flag
  357. .BR clicktotype ,
  358. and the
  359. .I ctl
  360. and
  361. .I data
  362. channels.
  363. .PP
  364. .I Clicktotype
  365. is zero by default.
  366. If it is set to non-zero, the controls
  367. in the set will acquire `focus' by the click-to-type paradigm.
  368. Otherwise, focus is always given to the control under the mouse.
  369. .PP
  370. Commands for controls are sent through the controlset's
  371. .I ctl
  372. channel.
  373. One special command is recognized by the controlset itself: Sending
  374. the string
  375. .B sync
  376. to the
  377. .I ctl
  378. channel causes tha string to be echoed to the controlset's
  379. .I data
  380. channel when all commands up to the
  381. .I sync
  382. command have been processed. The string is
  383. allocated and must be freed (see
  384. .IR malloc (2)).
  385. Synchronization is necessary between sending a command, for example, to resize
  386. all controls, and using their
  387. .I rect
  388. fields.
  389. .PP
  390. The function
  391. .I resizecontrolset
  392. must be provided by the user.
  393. When the associated window is resized, the library will call
  394. .I resizecontrolset
  395. with the affected
  396. .BR Controlset ;
  397. the function should reconnect to and redraw the window.
  398. .PP
  399. If all windows are organized in a hierachy of
  400. .IR boxboxes ,
  401. .IR columns ,
  402. .I rows
  403. and
  404. .IR stacks ,
  405. and minimum and maximum sizes have already been supplied, only
  406. the top control needs to be resized (see the
  407. .I rect
  408. command below).
  409. .SS "Fonts and images
  410. Fonts and images must be given names so they may be referenced
  411. in messages.
  412. The functions
  413. .I namectlfont
  414. and
  415. .I namectlimage
  416. associate a (unique) name with the specified font or image.
  417. The association is removed by
  418. .I freectlfont
  419. and
  420. .IR freectlimage .
  421. The font or image is not freed by these functions, however.
  422. .PP
  423. The function
  424. .I initcontrols
  425. establishes name bindings for all the colors mentioned in
  426. .BR <draw.h> ,
  427. such as
  428. .BR black ,
  429. .BR white ,
  430. .BR red ,
  431. .BR yellow ,
  432. etc., as well as masks
  433. .B transparent
  434. and
  435. .BR opaque .
  436. It also sets the name
  437. .B font
  438. to refer to the default
  439. .B font
  440. variable set up by
  441. .BR initdraw .
  442. .SS Creation
  443. Each type of control has an associated creation function:
  444. .IR createbutton ,
  445. .IR createentry ,
  446. etc.,
  447. whose arguments are the
  448. .B Controlset
  449. to attach it to and a globally unique name for it.
  450. A control may be destroyed by calling
  451. .IR closecontrol .
  452. .PP
  453. The function
  454. .I controlcalled
  455. returns a pointer to the
  456. .B Control
  457. with the given
  458. .IR name ,
  459. or nil if no such control exists.
  460. .SS Configuration
  461. After a control is created, it must be configured using the control-specific
  462. commands documented below.
  463. Commands are sent to the
  464. .B ctl
  465. channel of the controlset.
  466. Multiple commands may be sent in a single message; newline characters
  467. separate commands.
  468. For an example, see the implementation of
  469. .I resizecontrolset
  470. in the EXAMPLES section.
  471. Note that newline is a separator, not a terminator; the final command
  472. does not need a newline.
  473. .PP
  474. Messages sent to the
  475. .I ctl
  476. channel are delivered to all controls that match the
  477. .I destination
  478. field. This field is a set of names separated by spaces, tabs or newlines.
  479. A control matches the destination if its name or its type is among the set.
  480. .PP
  481. The recipient of a message ignores the initial
  482. .IB sender :
  483. field of the message, if present,
  484. making it possible to send messages generated on an
  485. .B event
  486. channel directly to another control's
  487. .B ctl
  488. channel.
  489. .SS Activation
  490. When they are created, controls are disabled: they do not respond to
  491. user input.
  492. Not all controls need to be responsive;
  493. for example, labels are static and a text display
  494. might show a log of messages but not be useful to edit.
  495. But buttons, entry boxes, and other text displays should be active.
  496. .PP
  497. To enable a control, call the
  498. .I activate
  499. function, which
  500. specifies that the
  501. .B Control
  502. .I c
  503. should respond to mouse and keyboard events;
  504. .I deactivate
  505. turns it off again.
  506. .PP
  507. Controls can be either
  508. .I revealed
  509. (default) or
  510. .IR hidden .
  511. When a control is hidden, it will not receive mouse or keyboard events
  512. and state changes or
  513. .I show
  514. commands will be ignored until the control is once again
  515. .IR revealed .
  516. Control hiding is particularly useful when different controls are overlayed,
  517. revealing only the `top' one.
  518. .PP
  519. The function
  520. .I controlwire
  521. permits rearrangement of the channels associated with a
  522. .BR Control .
  523. The channel
  524. .I cname
  525. (one of
  526. \f5"data"\fP
  527. or
  528. \f5"event"\fP)
  529. of
  530. .B Control
  531. .I c
  532. is reassigned to the channel
  533. .IR ch .
  534. There are several uses for this operation:
  535. one may reassign all the
  536. .B event
  537. channels to a single channel, in effect multiplexing all the events onto
  538. a single channel;
  539. or connect the
  540. .B event
  541. channel of a slider to the
  542. .B ctl
  543. channel for delivery to a text display (after setting the format for the slider's messages
  544. to name the destination control and the appropriate syntax for the rest of the command)
  545. to let the slider act as a scroll bar for the text without rerouting the messages explicitly.
  546. .SS Controls
  547. The following sections document the individual controls in alphabetical order.
  548. The layout of each section is a brief description of the control's behavior,
  549. followed by the messages it sends on
  550. .BR event ,
  551. followed by the messages it accepts via the
  552. .B ctl
  553. channel.
  554. The
  555. .B event
  556. messages are triggered
  557. .I only
  558. by mouse or keyboard action; messages to the
  559. .B ctl
  560. file do not cause events to be generated.
  561. .PP
  562. All controls accept the following messages:
  563. .TP
  564. .BI rect " minx miny maxx maxy
  565. Set the bounding rectangle for the control on the display.
  566. The syntax generated by the
  567. .B %R
  568. print format of the draw library is also acceptable for the coordinates.
  569. .TP
  570. .BR size " [ \f2minΔx minΔy maxΔx maxΔy\fP ]
  571. Set the minimum and maximum size for automatic layout in
  572. .IR columns ,
  573. .I rows
  574. and
  575. .IR stacks .
  576. Without its four arguments, this command is ignored by primitive controls
  577. and used by grouping controls to calculate their minimum and maximum sizes
  578. by examining those of their constituent members.
  579. If all primitive controls have been assigned a size, a single size request addressed
  580. to the top of a layout hierarchy will assign sizes to all grouping controls.
  581. .TP
  582. .B hide
  583. Disable drawing of the control and ignore mouse and keyboard events
  584. until the control is once again revealed.
  585. Grouping controls (\f2column\fP, \f2row\fP, and \f2stack\fP) pass the
  586. request down to their constituent controls.
  587. .TP
  588. .B reveal
  589. This is the opposite of
  590. .BR hide :
  591. the control is displayed and mouse and keyboard operations resume.
  592. Grouping controls (\f2column\fP, \f2row\fP, and \f2stack\fP) pass the
  593. request down to their constituent controls.
  594. The
  595. .B reveal
  596. command for
  597. .I stacks
  598. takes an optional argument naming the control to be revealed; all
  599. other controls will be hidden.
  600. .TP
  601. .B show
  602. Display the control on its screen if not hidden.
  603. Some actions will also cause the controls to show themselves automatically
  604. (but never when the control is hidden).
  605. Grouping controls (\f2column\fP, \f2row\fP, and \f2stack\fP) pass the
  606. request down to their constituent controls.
  607. .PP
  608. Many messages are common between multiple controls.
  609. Such messages are described in detail here to avoid repetition.
  610. In the individual descriptions, only the syntax is presented.
  611. .TP
  612. .BI align " n
  613. Specify the alignment of (some part of) the control's display within its rectangle.
  614. For textual controls, the alignment specifies where the text should appear.
  615. For multiline text, the alignment refers to each line within its box, and only the
  616. horizontal part is honored.
  617. For other controls, the alignment affects the appearance of the display in
  618. a reasonable way.
  619. The valid alignments are words with obvious interpretations:
  620. .BR upperleft ,
  621. .BR uppercenter ,
  622. .BR upperright ,
  623. .BR centerleft ,
  624. .BR center ,
  625. .BR centerright ,
  626. .BR lowerleft,
  627. .BR lowercenter ,
  628. and
  629. .BR lowerright .
  630. .TP
  631. .BI border " n
  632. Inset the control (or separate constituent controls in
  633. .IR boxbox ,
  634. .I column
  635. and
  636. .I row
  637. controls after the next
  638. .I rect
  639. command) within its rectangle by
  640. .I n
  641. pixels, default zero.
  642. .TP
  643. .BI bordercolor " name
  644. Paint the border of the control with the named color, default black.
  645. .TP
  646. .BI focus " n
  647. The control now has (if
  648. .I n
  649. is non-zero) or does not have ( if
  650. .I n
  651. is zero) focus.
  652. Most controls ignore the message; there are plans to make them react.
  653. .TP
  654. .BI format " fmt
  655. Set the format of `value' messages sent on the
  656. .B event
  657. channel.
  658. By default, the format is
  659. .B \&"%q: value %q"
  660. for string-valued controls,
  661. .B \&"%q: value %d"
  662. for integer-valued controls such as buttons,
  663. and
  664. .B \&"%q: value 0x%x"
  665. for the keyboard and scribble controls.
  666. The
  667. .B %q
  668. prints the name of the control; the rest the value.
  669. Any supplied format string must be type-equivalent to the default for that control.
  670. .TP
  671. .BI image " name
  672. .TP
  673. .BI light " name
  674. .TP
  675. .BI mask " name
  676. Many controls set a background image or color for display.
  677. The
  678. .B image
  679. message sets the image.
  680. The
  681. .B mask
  682. and
  683. .B light
  684. images together specify how the control shows it is enabled:
  685. the
  686. .B light
  687. is printed through the
  688. .B mask
  689. when the state is `on' or `pressed'.
  690. Otherwise, the image appears unmodified.
  691. The default image is white; mask opaque; light yellow.
  692. .TP
  693. .BI font " name
  694. .TP
  695. .BI textcolor " name
  696. These commands set the font and color for displaying text.
  697. The defaults are the default
  698. .B font
  699. set up by the draw library, and black.
  700. .TP
  701. .BI value " v
  702. Set the value of the control. Textual images accept an arbitrary string;
  703. others an integral value.
  704. .SS Box
  705. A box is a trivial control that does nothing more than pass keyboard, mouse,
  706. and focus messages back on its
  707. .B event
  708. channel.
  709. Keyboard characters are sent in the format
  710. .IP
  711. .EX
  712. boxname: key 0x\f2nn
  713. .EE
  714. .PP
  715. where
  716. .I nn
  717. is the hexadecimal value of the character.
  718. Mouse messages are sent in the format
  719. .IP
  720. .EX
  721. boxname: mouse [\f2x\fP \f2y\fP] \f2but\fP \f2msec\fP
  722. .EE
  723. .PP
  724. where
  725. .IR x ,
  726. .IR y ,
  727. .IR but ,
  728. and
  729. .I msec
  730. are the various fields of the
  731. .B Mouse
  732. structure.
  733. The focus message is just
  734. .IP
  735. .EX
  736. boxname: focus \f2n\f1
  737. .EE
  738. .PP
  739. where
  740. .I n
  741. is 0 if the box has lost focus, 1 if it has acquired it.
  742. .PP
  743. The box displays within its rectangle
  744. an image, under mask, with specified alignment.
  745. The control messages it accepts are:
  746. .TP
  747. .BI align " a
  748. Controls the placement of the image in the rectangle (unimplemented).
  749. .TP
  750. .BI border " b
  751. .TP
  752. .BI bordercolor " name
  753. .TP
  754. .BI focus " n
  755. .TP
  756. .BI hide
  757. .TP
  758. .BI image " name
  759. .TP
  760. .BI rect " minx miny maxx maxy
  761. .TP
  762. .BI reveal
  763. .TP
  764. .BI show
  765. .TP
  766. .BI size " minΔx minΔy maxΔx maxΔy
  767. .PP
  768. .SS Boxbox
  769. A
  770. .B boxbox
  771. allows a set of controls (``boxes'') to be displayed in rows and columns within the
  772. rectangle of the
  773. .IR boxbox .
  774. The maximum of the minimum heights of the constituent controls determines the
  775. number of rows to be displayed. The number of columns is the minimum that
  776. allows all controls to be displayed. This aggregator works well for collections
  777. of buttons, labels, or textbuttons that all have a fixed height.
  778. .TP
  779. .BI add " name ...
  780. adds the named control to the box of controls. The display order
  781. is determined by the order of adding. The first named control is top left,
  782. the second goes below it, etc.
  783. It is possible to add one control to multiple grouping controls but
  784. the layout of the result will be quite unpredictable.
  785. .TP
  786. .BI border " width
  787. .TP
  788. .BI bordercolor " color
  789. .TP
  790. .B hide
  791. This command is passed on to the member controls.
  792. .TP
  793. .B image " color
  794. Background color displayed between member controls.
  795. .TP
  796. .B reveal
  797. This command is passed on to the member controls.
  798. .TP
  799. .BI separation " width
  800. Set the separation between member controls to
  801. .I n
  802. pixels.
  803. .TP
  804. .BI rect " minx miny maxx maxy
  805. The member controls are layed out within the given rectangle according to
  806. the minimum and maximum sizes given. If the rectangle is not large enough
  807. for the minimum a fatal error is currently generated.
  808. If the controls at their maximum size are not big enough to fit, they are top-left justified
  809. at their maximum size in the space given.
  810. Otherwise, controls will get their minimum size and be enlarged proportional
  811. to the extra size given by the maximum until they fit given rectangle.
  812. The members are separated by borders of the width established by
  813. .IR borderwidth .
  814. .TP
  815. .BI remove " name
  816. Remove the named
  817. control from the box.
  818. .TP
  819. .B show
  820. This command is passed on to the member controls.
  821. Show also (re)displays background and borders.
  822. .TP
  823. .BR size " \f2minΔx minΔy maxΔx maxΔy\fP
  824. .PP
  825. .SS Button
  826. A button is a simple control that toggles its state when mouse button 1 is pressed on its rectangle.
  827. Each state change triggers an event message:
  828. .IP
  829. .EX
  830. buttonname: value \f2n\fP
  831. .EE
  832. where
  833. .I n
  834. encodes the mouse buttons used to make the selection.
  835. .PP
  836. The button displays an image (which may of course be a simple color)
  837. and illuminates in the standard way when it is `on'.
  838. The control messages it accepts are:
  839. .TP
  840. .BI align " a
  841. Controls the placement of the image in the rectangle (unimplemented).
  842. .TP
  843. .BI border " b
  844. .TP
  845. .BI bordercolor " name
  846. .TP
  847. .BI focus " n
  848. .TP
  849. .BI format " fmt
  850. .TP
  851. .BI hide
  852. .TP
  853. .BI image " name
  854. .TP
  855. .BI light " name
  856. .TP
  857. .BI mask " name
  858. .TP
  859. .BI rect " minx miny maxx maxy
  860. .TP
  861. .BI reveal
  862. .TP
  863. .B show
  864. .TP
  865. .BI size " minΔx minΔy maxΔx maxΔy
  866. .TP
  867. .BI value " n
  868. Set the button to `on' (if
  869. .I n
  870. is non-zero) or `off' (if
  871. .I n
  872. is zero).
  873. .PP
  874. .SS Column
  875. A column is a grouping control which lays out its members vertically,
  876. from top to bottom. Currently, columns ignore mouse and keyboard
  877. events, but there are plans to allow dragging the borders (when they
  878. have non-zero width) between constituent members.
  879. .TP
  880. .BI add " name ...
  881. adds the named control to the column of controls. The vertical order
  882. is determined by the order of adding. The first named control goes at
  883. the top. It is possible to add one control to multiple grouping controls but
  884. the layout of the result will be quite unpredictable.
  885. .TP
  886. .BI border " width
  887. Set the border between members to the width given.
  888. .TP
  889. .BI bordercolor " color
  890. .TP
  891. .B hide
  892. .TP
  893. .B image " color
  894. Background color displayed between member controls.
  895. .TP
  896. .B reveal
  897. .TP
  898. .BI separation " width
  899. Set the separation between member controls to
  900. .I n
  901. pixels.
  902. .TP
  903. .B show
  904. These three commands are passed on to the member controls.
  905. Show also (re)displays the borders between members.
  906. .TP
  907. .BI rect " minx miny maxx maxy
  908. The member controls are layed out within the given rectangle according to
  909. the minimum and maximum sizes given. If the rectangle is not large enough
  910. for the minimum a fatal error is currently generated. However, see the example
  911. at the end of this man page.
  912. If the controls at their maximum size are not big enough to fit, they are centered
  913. at their maximum size in the space given.
  914. Otherwise, controls will get their minimum size and be enlarged proportional
  915. to the extra size given by the maximum until they fit given rectangle.
  916. The members are separated by borders of the width established by
  917. .IR borderwidth .
  918. .TP
  919. .BI remove " name
  920. Remove the named control from the column.
  921. .TP
  922. .BR size " [ \f2minΔx minΔy maxΔx maxΔy\fP ]
  923. Without arguments, this command computes the minimum and
  924. maximum size of a column by adding the minimum and maximum
  925. heights to set
  926. .I minΔy
  927. and
  928. .IR maxΔy ,
  929. and it finds the largest minimum and maximum widths to set
  930. .I minΔy
  931. and
  932. .IR maxΔy .
  933. When called with arguments, it simply sets the minimum and maximum
  934. sizes to those given.
  935. .PP
  936. .SS Entry
  937. The entry control manages a single line of editable text.
  938. When the user hits a carriage return anywhere
  939. in the text, the control generates the event message,
  940. .IP
  941. .EX
  942. entryname: value \f2s\fP
  943. .EE
  944. .PP
  945. with
  946. .I s
  947. the complete text of the entry box.
  948. .PP
  949. The cursor can be moved by clicking button 1; at the moment,
  950. there is no way to select characters, only a typing position.
  951. Some control characters have special actions:
  952. control-H (backspace) deletes the character before the cursor;
  953. control-U clears the line; and
  954. control-V pastes the snarf buffer at the typing position.
  955. Most important, carriage return sends the text to the event channel.
  956. .PP
  957. To enter passwords and other secret text without displaying the
  958. contents, set the font to one in which all characters are the same.
  959. The easiest way to do this is to make a font containing only one character,
  960. at position 0 (NUL), since that position is used to render all
  961. characters not otherwise defined in the font (see
  962. .IR draw (2)).
  963. The file
  964. .B /lib/font/bit/lucm/passwd.9.font
  965. defines such a font.
  966. .PP
  967. The control messages the entry control accepts are:
  968. .TP
  969. .BI align " a
  970. Controls the placement of the text in the rectangle.
  971. .TP
  972. .BI border " b
  973. .TP
  974. .BI bordercolor " name
  975. .TP
  976. .BI data
  977. After receiving this message, the entry will send its value to its
  978. .B data
  979. channel as an unadorned, unquoted string.
  980. .TP
  981. .BI focus " n
  982. When it receives focus, the entry box displays a typing cursor.
  983. When it does not have focus, the cursor is not displayed.
  984. .TP
  985. .BI font " name
  986. .TP
  987. .BI format " fmt
  988. .TP
  989. .BI hide
  990. .TP
  991. .BI image " name
  992. .TP
  993. .BI rect " minx miny maxx maxy
  994. .TP
  995. .B reveal
  996. .TP
  997. .B show
  998. .TP
  999. .BI size " minΔx minΔy maxΔx maxΔy
  1000. .TP
  1001. .BI textcolor " name
  1002. .TP
  1003. .BI value " s
  1004. Set the string displayed in the entry box.
  1005. .SS Keyboard
  1006. The keyboard control implements a simulated keyboard useful on palmtop devices.
  1007. Keystrokes, generated by mouse button 1 on the simulated keys,
  1008. are sent as event messages:
  1009. .IP
  1010. .EX
  1011. keyboardname: value 0x\f2nn\f1
  1012. .EE
  1013. .PP
  1014. where
  1015. .I nn
  1016. is the hexadecimal Unicode value of the character.
  1017. Shift, control, and caps lock are handled by the keyboard control itself;
  1018. shift and control affect only the next regular keystroke.
  1019. The Alt key is unimplemented; it will become equivalent to the standard Plan 9
  1020. key for synthesizing non-ASCII characters.
  1021. .PP
  1022. There are two special keys,
  1023. .B Scrib
  1024. and
  1025. .BR Menu ,
  1026. which return values
  1027. .B 0x10000
  1028. and
  1029. .BR 0x10001 .
  1030. .PP
  1031. The image, mask, light rules are used to indicate that a key is pressed,
  1032. but to aid clumsy fingers the keystroke is not generated until the key is released,
  1033. so it is possible to slide the pointer to a different key to correct for bad aim.
  1034. .PP
  1035. The control messages the keyboard accepts are:
  1036. .TP
  1037. .BI border " b
  1038. .TP
  1039. .BI bordercolor " name
  1040. .TP
  1041. .BI focus " n
  1042. .TP
  1043. .BI font " name1 name2
  1044. Sets the font for the keys.
  1045. If only one font is named, it is used for all keys.
  1046. If two are named, the second is used for key caps with special names such
  1047. as Shift and Enter.
  1048. (Good choices on the Bitsy are
  1049. .B /lib/font/bit/lucidasans/boldlatin1.6.font
  1050. for the first and
  1051. .B /lib/font/bit/lucidasans/unicode.6.font
  1052. for the second argument.)
  1053. If neither is specified, both will be set to the default global font.
  1054. .TP
  1055. .BI format " fmt
  1056. .TP
  1057. .BI hide
  1058. .TP
  1059. .BI image " name
  1060. .TP
  1061. .BI light " name
  1062. .TP
  1063. .BI mask " name
  1064. .TP
  1065. .BI rect " minx miny maxx maxy
  1066. .TP
  1067. .BI reveal
  1068. .TP
  1069. .B show
  1070. .TP
  1071. .BI size " minx miny maxx maxy
  1072. .SS Label
  1073. A label is like a textbutton
  1074. .RI ( q.v. )
  1075. that does not react, but whose value is the text it displays.
  1076. The control messages it accepts are:
  1077. .TP
  1078. .BI align " a
  1079. Controls the placement of the image in the rectangle.
  1080. .TP
  1081. .BI border " b
  1082. .TP
  1083. .BI bordercolor " name
  1084. .TP
  1085. .BI focus " n
  1086. .TP
  1087. .BI font " name
  1088. .TP
  1089. .BI hide
  1090. .TP
  1091. .BI image " name
  1092. .TP
  1093. .BI rect " minx miny maxx maxy
  1094. .TP
  1095. .BI reveal
  1096. .TP
  1097. .B show
  1098. .TP
  1099. .BI size " minx miny maxx maxy
  1100. .TP
  1101. .BI textcolor " name
  1102. .TP
  1103. .BI value " s
  1104. The value is a string that can be modified only by sending this message to the
  1105. .B ctl
  1106. file.
  1107. .SS Menu
  1108. A menu is a pop-up window containing a set of textual selections.
  1109. When a selection is made, it removes itself from the screen and reports the selection
  1110. by value:
  1111. .IP
  1112. .EX
  1113. menuname: value \f2n\fP
  1114. .EE
  1115. .PP
  1116. If no selection is made, no message is reported.
  1117. Because it creates a window, programs using a menu must have their
  1118. .B screen
  1119. variable (see
  1120. .IR graphics (2)
  1121. and
  1122. .IR window (2))
  1123. set up to be refreshed properly.
  1124. The easiest way to do this is to call
  1125. .B getwindow
  1126. with refresh argument
  1127. .B Refbackup
  1128. (see
  1129. .IR graphics (2));
  1130. most programs use
  1131. .BR Refnone .
  1132. .PP
  1133. The control messages accepted by a menu are:
  1134. .TP
  1135. .BI add " text
  1136. Add a line of
  1137. .I text
  1138. to the end of the menu.
  1139. .TP
  1140. .BI align " a
  1141. Controls the left-right placement of the text in its rectangle.
  1142. .TP
  1143. .BI border " b
  1144. .TP
  1145. .BI bordercolor " name
  1146. .TP
  1147. .BI focus " n
  1148. .TP
  1149. .BI font " name
  1150. .TP
  1151. .BI format " fmt
  1152. .TP
  1153. .BI hide
  1154. .TP
  1155. .BI image " name
  1156. .TP
  1157. .BI rect " minx miny maxx maxy
  1158. .TP
  1159. .BI reveal
  1160. .TP
  1161. .BI size " minx miny maxx maxy
  1162. Only the origin of the rectangle is significant; menus calculate the appropriate size.
  1163. .TP
  1164. .BI selectcolor " name
  1165. Set the color in which to highlight selected lines; default yellow.
  1166. .TP
  1167. .BI selecttextcolor " name
  1168. Set the color in which to draw the text in selected lines; default black.
  1169. .TP
  1170. .B show
  1171. Display the menu. Not usually needed unless the menu is changed while visible; use
  1172. .I window
  1173. instead.
  1174. .TP
  1175. .B window
  1176. .TP
  1177. .BI window " n
  1178. With no arguments, toggle the menu's visibility; otherwise make it visible (1) or invisible (0).
  1179. When the selection is made, the menu will remove its window automatically.
  1180. .SS Radiobutton
  1181. The radiobutton assembles a group of buttons or textbuttons into a
  1182. single control with a numeric value.
  1183. Its value is \-1 if none of the constituent buttons is pressed; otherwise
  1184. it is the index, starting at zero, of the button that is pressed.
  1185. Only one button may be pressed; the radiobutton manipulates its
  1186. buttons to guarantee this.
  1187. State changes trigger an event message:
  1188. .IP
  1189. .EX
  1190. radiobuttonname: value \f2n\fP
  1191. .EE
  1192. .PP
  1193. Buttons are added to the radio button using the
  1194. .B add
  1195. message; there is no way to remove them, although they may be turned off
  1196. independently using
  1197. .IR deactivate .
  1198. The index reported in the value is defined by the order
  1199. in which the buttons are added.
  1200. The constituent buttons should be configured and layed out in the usual way;
  1201. the rectangle of the radiobutton is used only to `catch' mouse events and
  1202. should almost always correspond to the bounding box of the constituent
  1203. buttons.
  1204. In other words, the geometry is not maintained automatically.
  1205. .PP
  1206. The control messages the radiobutton accepts are:
  1207. .TP
  1208. .BI add " name
  1209. Add the control with the specified
  1210. .I name
  1211. to the radiobutton.
  1212. .TP
  1213. .BI focus " n
  1214. .TP
  1215. .BI format " fmt
  1216. .TP
  1217. .BI hide
  1218. .TP
  1219. .BI rect " minx miny maxx maxy
  1220. .TP
  1221. .BI reveal
  1222. .TP
  1223. .BI size " minx miny maxx maxy
  1224. .TP
  1225. .B show
  1226. .TP
  1227. .BI value " n
  1228. .SS Row
  1229. A row groups a number of member controls left to right in a rectangle.
  1230. Rows behave exactly like columns with the roles of
  1231. .I x
  1232. and
  1233. .I y
  1234. interchanged.
  1235. .TP
  1236. .BI add " name ...
  1237. .TP
  1238. .BI border " width
  1239. .TP
  1240. .BI bordercolor " color
  1241. .TP
  1242. .BI hide
  1243. .TP
  1244. .B image " color
  1245. .TP
  1246. .BI rect " minx miny maxx maxy
  1247. .TP
  1248. .BI remove " name
  1249. .TP
  1250. .BI reveal
  1251. .TP
  1252. .BI separation " width
  1253. .TP
  1254. .BI show
  1255. .TP
  1256. .BR size " [ \f2minΔx minΔy maxΔx maxΔy\fP ]
  1257. .SS Scribble
  1258. The scribble control provides a region in which strokes drawn with mouse button
  1259. 1 are interpreted as characters in the manner of
  1260. .IR scribble (2).
  1261. In most respects, including the format of its event messages, it is equivalent
  1262. to a keyboard control.
  1263. .PP
  1264. The control messages it accepts are:
  1265. .TP
  1266. .BI align " a
  1267. Controls the placement of the image in the rectangle (unimplemented).
  1268. .TP
  1269. .BI border " b
  1270. .TP
  1271. .BI bordercolor " name
  1272. .TP
  1273. .BI focus " n
  1274. .TP
  1275. .BI font " name
  1276. Used to display the indicia.
  1277. .TP
  1278. .BI hide
  1279. TP
  1280. .BI image " name
  1281. .TP
  1282. .BI linecolor " name
  1283. The color in which to draw the strokes; default black.
  1284. .TP
  1285. .BI rect " minx miny maxx maxy
  1286. .TP
  1287. .BI reveal
  1288. .TP
  1289. .BI size " minx miny maxx maxy
  1290. .TP
  1291. .B show
  1292. .SS Stack
  1293. A stack groups a number of member controls in the same shared rectangle.
  1294. Only one of these controls will be visible (revealed), the others are hidden.
  1295. .TP
  1296. .BI hide
  1297. .TP
  1298. .BI rect " minx miny maxx maxy
  1299. .TP
  1300. .BI remove " name
  1301. .TP
  1302. .BR reveal " [ \f2n\fP ]
  1303. Without argument,
  1304. .B reveal
  1305. is the opposite of
  1306. .BR hide :
  1307. it makes its selected control visible after it was hidden.
  1308. With an argument, it makes the
  1309. .IR n 'th
  1310. added control visible, hiding all others.
  1311. .TP
  1312. .BI show
  1313. .TP
  1314. .BR size " [ \f2minΔx minΔy maxΔx maxΔy\fP ]
  1315. Without argument,
  1316. .I size
  1317. computes the maximum of the minimum and maximum sizes of
  1318. its constituent controls. With arguments, it sets the size to the
  1319. given values.
  1320. .SS Slider
  1321. A slider controls an integer value by dragging the mouse with a button.
  1322. Configured appropriately, it can serve as a scroll bar with the standard
  1323. Plan 9 behavior.
  1324. When the value changes, an event message is sent:
  1325. .IP
  1326. .EX
  1327. slidername: value \f2n\f1
  1328. .EE
  1329. .PP
  1330. The slider is a good candidate for connecting to another control
  1331. by setting its format and rewiring its
  1332. .B event
  1333. channel to the other's
  1334. .B ctl
  1335. channel.
  1336. .PP
  1337. The geometry of the slider is defined by three numbers:
  1338. .B max
  1339. is a number representing the range of the slider;
  1340. .B vis
  1341. is a number representing how much of what is being controlled is visible;
  1342. and
  1343. .B value
  1344. is a number representing the value of the slider within its range.
  1345. For example, if the slider is managing a textual display of 1000 lines, with
  1346. 18 visible, and the first visible line (numbered starting form 0) is 304,
  1347. .B max
  1348. will be 1000,
  1349. .B vis
  1350. will be 18, and
  1351. .B value
  1352. will be 304.
  1353. The
  1354. .I indicator
  1355. is the visual representation of the
  1356. .I vis
  1357. portion of the controlled object.
  1358. .PP
  1359. The control messages the slider accepts are:
  1360. .TP
  1361. .BI absolute " n
  1362. If
  1363. .I n
  1364. is zero,
  1365. the slider behaves like a Plan 9 scroll bar:
  1366. button 2 sets absolute position, button 1 decreases the value,
  1367. and button 3 increases it.
  1368. If
  1369. .I n
  1370. is non-zero, all buttons behave like button 2, setting the absolute value.
  1371. .TP
  1372. .BI border " b
  1373. .TP
  1374. .BI bordercolor " name
  1375. .TP
  1376. .BI clamp " end n
  1377. The
  1378. .I end
  1379. is either the word
  1380. .B high
  1381. or
  1382. .BR low ;
  1383. .I n
  1384. sets whether that end is clamped or not.
  1385. If it is clamped, that end of the indicator is always at its supremum.
  1386. A standard scroll bar has neither end clamped; a volume slider would
  1387. have its low end clamped.
  1388. If the low end is clamped, the value of the slider is represented by the
  1389. high end of the indicator; otherwise it is represented by the low end.
  1390. .TP
  1391. .BI focus " n
  1392. .TP
  1393. .BI format " fmt
  1394. .TP
  1395. .BI hide
  1396. .TP
  1397. .BI image " name
  1398. .TP
  1399. .BI indicatorcolor " name
  1400. Set the color in which to draw the indicator; default black.
  1401. .TP
  1402. .BI max " n
  1403. Set the maximum value of the range covered by the slider.
  1404. .TP
  1405. .BI orient " dir
  1406. The string
  1407. .I dir
  1408. begins either
  1409. .B hor
  1410. or
  1411. .B ver
  1412. to specify the orientation of the slider.
  1413. The default is vertical.
  1414. The value always increases to the right for horizontal sliders and
  1415. downwards for vertical sliders.
  1416. .TP
  1417. .BI rect " minx miny maxx maxy
  1418. .TP
  1419. .BI reveal
  1420. .TP
  1421. .BI size " minx miny maxx maxy
  1422. .TP
  1423. .B show
  1424. .TP
  1425. .BI value " n
  1426. .TP
  1427. .BI vis " n
  1428. Set the visible area shown by the indicator.
  1429. .SS Tab
  1430. A tab control combines radiobottuns with a stack of windows giving the
  1431. appearance of tabbed controls. Currently, the tabs are positioned at the
  1432. top of the stack. The radiobutton consists of textbuttons, the stack
  1433. can be composed of any type of control.
  1434. .PP
  1435. Control messages are
  1436. .TP
  1437. .BI add " button control button control ...
  1438. Adds a button to the radiobutton, and an associated control to the stack.
  1439. Buttons and controls are numbered in the order of addition. There is
  1440. no remove operation.
  1441. .TP
  1442. .BI border " b
  1443. .TP
  1444. .BI bordercolor " color
  1445. .TP
  1446. .BI focus " n
  1447. .TP
  1448. .BI format " fmt
  1449. When a format string is defined, the tab control reports which tab
  1450. is selected using the format string (which must print a
  1451. .B char*
  1452. and an
  1453. .BR int ).
  1454. .TP
  1455. .BI image " color
  1456. Color between member controls.
  1457. .TP
  1458. .BI separation " n
  1459. Spacing between buttons in the radiobutton and between the row of
  1460. buttons and the stack below it.
  1461. .TP
  1462. .BI rect " n n n n
  1463. .TP
  1464. .B hide
  1465. .TP
  1466. .B reveal
  1467. .TP
  1468. .BI size " n n n n
  1469. .TP
  1470. .B show
  1471. .TP
  1472. .BI value " n
  1473. Value must be an integer indicating which tab to bring to the top.
  1474. .SS Text
  1475. A text control presents a set of lines of text.
  1476. The text cannot be edited with the keyboard, but can be
  1477. changed by control messages.
  1478. (A more interactive text control will be created eventually.)
  1479. The mouse can be used to select lines of text.
  1480. The only event message reports a state change in the selection of a line:
  1481. .IP
  1482. .EX
  1483. textname: select \f2n\f1 \f2s\f1
  1484. .EE
  1485. .PP
  1486. states that line
  1487. .I n
  1488. has changed its selection state to
  1489. .IR s ,
  1490. either zero (unselected) or non-zero (selected).
  1491. The non-zero value encodes the mouse buttons that were down
  1492. when the selection occurred.
  1493. .PP
  1494. .PP
  1495. The control messages the text control accepts are:
  1496. .TP
  1497. .BI accumulate " s
  1498. .TP
  1499. .BI accumulate " n s
  1500. .TP
  1501. .BI add " s
  1502. .TP
  1503. .BI add " n s
  1504. With one argument, append the string
  1505. .I s
  1506. as a new last line of the control; if
  1507. .I n
  1508. is specified, add the line
  1509. .I before
  1510. the current line
  1511. .IR n ,
  1512. making the new line number
  1513. .IR n.
  1514. The lines are zero indexed and
  1515. .I n
  1516. can be no greater than the current number of lines.
  1517. .I Add
  1518. refreshes the display, but
  1519. .I accumulate
  1520. does not, to avoid n-squared behavior when assembling a piece of text.
  1521. .TP
  1522. .BI align " a
  1523. Controls the placement of each line of text left-to-right in its rectangle.
  1524. Vertically, lines are tightly packed with separation set by the font's interline
  1525. spacing.
  1526. .TP
  1527. .BI border " b
  1528. .TP
  1529. .BI bordercolor " name
  1530. .TP
  1531. .BI clear
  1532. Delete all text.
  1533. .TP
  1534. .BI delete " n
  1535. Delete line
  1536. .IR n .
  1537. .TP
  1538. .BI focus " n
  1539. .TP
  1540. .BI font " name
  1541. .TP
  1542. .BI image " name
  1543. .TP
  1544. .BI rect " minx miny maxx maxy
  1545. .TP
  1546. .BI replace " n s
  1547. Replace line
  1548. .I n
  1549. by the string
  1550. .IR s .
  1551. .TP
  1552. .BI reveal
  1553. .TP
  1554. .B scroll " n
  1555. If
  1556. .I n
  1557. is non-zero, the text will automatically scroll so the last line is always visible
  1558. when new text is added.
  1559. .TP
  1560. .BI select " n m
  1561. Set the selection state of line
  1562. .I n
  1563. to
  1564. .IR m .
  1565. .TP
  1566. .BI selectcolor " name
  1567. Set the color in which to highlight selected lines; default yellow.
  1568. .TP
  1569. .BI selectmode " s
  1570. The string
  1571. .I s
  1572. is either
  1573. .B single
  1574. or
  1575. .BR multi .
  1576. If
  1577. .BR single ,
  1578. the default,
  1579. only one line may be selected at a time; when a line is selected,
  1580. other lines are unselected.
  1581. If
  1582. .BR multi ,
  1583. the selection state of individual lines can be toggled independently.
  1584. .TP
  1585. .BI size " minx miny maxx maxy
  1586. .TP
  1587. .B show
  1588. .TP
  1589. .BI textcolor " name
  1590. .TP
  1591. .BI topline " n
  1592. Scroll the text so the top visible line is number
  1593. .IR n .
  1594. .TP
  1595. .BI value " s
  1596. Delete all the text in the control and then add the single line
  1597. .IR s .
  1598. .SS Textbutton
  1599. A textbutton is a textual variant of a plain button.
  1600. Each state change triggers an event message:
  1601. .IP
  1602. .EX
  1603. textbuttonname: value \f2n\fP
  1604. .EE
  1605. where
  1606. .I n
  1607. encodes the mouse buttons used to make the selection.
  1608. .PP
  1609. Like a regular button, the value of a textbutton is an integer; the
  1610. .I text
  1611. is the string that appears in the button.
  1612. It uses the image, light, mask method of indicating its state;
  1613. moreover, the color of the text can be set to change when the button is pressed.
  1614. The control messages it accepts are:
  1615. .TP
  1616. .BI align " a
  1617. Controls the placement of the text in the rectangle.
  1618. .TP
  1619. .BI border " b
  1620. .TP
  1621. .BI bordercolor " name
  1622. .TP
  1623. .BI focus " n
  1624. .TP
  1625. .BI font " name
  1626. .TP
  1627. .BI format " fmt
  1628. .TP
  1629. .B hide
  1630. .TP
  1631. .BI image " name
  1632. .TP
  1633. .BI light " name
  1634. .TP
  1635. .BI mask " name
  1636. .TP
  1637. .BI pressedtextcolor " name
  1638. Set the color in which to display text when the textbutton is pressed.
  1639. .TP
  1640. .BI rect " minx miny maxx maxy
  1641. .TP
  1642. .B reveal
  1643. .TP
  1644. .BI size " minx miny maxx maxy
  1645. .TP
  1646. .B show
  1647. .TP
  1648. .BI text " s
  1649. Set the text displayed in the button.
  1650. .TP
  1651. .BI textcolor " name
  1652. .TP
  1653. .BI value " n
  1654. Set the button to `on' (if
  1655. .I n
  1656. is non-zero) or `off' (if
  1657. .I n
  1658. is zero).
  1659. .SS "Helper functions
  1660. The function
  1661. .I ctlerror
  1662. is called when the library encounters an error.
  1663. It prints the formatted message and exits the program.
  1664. .PP
  1665. The functions
  1666. .IR ctlmalloc ,
  1667. .IR ctlrealloc ,
  1668. .IR ctlstrdup ,
  1669. and
  1670. .I ctlrunestrdup
  1671. are packagings of the corresponding C library functions.
  1672. They call
  1673. .I ctlerror
  1674. if they fail to allocate memory, and
  1675. .I ctlmalloc
  1676. zeros the memory it returns.
  1677. .PP
  1678. Finally, for debugging, if the global variable
  1679. .I ctldeletequits
  1680. is set to a non-zero value, typing a
  1681. .SM DEL
  1682. will cause the program to call
  1683. .IP
  1684. .EX
  1685. ctlerror("delete");
  1686. .EE
  1687. .SS Caveat
  1688. This library is very new and is still missing a number of important features.
  1689. The details are all subject to change.
  1690. Another level of library that handles geometry and has sensible default
  1691. appearances for the controls would be useful.
  1692. .PP
  1693. One unusual design goal of this library was to make the controls themselves
  1694. easy to implement.
  1695. The reader is encouraged
  1696. to create new controls by adapting the source to existing ones.
  1697. .SH EXAMPLES
  1698. This example creates two entry boxes,
  1699. .BR top
  1700. and
  1701. .BR bot ,
  1702. and copies the contents of one to the other whenever a newline is typed.
  1703. .PP
  1704. .EX
  1705. #include <u.h>
  1706. #include <libc.h>
  1707. #include <thread.h>
  1708. #include <draw.h>
  1709. #include <mouse.h>
  1710. #include <keyboard.h>
  1711. #include <control.h>
  1712. Controlset *cs;
  1713. int ctldeletequits = 1;
  1714. void
  1715. resizecontrolset(Controlset*)
  1716. {
  1717. int i;
  1718. Rectangle r, r1, r2;
  1719. if(getwindow(display, Refnone) < 0)
  1720. sysfatal("resize failed: %r");
  1721. r = insetrect(screen->r, 10);
  1722. r1 = r;
  1723. r2 = r;
  1724. r1.max.y = r1.min.y+1+font->height+1;
  1725. r2.min.y = r1.max.y+10;
  1726. r2.max.y = r2.min.y+1+font->height+1;
  1727. chanprint(cs->ctl, "top rect %R\entop show", r1);
  1728. chanprint(cs->ctl, "bot rect %R\enbot show", r2);
  1729. }
  1730. void
  1731. threadmain(int argc, char *argv[])
  1732. {
  1733. char *s, *args[3];
  1734. Channel *c;
  1735. Control *top, *bot;
  1736. int n;
  1737. initdraw(0, 0, "example");
  1738. initcontrols();
  1739. cs = newcontrolset(screen, nil, nil, nil);
  1740. cs->clicktotype = 1;
  1741. top = createentry(cs, "top");
  1742. chanprint(cs->ctl, "top image paleyellow");
  1743. chanprint(cs->ctl, "top border 1");
  1744. bot = createentry(cs, "bot");
  1745. chanprint(cs->ctl, "bot image paleyellow");
  1746. chanprint(cs->ctl, "bot border 1");
  1747. c = chancreate(sizeof(char*), 0);
  1748. controlwire(top, "event", c);
  1749. controlwire(bot, "event", c);
  1750. activate(top);
  1751. activate(bot);
  1752. resizecontrolset(cs);
  1753. for(;;){
  1754. s = recvp(c);
  1755. n = tokenize(s, args, nelem(args));
  1756. if(n==3 && strcmp(args[1], "value")==0){
  1757. if(strcmp(args[0], "top:") == 0)
  1758. chanprint(cs->ctl, "bot value %q", args[2]);
  1759. else
  1760. chanprint(cs->ctl, "top value %q", args[2]);
  1761. }
  1762. }
  1763. threadexitsall(nil);
  1764. }
  1765. .EE
  1766. .PP
  1767. A richer variant couples a text entry box to a slider.
  1768. Since the value of a slider is its numerical setting, as a decimal number,
  1769. all that needs changing is the setup of
  1770. .BR bot :
  1771. .PP
  1772. .EX
  1773. bot = createslider(cs, "bot");
  1774. chanprint(cs->ctl, "bot border 1");
  1775. chanprint(cs->ctl, "bot image paleyellow");
  1776. chanprint(cs->ctl, "bot indicatorcolor red");
  1777. chanprint(cs->ctl, "bot max 100");
  1778. chanprint(cs->ctl, "bot clamp low 1");
  1779. chanprint(cs->ctl, "bot orient horizontal");
  1780. .EE
  1781. .PP
  1782. The rest is the same.
  1783. Of course, the value of the entry box is only meaningful to the slider
  1784. if it is also a decimal number.
  1785. .PP
  1786. Finally, we can avoid processing events altogether by cross-coupling
  1787. the controls. Replace the rest of
  1788. .B threadmain
  1789. with this:
  1790. .PP
  1791. .EX
  1792. chanprint(cs->ctl, "bot format %q", "%q: top value %q");
  1793. chanprint(cs->ctl, "top format %q", "%q: bot value %q");
  1794. controlwire(top, "event", cs->ctl);
  1795. controlwire(bot, "event", cs->ctl);
  1796. activate(top);
  1797. activate(bot);
  1798. resizecontrolset(cs);
  1799. for(;;)
  1800. yield();
  1801. threadexitsall(nil);
  1802. .EE
  1803. .SH SOURCE
  1804. .B /sys/src/libcontrol
  1805. .SH SEE ALSO
  1806. .IR draw (2),
  1807. .IR frame (2),
  1808. .IR graphics (2),
  1809. .IR quote (2),
  1810. .IR thread (2)
  1811. .SH BUGS
  1812. The library is strict about matters of formatting, argument count in messages,
  1813. etc., and calls
  1814. .I ctlerror
  1815. in situations where it may be fine to ignore the error and continue.