Views
Each one fills a rectangle of the screen. One built from a list skips any
false entry in it, so busy and ito.Spinner() shows a spinner only while
busy is true. A nil ends the list.
ito.view(body)
Makes a view out of body, a function that takes the view’s props and
returns the view to draw. Calling the result with a props table gives a view
to place inside another.
local ito = require("ito")
local Branch = ito.view(function(props)
return ito.Text(props.name):foreground(ito.Color.green)
end)
uji.ui.toolbar({
ito.ToolbarItem(ito.ToolbarPlacement.bottom_bar, function()
return Branch({ name = "main" })
end),
})
A view of your own takes the same modifiers as ito’s views, and they apply to the view its body returns.
A view keeps its state by its place among its siblings. Give it an
id with :id, on ito’s views and your own alike, and the
state follows the view when the list around it changes order.
ito.view raises an error when body is not a function.
ito.VStack(children)
Stacks children from the top down. A child is as tall as its content,
unless it has height,
share or grow.
The children that grow split the rows the others leave, by their weights.
ito.VStack({
ito.Text("Build"):bold(),
ito.Text("3 warnings"):foreground(ito.Color.yellow),
ito.Spacer(),
ito.Text("updated just now"):dim(),
})
:spacing(cells) leaves cells blank rows between each child and the next,
skipping the hidden ones.
ito.HStack(children)
Places children side by side from the left. A child is as wide as its
width, its share, or its text, and one that has grow or no natural width
takes a part of the columns the others leave. :spacing(cells) leaves cells
blank columns between each child and the next.
ito.HStack({ ito.Text("main"), ito.Spacer(), ito.Text("3 files changed") })
ito.HStack({ ito.Text("enter"):bold(), ito.Text("open") }):spacing(1)
ito.Grid(rows) and ito.GridRow(cells)
Stacks rows like ito.VStack and lines up the cells of each
ito.GridRow in columns. A column is as wide as its widest cell, and a column
with a cell that has grow takes a part of the columns the others leave. A
cell with :align keeps its own size inside its
column. When the columns are wider than the grid, the columns with a cell that
has :shrink narrow, the widest first, until they fit,
and the narrower ones keep their width. A row that is not an ito.GridRow
takes the whole width.
ito.Grid({
ito.GridRow({ ito.Text("9"):align(ito.Alignment.top_trailing), ito.Text("main.lua"):grow() }),
ito.GridRow({ ito.Text("120"):align(ito.Alignment.top_trailing), ito.Text("README.md"):grow() }),
})
ito.Spacer()
Fills the room the rest of its stack leaves. Whatever follows it sits at the far edge.
ito.Text(text)
Draws text, one row for each line in it. text is a string, or a list of
spans, each { text, style }, for text in more than one style. A tab takes
four columns. A line too long for the view is cut at its edge unless the text
wraps. Text with more rows than its room shows the first ones, and text from
ctx:typed shows the rows up to its
cursor. These modifiers style the whole text, and a span’s own style goes on
top.
| Modifier | Effect |
|---|---|
:foreground(colour) | The text colour, an ito.Color. |
:bold(), :dim(), :italic(), :underline(), :reverse(), :strikethrough(), :blink() | Turns on that attribute. |
:style(style) | Merges an ito.TextStyle on top of the text’s style so far. |
:wrap() | Wraps each line to the width the view gets. |
:repeating() | Repeats the text across and down all the room the view gets, such as a bar beside a column or a rule across a row. |
ito.Text("build failed"):foreground(ito.Color.red):bold()
ito.Text("3 files"):style(ito.theme().styles.muted)
ito.HStack({
ito.Text("│"):repeating():padding({ trailing = 1 }),
ito.Text({ { "Note", ito.theme().styles.bold }, { " the build is slow on a cold cache" } }):wrap():grow(),
})
ito.Text raises an error when text is neither a string nor a list.
ito.Fold(content, opts)
Shows content up to opts.rows rows. When content is taller, it shows the
first opts.rows rows and, under them, the view opts.more(hidden) gives,
where hidden is the number of rows left out. Without opts.rows it shows all
of content.
ito.Fold(ito.Text(log):wrap(), {
rows = 8,
more = function(hidden)
return ito.Text("… " .. hidden .. " more"):dim()
end,
})
Raises an error when opts.rows is not a whole number or opts.more is not a
function.
ito.Lines(lines, value)
Draws lines, a list of lines, where each line is a list of spans. lines
can also be a function that takes the width the view gets and value, and
returns the lines, for text that wraps. Its lines are kept until the function,
value or the width changes. A span is
{ text, style }, and the style is an
ito.TextStyle, such as one of the
theme’s ito.theme().styles.muted. A span without a style is drawn in the
terminal’s own style. A line with an on_click function calls it when you
click that line.
local ito = require("ito")
local Summary = ito.view(function()
local styles = ito.theme().styles
return ito.Lines({
{ { "tests ", styles.muted }, { "passing", styles.accent } },
{
{ "open the build log", styles.highlight },
on_click = function()
uji.ui.exec("less build.log")
end,
},
})
end)
Styles lists the styles every theme has.
ito.spans.wrap(line, width)
Breaks one line of spans into lines no wider than width, and keeps each
piece in its span’s style. It breaks at the last space that fits and drops
that space, keeps leading spaces with the text after them, and cuts a word
that is wider than width. A line’s on_click and a span’s other fields go
to every piece. It suits an ito.Lines function, which gets the width.
local function code(width, value)
local out = {}
for _, line in ipairs(value.lines) do
for _, row in ipairs(ito.spans.wrap(line, width)) do
out[#out + 1] = row
end
end
return out
end
local Code = ito.view(function(props)
return ito.Lines(code, { lines = props.lines })
end)
ito.Group(children)
Draws children one under another, like ito.VStack. Inside an
ito.LazyVStack, each child becomes a row
of its own, and only the ones that show are built.
ito.ZStack(children)
Draws children on top of each other in the order of the list, so the last
one is in front. Each child sits at the stack’s alignment, center unless
the props name another from ito.Alignment, and
a child’s own :align wins over it. A child takes its fixed size, the whole
stack when it grows, or else the size its content needs.
ito.ZStack({
alignment = ito.Alignment.top_trailing,
ito.Lines(log):grow(),
ito.Text(" 3 new "):background(ito.theme().colors.accent),
})
ito.Subviews(children, builder)
Builds children, then calls builder(subviews) with the ones that drew
something, in order. The builder returns the view to draw and places each
subview in it at most once. A subview keeps its state, and it carries the
hints its parent would read: weight, width, height, alignment and
layout_id. Modifiers on ito.Subviews(...) apply to the view the builder
returns.
This puts a bar between neighbours, but not next to a spacer or a segment that drew nothing:
local function joined(children)
return ito.Subviews(children, function(subviews)
local row = {}
for index, subview in ipairs(subviews) do
local before = subviews[index - 1]
if before and not before.weight and not subview.weight then
row[#row + 1] = ito.Text(" | ")
end
row[#row + 1] = subview
end
return ito.HStack(row)
end)
end
Placing one subview twice raises “a subview can be placed once”.
ito.Layout(measure)
Makes a container from one function. measure(children, room) returns the
container’s width, its height and a place(x, y) function. room.width and
room.height are cells, or nil while the parent asks for a natural size.
Each child has child:measure(room), which gives the width and height it
wants, and child:place(x, y, width, height), plus the weight,
alignment and layout_id hints. A child that place never places is not
drawn.
Lay children out from children and room alone. ito lays a container out
again only when its room or its children change.
local Corners = ito.Layout(function(children, room)
return room.width, room.height, function(x, y)
for _, child in ipairs(children) do
local width, height = child:measure(room)
if child.layout_id == "end" then
child:place(x + room.width - width, y + room.height - height, width, height)
else
child:place(x, y, width, height)
end
end
end
end)
uji.ui.toolbar({
ito.ToolbarItem(ito.ToolbarPlacement.bottom_bar, function()
return Corners({ ito.Text("uji"), ito.Text("v0.4"):layout_id("end") }):height(1)
end),
})
ito.SubcomposeLayout(build, opts)
Calls build(room) with the room the view gets, { width, height } in cells,
and draws the view it returns. While its parent measures it, the height is
math.huge. The content keeps its state across frames. An error while
building is passed to opts.failed(message) when you give one, and the view
then draws nothing. In an ito.HStack it takes the room the other views
leave, unless it has a width.
ito.SubcomposeLayout(function(room)
if room.width < 60 then
return ito.Text(uji.model.current().model)
end
return ito.Text(uji.model.current().name .. "/" .. uji.model.current().model)
end)