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