--- name: "frame" section: "3g" platform: "linux" package: "libxg-dev" version: "4.3-14" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/frame/3g" --- # frame(3g) frames of text ## NAME frinit, frsetrects, frclear, frcharofpt, frptofchar, frinsert, frdelete, frselect, frselectp, frselectf, frgetmouse - frames of text ## SYNOPSIS ``` #include #include #include #include ``` **void frinit(Frame \*f, Rectangle r, Font \*ft, Bitmap \*b);** **void frsetrects(Frame \*f, Rectangle r, Bitmap \*b);** **void frclear(Frame \*f);** **ulong frcharofpt(Frame \*f, Point pt);** **Point frptofchar(Frame \*f, ulong p);** **void frinsert(Frame \*f, Rune \*r0, Rune \*r1, ulong p);** **int frdelete(Frame \*f, ulong p0, ulong p1);** **void frselect(Frame \*f, Mouse \*m);** **void frselectp(Frame \*f, Fcode fc);** **void frselectf(Frame \*f, Point p0, Point p1, Fcode c);** **extern void frgetmouse(void);** ## DESCRIPTION This library supports *frames* of editable text in a single font on bitmap displays, such as in [*sam*(1)](/sam/1.md), 8½ (1), and *9term*(1). Frames may hold any character except NUL. Long lines are folded and tabs are at fixed intervals. The user-visible data structure, a **Frame**, is defined in **\**: - ``` typedef struct Frame Frame; struct Frame { Font *font; /* of chars in the frame */ Bitmap *b; /* on which frame appears */ Rectangle r; /* in which text appears */ Rectangle entire; /* of full frame */ Frbox *box; ulong p0, p1; /* selection */ short left; /* left edge of text */ ushort nbox, nalloc; ushort maxtab; /* max size of tab, in pixels */ ushort nchars; /* # runes in frame */ ushort nlines; /* # lines with text */ ushort maxlines; /* total # lines in frame */ ushort lastlinefull; /* last line fills frame */ ushort modified; /* changed since frselect() */ }; ``` **Frbox** is an internal type and is not used by the interface. **P0** and **p1** may be changed by the application provided the selection routines are called afterwards to maintain a consistent display. *Maxtab* determines the size of tab stops. *Frinit* sets it to 8 times the width of a **1** 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. There are no routines in the library to allocate **Frames**; instead the interface assumes that **Frames** will be components of larger structures. *Frinit* prepares the **Frame** *f* so characters drawn in it will appear in the single **Font** *ft.* It then calls **frsetrects** to initialize the geometry for the **Frame.** The **Bitmap** *b* is where the **Frame** is to be drawn; **Rectangle** *r* defines the limit of the portion of the **Bitmap** the text will occupy. The **Bitmap** pointer may be null, allowing the other routines to be called to maintain the associated data structure in, for example, an obscured window. *Frclear* frees the internal structures associated with *f,* permitting another *frinit* or *frsetrects* on the **Frame**. If *f* is to be deallocated, the associated **Font** and **Bitmap** must be freed separately. To reshape a **Frame,** use *frclear* and *frinit* and then *frinsert* (q.v.) to recreate the display. If a **Frame** is being moved but not reshaped, that is, if the shape of its containing rectangle is unchanged, it is sufficient to [*bitblt*(3g)](/bitblt/3g.md) the containing rectangle from the old to the new location and then call *frsetrects* to establish the new geometry. No redrawing is necessary. **Frames** hold text as runes, not as bytes. *Frptofchar* returns the location of the upper left corner of the *p'th* rune in the **Frame** *f.* If *f* holds fewer than *p* runes, *frptofchar* returns the location of the upper right corner of the last character in *f.* *Frcharofpt* is the inverse: it returns the index of the closest rune whose image's upper left corner is up and to the left of *pt.* *Frinsert* inserts into **Frame** *f* starting at rune index *p* the runes between *r0* and *r1.* *Frdelete* deletes from the **Frame** the text between *p0* and *p1.* *Frselect* tracks the mouse to select a contiguous string of text in the **Frame**. When called, mouse button 1 should be depressed. It will return when the button is released and will set *f***-\>p0** and *f***-\>p1** to the selected range of text. *Frselectf* and *Frselectp* modify the display of the selected text. *Frselectf* highlights the text between *p0* and *p1* (which must have been returned by *frptofochar*) using **bitblt** in mode *c.* *Frselectp* is similar but highlights the text from *f***-\>p0** to *f***-\>p1***.* Neither *frselectf* nor *frselectp* modifies *f***-\>p0** or *f***-\>p1***.* Upon return from *frinsert* or *frdelete,* the display will be consistent but *f***-\>p0** and *f***-\>p1** may not point to the desired selection. It may be necessary to adjust the selection and use *frselectf* or *frselectp* to fix the display. *Frgetmouse* must be provided by the application; *frselect* calls it to get mouse updates. Each call to *frgetmouse* should update the **Mouse** structure pointed to by *frselect's* argument *m.* *Frgetmouse* should block until the mouse status has changed. 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. Only the text that is visible is held by the **Frame**; the application must check **maxlines**, **nlines**, and **lastlinefull** to determine, for example, whether new text needs to be appended at the end of the **Frame** after calling **frdelete**. ## SEE ALSO [*graphics*(3g)](/graphics/3g.md), [*bitblt*(3g)](/bitblt/3g.md), [*event*(3g)](/event/3g.md), *cachechar*(3g).