frame.3 (7880B)
1 .TH FRAME 3 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 .MR sam (1) 77 and 78 .MR 9term (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 .MR draw (3) 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 \*9/src/libframe 359 .SH SEE ALSO 360 .MR graphics (3) , 361 .MR draw (3) , 362 .MR cachechars (3) .