| <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> |
