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