tframe.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tframe.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) .