README
¶
ifitfits
ifitfits — a viewport tiling engine ("if it fits, it shows")
If you use this, please support me on ko-fi: https://ko-fi.com/jeffday
A small, renderer-agnostic tiling engine in Go. It maintains an oriented tree of tiles and resolves it to boxes by a space-negotiation waterfall, with tabbed stacks, magnify lenses, and a caret that steers directional navigation. It draws nothing and knows nothing about pixels or cells — it only does arithmetic on the numbers a host gives it — so the same engine drives a terminal desktop or a graphical one.
It's a sibling to the rest of the line: Mew (text editor), PurfecTerm (terminal emulator), PawScript (language), and KittyTK (UI toolkit). The name reads "if it fits" — a window shows if there's room for it; when the workspace runs out, the lowest-priority tiles are omitted, cleanly.
Model
- A tile is a leaf of the tree with a unique, library-assigned handle — the id every command takes. A tile also carries a ref: host content identity, which (unlike a handle) may be shared across many tiles.
- Space is allocated along each group's axis by a waterfall: minimums → pins → zoom → natural → mop-up, with a cross-axis omission pass. Overflow is resolved by priority; a stack reports the max of its tabs, so flipping a tab never triggers a relayout.
- The engine does not own focus — that's the host's job. Every command takes
an explicit tile; the host reports focus (
SetFocus) only so a lens knows when to dismiss.
Use
import "github.com/phroun/ifitfits"
vp, first := ifitfits.NewViewport(1920, 1080) // one tile, filling the workspace
vp.Set(first, "editor") // give it a content ref
right := vp.Split(first, ifitfits.Right) // split; clones "editor"
vp.Set(right, "terminal")
vp.Stack(right, ifitfits.On) // fold its group into tabs
for _, b := range vp.Tiles() { // resolved boxes, for the host to draw
draw(b.Ref, b.Rect)
}
dest := vp.Go(first, ifitfits.Right) // navigate; returns the destination tile
vp.Monocle(dest, ifitfits.On) // magnify it to fill the screen
The full command surface — and the mew (PawScript) viewport_* names each
method mirrors — is in COMMANDS.md.
Test
go test ./...
License
MIT — see LICENSE.
Documentation
¶
Overview ¶
Package ifitfits is a renderer-agnostic viewport tiling engine: an oriented tree of tiles that negotiates space by a minimums → pins → zoom → natural → shrink → mop-up waterfall, with tabbed stacks, magnify lenses, and a caret that steers directional navigation.
The library owns the layout, not the host's focus. Every command takes an explicit tile Handle; the host reports focus (SetFocus) only so an active lens knows when to dismiss. Coordinates are whatever the host uses — the engine only does arithmetic on the numbers it is given.
See COMMANDS.md for the mew (PawScript) command names these methods mirror.
Index ¶
- func NewViewport(width, height float64) (*Viewport, Handle)
- type Box
- type Direction
- type Handle
- type Mode
- type Orient
- type Rect
- type Stack
- type State
- type Tab
- type Viewport
- func (v *Viewport) Balance(tile Handle, recursive bool)
- func (v *Viewport) Caret() (x, y float64)
- func (v *Viewport) Close(tile Handle) Handle
- func (v *Viewport) Content(tile Handle) string
- func (v *Viewport) Contract(tile Handle, delta float64)
- func (v *Viewport) Down(t Handle) Handle
- func (v *Viewport) Equalize(tile Handle, recursive bool)
- func (v *Viewport) Expand(tile Handle, delta float64)
- func (v *Viewport) Flip(tile Handle)
- func (v *Viewport) FlipParent(tile Handle)
- func (v *Viewport) Get(ref string, includeHidden bool) []Handle
- func (v *Viewport) GetFocus() Handle
- func (v *Viewport) GetTile(x, y float64) Handle
- func (v *Viewport) Go(tile Handle, d Direction) Handle
- func (v *Viewport) Left(t Handle) Handle
- func (v *Viewport) LocalMonocle(tile Handle, state State)
- func (v *Viewport) LocalSpectacle(tile Handle, state State)
- func (v *Viewport) Merge(tile Handle, d Direction)
- func (v *Viewport) MergeDown(t Handle)
- func (v *Viewport) MergeLeft(t Handle)
- func (v *Viewport) MergeRight(t Handle)
- func (v *Viewport) MergeUp(t Handle)
- func (v *Viewport) ModeNext(tile Handle)
- func (v *Viewport) ModePrior(tile Handle)
- func (v *Viewport) Monocle(tile Handle, state State)
- func (v *Viewport) MoveTabNext(tile Handle)
- func (v *Viewport) MoveTabPrior(tile Handle)
- func (v *Viewport) New(tile Handle, d Direction, ref ...string) Handle
- func (v *Viewport) Next(t Handle) Handle
- func (v *Viewport) Normal(tile Handle)
- func (v *Viewport) Prior(t Handle) Handle
- func (v *Viewport) Resize(tile Handle, size float64)
- func (v *Viewport) Reveal(tile Handle) Handle
- func (v *Viewport) Reverse(tile Handle)
- func (v *Viewport) ReverseParent(tile Handle)
- func (v *Viewport) Right(t Handle) Handle
- func (v *Viewport) Set(tile Handle, ref string)
- func (v *Viewport) SetCaret(tile Handle, x, y float64)
- func (v *Viewport) SetFocus(tile Handle)
- func (v *Viewport) SetMetrics(tile Handle, minW, minH, natW, natH float64)
- func (v *Viewport) SetPriority(tile Handle, p int)
- func (v *Viewport) SetStackReserve(h float64)
- func (v *Viewport) SetWorkspace(width, height float64)
- func (v *Viewport) Shrink(tile Handle, state State)
- func (v *Viewport) Spectacle(tile Handle, state State)
- func (v *Viewport) Split(tile Handle, d Direction, ref ...string) Handle
- func (v *Viewport) Stack(tile Handle, state State)
- func (v *Viewport) Stacks() []Stack
- func (v *Viewport) Swap(tile Handle, d Direction)
- func (v *Viewport) SwapDown(t Handle)
- func (v *Viewport) SwapLeft(t Handle)
- func (v *Viewport) SwapRight(t Handle)
- func (v *Viewport) SwapUp(t Handle)
- func (v *Viewport) TabNext(tile Handle) Handle
- func (v *Viewport) TabPrior(tile Handle) Handle
- func (v *Viewport) Tiles() []Box
- func (v *Viewport) Up(t Handle) Handle
- func (v *Viewport) Zoom(tile Handle, state State)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewViewport ¶
NewViewport creates a viewport of the given size holding a single tile, and returns the viewport and that tile's handle. The engine is unit-agnostic: a fresh tile carries no intrinsic minimum or natural size (all zero) and the stack header reserve is zero, so it invents no measurement of its own — the host supplies sizes in its own units via SetMetrics / SetStackReserve.
Types ¶
type Box ¶
type Box struct {
Tile Handle
Ref string
Rect Rect
Mode Mode
Pinned bool
Selected bool // the shown tab of a stacked parent
Priority int
}
Box is one resolved, on-screen tile, handed to the host for drawing.
type Direction ¶
type Direction uint8
Direction values accepted by the structural and navigation commands.
type Handle ¶
type Handle uint64
Handle is an opaque, unique identifier for a tile (a leaf of the layout tree). It is distinct from a tile's ref: a ref is host content identity and may be shared across many tiles, while a handle names exactly one tile.
type Rect ¶
type Rect struct{ X, Y, W, H float64 }
Rect is an axis-aligned box in the host's coordinate space.
type State ¶
type State uint8
State is the tri-state used by toggling commands (Stack, Zoom, Shrink, lenses). The zero value is Toggle, matching the mew "omit = toggle" default.
type Tab ¶
Tab is one entry of a stack's header, for the host to draw a tab strip. Tile is the leaf revealing that tab (pass it to Reveal on a click).
type Viewport ¶
type Viewport struct {
// contains filtered or unexported fields
}
Viewport is a tiling layout. It is not safe for concurrent use.
func (*Viewport) Balance ¶
Balance clears the group's pins only; naturals + priority re-derive the sizes.
func (*Viewport) Close ¶
Close removes `tile` and returns the tile focus should move to (0 if the tree emptied — a fresh tile is created).
func (*Viewport) Equalize ¶
Equalize throws out the group's pins and modes and pins each child to an equal share of the axis (ignoring naturals). recursive descends the whole subtree.
func (*Viewport) FlipParent ¶
FlipParent flips the orientation one level up.
func (*Viewport) Get ¶
Get returns every tile carrying ref. When includeHidden is false, tiles that are not currently on screen (hidden tabs or overflow omissions) are skipped.
func (*Viewport) GetFocus ¶
GetFocus returns the last tile the host reported via SetFocus (0 if none or if it has since been closed). The engine does not otherwise track focus.
func (*Viewport) GetTile ¶
GetTile returns the tile at absolute workspace coordinates, hit-testing the fully resolved (on-screen) layout. Returns 0 if none.
func (*Viewport) Go ¶
Go moves in a direction and returns the destination tile, updating the caret as a side effect. Spatial directions (Up/Down/Left/Right) navigate by geometry and, at a workspace edge, slide the caret instead of moving. Prior/Next cycle the whole tree in reading order (wrapping).
func (*Viewport) LocalMonocle ¶
LocalMonocle magnifies the tile to fill its own group box.
func (*Viewport) LocalSpectacle ¶
LocalSpectacle magnifies the tile's enclosing group to fill its own group box.
func (*Viewport) Merge ¶
Merge moves the single tile `tile` into the adjacent group in `dir` — a lone tab can be extracted from its stack without dragging the rest along.
func (*Viewport) MergeRight ¶
func (*Viewport) MoveTabNext ¶
MoveTabNext/MoveTabPrior reorder the active tab within its stack (no wrap).
func (*Viewport) MoveTabPrior ¶
func (*Viewport) New ¶
New inserts a new tile relative to `tile`. A directional new busts out to the nearest matching-axis level. The new tile clones `tile`'s ref unless a ref is given. Returns the new tile.
func (*Viewport) Reveal ¶
Reveal makes a tile the shown tab of every stacked ancestor, so it is no longer hidden behind a tab. Returns the tile.
func (*Viewport) ReverseParent ¶
ReverseParent reverses the grandparent's child order.
func (*Viewport) SetCaret ¶
SetCaret sets the caret goal from coordinates LOCAL to a tile (0,0 = the tile's top-left), clamped to the tile's size, then mapped into the workspace.
func (*Viewport) SetFocus ¶
SetFocus tells the engine the host moved focus to `tile`. Its only effect is to dismiss an active lens when focus lands outside the magnified subtree.
func (*Viewport) SetMetrics ¶
SetMetrics sets a tile's intrinsic minimum and natural sizes (host content hints). Zero values are left unchanged.
func (*Viewport) SetPriority ¶
SetPriority sets a tile's overflow priority (higher survives longer).
func (*Viewport) SetStackReserve ¶ added in v0.1.1
SetStackReserve sets the header band (in the host's units) that every stacked group carves off the top of its box for a host-drawn tab strip; the shown tab is laid out below it. Zero (the default) reserves nothing, so the shown tab fills the whole stack box. Negative values clamp to zero.
func (*Viewport) SetWorkspace ¶
SetWorkspace sets the workspace size that layout fills.
func (*Viewport) Spectacle ¶
Spectacle magnifies the tile's enclosing group to fill the whole screen.
func (*Viewport) Split ¶
Split wraps `tile` in a new nested group in place; the new tile clones `tile`'s ref unless a ref is given. Returns the new tile.
func (*Viewport) Stack ¶
Stack folds `tile`'s group into a tabbed stack or unfolds it. state On stacks, Off unstacks, Toggle flips.
func (*Viewport) Stacks ¶
Stacks returns the visible tabbed stacks so the host can draw their tab strips (including tabs not currently shown — which Tiles omits).
func (*Viewport) Swap ¶
Swap exchanges `tile` (its whole box, if it is a stacked tab) with the neighbor in `dir`; at a workspace edge it slides the caret instead (a non-swap).
func (*Viewport) TabNext ¶
TabNext cycles the tile's enclosing stack forward and returns the newly shown tile. Nested stacks read as one continuous order (step the innermost that can move, escalate at each boundary, and only the OUTERMOST wraps). When the tile is not inside any stack, it runs the loose odometer over the visible tab-groups instead (which does not move focus) and returns the tile unchanged.
Source Files