frame 7.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362
  1. .TH FRAME 2
  2. .SH NAME
  3. frinit, frsetrects, frinittick, frclear, frcharofpt, frptofchar, frinsert, frdelete, frselect, frtick, frselectpaint, frdrawsel, frdrawsel0, frgetmouse \- frames of text
  4. .SH SYNOPSIS
  5. .nf
  6. .B
  7. #include <u.h>
  8. .B
  9. #include <libc.h>
  10. .B
  11. #include <draw.h>
  12. .B
  13. #include <thread.h>
  14. .B
  15. #include <mouse.h>
  16. .B
  17. #include <frame.h>
  18. .PP
  19. .B
  20. void frinit(Frame *f, Rectangle r, Font *ft, Image *b, Image **cols)
  21. .PP
  22. .B
  23. void frsetrects(Frame *f, Rectangle r, Image *b)
  24. .PP
  25. .B
  26. void frinittick(Frame *f)
  27. .PP
  28. .B
  29. void frclear(Frame *f, int resize)
  30. .PP
  31. .B
  32. ulong frcharofpt(Frame *f, Point pt)
  33. .PP
  34. .B
  35. Point frptofchar(Frame *f, ulong p)
  36. .PP
  37. .B
  38. void frinsert(Frame *f, Rune *r0, Rune *r1, ulong p)
  39. .PP
  40. .B
  41. int frdelete(Frame *f, ulong p0, ulong p1)
  42. .PP
  43. .B
  44. void frselect(Frame *f, Mousectl *m)
  45. .PP
  46. .B
  47. void frtick(Frame *f, Point pt, int up)
  48. .PP
  49. .B
  50. void frselectpaint(Frame *f, Point p0, Point p1, Image *col)
  51. .PP
  52. .B
  53. void frdrawsel(Frame *f, Point pt0, ulong p0, ulong p1,
  54. .B
  55. int highlighted)
  56. .PP
  57. .B
  58. void frdrawsel0(Frame *f, Point pt0, ulong p0, ulong p1,
  59. .B
  60. Image *back, Image *text)
  61. .PP
  62. .ft L
  63. enum{
  64. BACK,
  65. HIGH,
  66. BORD,
  67. TEXT,
  68. HTEXT,
  69. NCOL
  70. };
  71. .fi
  72. .SH DESCRIPTION
  73. This library supports
  74. .I frames
  75. of editable text in a single font on raster displays, such as in
  76. .IR sam (1)
  77. and
  78. .IR rio (1).
  79. Frames may hold any character except NUL (0).
  80. Long lines are folded and tabs are at fixed intervals.
  81. .PP
  82. The user-visible data structure, a
  83. .BR Frame ,
  84. is defined in
  85. .BR <frame.h> :
  86. .IP
  87. .EX
  88. .ta 6n +\w'Rectangle 'u +\w'lastlinefull; 'u
  89. typedef struct Frame Frame;
  90. struct Frame
  91. {
  92. Font *font; /* of chars in the frame */
  93. Display *display; /* on which frame appears */
  94. Image *b; /* on which frame appears */
  95. Image *cols[NCOL]; /* text and background colors */
  96. Rectangle r; /* in which text appears */
  97. Rectangle entire; /* of full frame */
  98. Frbox *box;
  99. ulong p0, p1; /* selection */
  100. ushort nbox, nalloc;
  101. ushort maxtab; /* max size of tab, in pixels */
  102. ushort nchars; /* # runes in frame */
  103. ushort nlines; /* # lines with text */
  104. ushort maxlines; /* total # lines in frame */
  105. ushort lastlinefull; /* last line fills frame */
  106. ushort modified; /* changed since frselect() */
  107. Image *tick; /* typing tick */
  108. Image *tickback; /* saved image under tick */
  109. int ticked; /* flag: is tick onscreen? */
  110. };
  111. .EE
  112. .PP
  113. .B Frbox
  114. is an internal type and is not used by the interface.
  115. .B P0
  116. and
  117. .B p1
  118. may be changed by the application provided the selection routines are called
  119. afterwards to maintain a consistent display.
  120. .I Maxtab
  121. determines the size of tab stops.
  122. .I Frinit
  123. sets it to 8 times the width of a
  124. .B 0
  125. (zero)
  126. character in the font;
  127. it may be changed before any text is added to the frame.
  128. The other elements of the structure are maintained by the library and
  129. should not be modified directly.
  130. .PP
  131. The text within frames
  132. is not directly addressable;
  133. instead frames are designed to work alongside
  134. another structure that holds the text.
  135. The typical application is to display a section of a longer document such
  136. as a text file or terminal session.
  137. Usually the program will keep its own copy of the
  138. text in the window (probably as
  139. an array of
  140. .BR Runes )
  141. and pass components of this text to the frame routines to
  142. display the visible portion.
  143. Only the text that is visible is held by the
  144. .BR Frame ;
  145. the application must check
  146. .BR maxlines ,
  147. .BR nlines ,
  148. and
  149. .B lastlinefull
  150. to determine, for example, whether new text needs to be appended
  151. at the end of the
  152. .B Frame
  153. after calling
  154. .I frdelete
  155. (q.v.).
  156. .PP
  157. There are no routines in the library to allocate
  158. .BR Frames ;
  159. instead the interface assumes that
  160. .B Frames
  161. will be components of larger structures.
  162. .I Frinit
  163. prepares the
  164. .B Frame
  165. .I f
  166. so characters drawn in it will appear
  167. in the single
  168. .B Font
  169. .IR ft .
  170. It then calls
  171. .I frsetrects
  172. and
  173. .I frinittick
  174. to initialize the geometry for the
  175. .BR Frame .
  176. The
  177. .B Image
  178. .I b
  179. is where the
  180. .B Frame
  181. is to be drawn;
  182. .B Rectangle
  183. .I r
  184. defines the limit of the portion of the
  185. .B Image
  186. the text will occupy.
  187. The
  188. .B Image
  189. pointer
  190. may be null, allowing the other routines to be called to maintain the
  191. associated data structure in, for example, an obscured window.
  192. .PP
  193. The array of
  194. .B Images
  195. cols sets the colors in which text and borders will be drawn. The background of the frame will be drawn in
  196. .BR cols[BACK] ;
  197. the background of highlighted text in
  198. .BR cols[HIGH] ;
  199. borders and scroll bar in
  200. .BR cols[BORD] ;
  201. regular text in
  202. .BR cols[TEXT] ;
  203. and highlighted text in
  204. .BR cols[HTEXT] .
  205. .PP
  206. .I Frclear
  207. frees the internal structures associated with
  208. .IR f ,
  209. permitting another
  210. .I frinit
  211. or
  212. .I frsetrects
  213. on the
  214. .BR Frame .
  215. It does not clear the associated display.
  216. If
  217. .I f
  218. is to be deallocated, the associated
  219. .B Font
  220. and
  221. .B Image
  222. must be freed separately.
  223. The
  224. .B resize
  225. argument should be non-zero if the frame is to be redrawn with
  226. a different font; otherwise the frame will maintain some
  227. data structures associated with the font.
  228. .PP
  229. To resize a
  230. .BR Frame ,
  231. use
  232. .I frclear
  233. and
  234. .I frinit
  235. and then
  236. .I frinsert
  237. (q.v.) to recreate the display.
  238. If a
  239. .B Frame
  240. is being moved but not resized, that is, if the shape of its containing
  241. rectangle is unchanged, it is sufficient to use
  242. .IR draw (2)
  243. to copy the containing rectangle from the old to the new location and then call
  244. .I frsetrects
  245. to establish the new geometry.
  246. (It is unnecessary to call
  247. .I frinittick
  248. unless the font size has changed.)
  249. No redrawing is necessary.
  250. .PP
  251. .B Frames
  252. hold text as runes,
  253. not as bytes.
  254. .I Frptofchar
  255. returns the location of the upper left corner of the
  256. .I p'th
  257. rune, starting from 0, in the
  258. .B Frame
  259. .IR f .
  260. If
  261. .I f
  262. holds fewer than
  263. .I p
  264. runes,
  265. .I frptofchar
  266. returns the location of the upper right corner of the last character in
  267. .IR f .
  268. .I Frcharofpt
  269. is the inverse: it
  270. returns the index of the closest rune whose image's upper left corner
  271. is up and to the left of
  272. .IR pt .
  273. .PP
  274. .I Frinsert
  275. inserts into
  276. .B Frame
  277. .I f
  278. starting at rune index
  279. .I p
  280. the runes between
  281. .I r0
  282. and
  283. .IR r1 .
  284. If a NUL (0) character
  285. is inserted, chaos will ensue.
  286. Tabs and newlines
  287. are handled by the library, but all other characters,
  288. including control characters, are just displayed.
  289. For example, backspaces are printed; to erase
  290. a character, use
  291. .IR frdelete .
  292. .PP
  293. .I Frdelete
  294. deletes from the
  295. .B Frame
  296. the text between
  297. .I p0
  298. and
  299. .IR p1 ;
  300. .I p1
  301. points at the first rune beyond the deletion.
  302. .PP
  303. .I Frselect
  304. tracks the mouse to select a contiguous string of text in the
  305. .BR Frame .
  306. When called, a mouse button is typically down.
  307. .I Frselect
  308. will return when the button state has changed (some buttons may
  309. still be down) and will set
  310. .IB f ->p0
  311. and
  312. .IB f ->p1
  313. to the selected range of text.
  314. .PP
  315. Programs that wish to manage the selection themselves have several routines to help.
  316. They involve the maintenance of the `tick', the vertical line indicating a null selection
  317. between characters, and the colored region representing a non-null selection.
  318. .I Frtick
  319. draws (if
  320. .I up
  321. is non-zero) or removes (if
  322. .I up
  323. is zero) the tick at the screen position indicated by
  324. .IR pt .
  325. .I Frdrawsel
  326. repaints a section of the frame, delimited by character positions
  327. .I p0
  328. and
  329. .IR p1 ,
  330. either with plain background or
  331. entirely highlighted, according to the flag
  332. .IR highlighted ,
  333. managing the tick appropriately.
  334. The point
  335. .I pt0
  336. is the geometrical location of
  337. .I p0
  338. on the screen; like all of the selection-helper routines'
  339. .B Point
  340. arguments, it must be a value generated by
  341. .IR frptofchar .
  342. .I Frdrawsel0
  343. is a lower-level routine, taking as arguments a background color,
  344. .IR back ,
  345. and text color,
  346. .IR text .
  347. It assumes that the tick is being handled (removed beforehand, replaced afterwards, as required)
  348. by its caller.
  349. .I Frselectpaint
  350. uses a solid color,
  351. .IR col ,
  352. to paint a region of the frame defined by the
  353. .B Points
  354. .I p0
  355. and
  356. .IR p1 .
  357. .SH SOURCE
  358. .B /sys/src/libframe
  359. .SH SEE ALSO
  360. .IR graphics (2),
  361. .IR draw (2),
  362. .IR cachechars (2).