frame

Documentation

Overview

Package frame supports frames of editable text, such as in the Plan 9 text editors sam and acme.

Index

• Constants
• type Frame
  • func (f *Frame) CharOf(pt draw.Point) int
  • func (f *Frame) Clear(newFont bool)
  • func (f *Frame) Delete(p0, p1 int) int
  • func (f *Frame) Drawsel(pt0 draw.Point, p0, p1 int, highlighted bool)
  • func (f *Frame) Drawsel0(pt draw.Point, p0, p1 int, back, text *draw.Image) draw.Point
  • func (f *Frame) Init(r draw.Rectangle, ft *draw.Font, b *draw.Image, cols []*draw.Image)
  • func (f *Frame) InitTick()
  • func (f *Frame) Insert(text []rune, p int)
  • func (f *Frame) PointOf(p int) draw.Point
  • func (f *Frame) Redraw()
  • func (f *Frame) Select(mc *draw.Mousectl)
  • func (f *Frame) SelectPaint(p0, p1 draw.Point, col *draw.Image)
  • func (f *Frame) SetRects(r draw.Rectangle, b *draw.Image)
  • func (f *Frame) Tick(pt draw.Point, ticked bool)

Constants

const (
	BACK  = iota // background color
	HIGH         // highlight background color
	BORD         // border color
	TEXT         // text color
	HTEXT        // highlight text color
	NCOL
)

BACK, HIGH, BORD, TEXT, and HTEXT are indices into Frame.Cols/

Types

type Frame

type Frame struct {
	P0, P1 int // selection
	MaxTab int // max size of tab, in pixels

	// Read-only to clients.
	Font         *draw.Font        // of chars in the frame
	Display      *draw.Display     // on which frame appears
	B            *draw.Image       // on which frame appears
	Cols         [NCOL]*draw.Image // text and background colors
	R            draw.Rectangle    // in which text appears
	Entire       draw.Rectangle    // of full frame
	Scroll       func(*Frame, int) // scroll function provided by application
	NumChars     int               // # runes in frame
	NumLines     int               // # lines with text
	MaxLines     int               // total # lines in frame
	LastLineFull bool              // last line fills frame
	Ticked       bool              // flag: is tick onscreen?
	NoRedraw     int               // don't draw on the screen
	// contains filtered or unexported fields
}

A Frame is a frame of editable text in a single font on a raster display. It may hold any character (even NUL, in contrast to the C original). Long lines are folded and tabs are set at fixed intervals.

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. The Init method sets MaxTab to 8 times the width of a 0 (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.

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 Runes) 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 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.

There are no routines in the library to allocate Frames; instead the interface assumes that Frames will be components of larger structures and initialized using the Init method.

Note that unlike most Go types, Frames must be explicitly freed using the Clear method, in order to release the associated images.

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. See the Tick, Drawsel, Drawsel0, and SelectPaint methods.

func (*Frame) CharOf

func (f *Frame) CharOf(pt draw.Point) int

CharOf is the inverse of PointOf: it returns the index of the closest rune whose image's upper left corner is up and to the left of pt.

func (*Frame) Clear

func (f *Frame) Clear(newFont bool)

Clear frees the internal structures associated with f, permitting another Init or SetRects on the Frame. It does not clear the associated display. If f is to be deallocated, the associated Font and Image (as passed to Init) must be freed separately. The newFont argument should be true if the frame is to be redrawn with a different font; otherwise the frame will maintain some data structures associated with the font.

To resize a frame, use Clear and Init and then Insert to recreate the display. If a frame is being moved but not resized, that is, if the shape of its containing rectangle is unchanged, it is sufficient to use Draw on the underlying image to copy the containing rectangle from the old to the new location and then call SetRects to establish the new geometry. (It is unnecessary to call frinittick unless the font size has changed.) No redrawing is necessary.

func (*Frame) Delete

func (f *Frame) Delete(p0, p1 int) int

Delete deletes from f the text between p0 and p1; p1 points at the first rune beyond the deletion.

func (*Frame) Drawsel

func (f *Frame) Drawsel(pt0 draw.Point, p0, p1 int, highlighted bool)

Drawsel repaints a section of the frame, delimited by character positions p0 and p1, either with plain background or entirely highlighted, according to the flag highlighted, managing the tick appropriately.

The point pt0 is the geometrical location of p0 on the screen; like all of the selection-helper routines' Point arguments, it must be a value generated by PointOf.

func (*Frame) Drawsel0

func (f *Frame) Drawsel0(pt draw.Point, p0, p1 int, back, text *draw.Image) draw.Point

Drawsel0 is a lower-level Drawsel, taking as arguments a background color, back, and text color, text. It assumes that the tick is being handled (removed beforehand, replaced afterwards, as required) by its caller.

func (*Frame) Init

func (f *Frame) Init(r draw.Rectangle, ft *draw.Font, b *draw.Image, cols []*draw.Image)

Init prepares the frame f so characters drawn in it will appear in the font ft. It then calls SetRects and InitTick to initialize the geometry for the frame. The image b is where the frame is to be drawn; the rectangle r defines the limit of the portion of the image the text will occupy. The image pointer may be null, allowing the other routines to be called to maintain the associated data structure in, for example, an obscured window. The array of images cols sets the colors in which text and borders will be drawn. The background of the frame will be drawn in cols[BACK]; the background of highlighted text in cols[HIGH]; borders and scroll bar in cols[BORD]; regular text in cols[TEXT]; and highlighted text in cols[HTEXT].

func (*Frame) InitTick

func (f *Frame) InitTick()

InitTick initializes the frame's tick images. It is called during the Init method and must be called again each time the frame's font changes.

func (*Frame) Insert

func (f *Frame) Insert(text []rune, p int)

Insert inserts text into f starting at rune index p0. 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 frdelete.

func (*Frame) PointOf

func (f *Frame) PointOf(p int) draw.Point

PointOf returns the location of the upper left corner of the p'th rune, starting from 0, 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.

func (*Frame) Redraw

func (f *Frame) Redraw()

func (*Frame) Select

func (f *Frame) Select(mc *draw.Mousectl)

Select tracks the mouse to select a contiguous string of text in the Frame. When called, a mouse button is typically down. Select will return when the button state has changed (some buttons may still be down) and will set f.P0 and f.P1 to the selected range of text.

func (*Frame) SelectPaint

func (f *Frame) SelectPaint(p0, p1 draw.Point, col *draw.Image)

SelectPaint uses a solid color, col, to paint a region of the frame defined by the points p0 and p1.

func (*Frame) SetRects

func (f *Frame) SetRects(r draw.Rectangle, b *draw.Image)

func (*Frame) Tick

func (f *Frame) Tick(pt draw.Point, ticked bool)

Tick draws (if ticked is true) or removes (if ticked is false) the tick at the screen position indicated by pt.