diff options
Diffstat (limited to 'man/man3/frame.html')
| -rw-r--r-- | man/man3/frame.html | 325 |
1 files changed, 325 insertions, 0 deletions
diff --git a/man/man3/frame.html b/man/man3/frame.html new file mode 100644 index 00000000..4a80453c --- /dev/null +++ b/man/man3/frame.html @@ -0,0 +1,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> |