The content of this document has been updated to align with the upcoming major release of Yazi 0.4.
Please make sure you are using the latest nightly version of Yazi to access these APIs.
Layout
Text, List, Bar, Border, and Gauge are renderable elements; others need to be placed within any of them.
Rect
A Rect is represented an area within the terminal by four attributes:
ui.Rect {
x = 10, -- x position
y = 10, -- y position
w = 20, -- width
h = 30, -- height
}
ui.Rect.default -- Equal to `ui.Rect { x = 0, y = 0, w = 0, h = 0 }`
Properties:
x
- x positiony
- y positionw
- widthh
- heightleft
- left positionright
- right positiontop
- top positionbottom
- bottom position
Methods (return self
if not specified):
padding(padding)
- Set padding, accepts a Padding
You can get a pre-computed Rect
through ui.Layout()
.
Note that if you intend to create a Rect
yourself, ensure these values are calculated accurately; otherwise, it may cause Yazi to crash!
Padding
All parameters for padding are integers:
ui.Padding(left, right, top, bottom)
Properties:
left
- left paddingright
- right paddingtop
- top paddingbottom
- bottom padding
If you want to specify only one of them, you can:
ui.Padding.left(left)
equal toui.Padding(left, 0, 0, 0)
ui.Padding.right(right)
equal toui.Padding(0, right, 0, 0)
ui.Padding.top(top)
equal toui.Padding(0, 0, top, 0)
ui.Padding.bottom(bottom)
equal toui.Padding(0, 0, 0, bottom)
Or specify a particular direction for them:
ui.Padding.x(x)
equal toui.Padding(x, x, 0, 0)
ui.Padding.y(y)
equal toui.Padding(0, 0, y, y)
ui.Padding.xy(x, y)
equal toui.Padding(x, x, y, y)
Style
Create a style:
ui.Style()
Methods (return self
if not specified):
fg(color)
- Set the foreground color of the style, which accepts a Colorbg(color)
- Set the background color of the style, which accepts a Colorbold()
- Set the style to bolddim()
- Set the style to dimitalic()
- Set the style to italicunderline()
- Set the style to underlineblink()
- Set the style to blinkblink_rapid()
- Set the style to blink rapidlyreverse()
- Set the style to reversehidden()
- Set the style to hiddencrossed()
- Set the style to crossedreset()
- Reset the stylepatch(style)
- Patch the style with anotherStyle
Span
ui.Span
is the smallest unit of text, yet a component of ui.Line
. Create a span:
ui.Span("foo")
For convenience, ui.Span
can also accept itself as a argument:
ui.Span(ui.Span("bar"))
Methods (return self
if not specified):
visible()
- Whether the span is visible (includes any printable characters), which returns a boolean.style(style)
- Set the style of the span, which accepts a Style
Besides applying the whole Style
, you can also call those methods of Style
directly on it, which means:
local style = ui.Style():fg("white"):bg("black"):bold()
ui.Span("Hello world"):style(style)
can be also written as:
ui.Span("Hello world"):fg("white"):bg("black"):bold()
Line
ui.Line
represents a line, consisting of multiple ui.Span
s, and it accepts a table of them:
ui.Line { ui.Span("foo"), ui.Span("bar") }
For convenience, the following types are also supported:
-- string
ui.Line("foo")
-- ui.Span
ui.Line(ui.Span("bar"))
-- ui.Line itself
ui.Line(ui.Line("baz"))
-- Mixed table of string, ui.Span, ui.Line
ui.Line { "foo", ui.Span("bar"), ui.Line("baz") }
Methods (return self
if not specified):
area(rect)
- accepts a Rect, changing the area of the line. If not specified, returns the current area.width()
- Get the width of the line, which returns an integer.align(alignment)
- Set the alignment of the line. It accepts the following constants:ui.Line.LEFT
ui.Line.CENTER
ui.Line.RIGHT
visible()
- Whether the line is visible (includes any printable characters), which returns a boolean.style(style)
- Set the style of the line, which accepts a Style.
Like with Span
, you can directly call Style
methods on it
ui.Line("Hello world"):fg("white"):bg("black"):bold()
Text
ui.Text
is used to represent multi-line text, it takes a table of ui.Line
:
ui.Text { ui.Line("foo"), ui.Line("bar") }
For convenience, the following types are also supported:
-- string
ui.Text("foo\nbar")
-- ui.Line
ui.Text(ui.Line("foo"))
-- ui.Span
ui.Text(ui.Span("bar"))
-- Mixed table of string, ui.Line, ui.Span
ui.Text { "foo", ui.Line("bar"), ui.Span("baz") }
You can also use ui.Text.parse(code)
to parse an ANSI escape sequence string into a text.
Methods (return self
if not specified):
area(rect)
- accepts a Rect, changing the area of the text. If not specified, returns the current area.align(alignment)
- Set the alignment of the text, accepts the following constants:ui.Text.LEFT
ui.Text.CENTER
ui.Text.RIGHT
wrap(wrap)
- Set the wrap of the text, which accepts the following constants:ui.Text.WRAP_NO
- No wrapui.Text.WRAP
- Wrap at the end of the lineui.Text.WRAP_TRIM
- Wrap at the end of the line, and trim the leading whitespace
max_width()
- Get the maximum width of the text, which returns an integerstyle(style)
- Set the style of the text, which accepts a Style
Like with Span
, you can directly call Style
methods on it:
ui.Text("Hello world"):fg("white"):bg("black"):bold()
Layout
Create a layout:
local areas = ui.Layout()
:direction(ui.Layout.HORIZONTAL)
:constraints({ ui.Constraint.Percentage(50), ui.Constraint.Percentage(50) })
:split(area)
local left = areas[1] -- The first rect
local right = areas[2] -- The second rect
Methods (return self
if not specified):
direction(direction)
- Set the direction of the layout, which accepts the following constants:ui.Layout.HORIZONTAL
ui.Layout.VERTICAL
margin(margin)
- Set the margin of the layout, which accepts an positive integer.margin_h(margin)
- Set the horizontal margin of the layout, which accepts an positive integer.margin_v(margin)
- Set the vertical margin of the layout, which accepts an positive integer.constraints({ constraint, ... })
- Set the constraints of the layout, which accepts a list of Constraint.split(rect)
- Accepts a Rect and split it into multiple Rect according to the constraints.
Constraint
A constraint that defines the size of a layout element.
Constraints can be used to specify a fixed size, a percentage of the available space, a ratio of the available space, a minimum or maximum size or a fill proportional value for a layout element.
Relative constraints (percentage, ratio) are calculated relative to the entire space being divided, rather than the space available after applying more fixed constraints (min, max, length).
Constraints are prioritized in the following order:
ui.Constraint.Min(min)
ui.Constraint.Max(max)
ui.Constraint.Length(len)
ui.Constraint.Percentage(p)
ui.Constraint.Ratio(num, den)
ui.Constraint.Fill(scale)
Min(min)
Applies a minimum size constraint to the element
The element size is set to at least the specified amount.
-- { Percentage(100), Min(20) }
-- ┌────────────────────────────┐┌──────────────────┐
-- │ 30 px ││ 20 px │
-- └────────────────────────────┘└──────────────────┘
-- { Percentage(100), Min(10) }
-- ┌──────────────────────────────────────┐┌────────┐
-- │ 40 px ││ 10 px │
-- └────────────────────────── ────────────┘└────────┘
Max(max)
Applies a maximum size constraint to the element
The element size is set to at most the specified amount.
-- { Percentage(0), Max(20) }
-- ┌────────────────────────────┐┌──────────────────┐
-- │ 30 px ││ 20 px │
-- └────────────────────────────┘└──────────────────┘
-- { Percentage(0), Max(10) }
-- ┌──────────────────────────────────────┐┌────────┐
-- │ 40 px ││ 10 px │
-- └──────────────────────────────────────┘└────────┘
Length(len)
Applies a length constraint to the element
The element size is set to the specified amount.
-- { Length(20), Length(20) }
-- ┌──────────────────┐┌──────────────────┐
-- │ 20 px ││ 20 px │
-- └──────────────────┘└──────────────────┘
-- { Length(20), Length(30) }
-- ┌──────────────────┐┌────────────────────────────┐
-- │ 20 px ││ 30 px │
-- └──────────────────┘└────────────────────────────┘
Percentage(p)
Applies a percentage of the available space to the element
Converts the given percentage to a floating-point value and multiplies that with area. This value is rounded back to a integer as part of the layout split calculation.
-- { Percentage(75), Fill(1) }
-- ┌────────────────────────────────────┐┌──────────┐
-- │ 38 px ││ 12 px │
-- └────────────────────────────────────┘└──────────┘
-- { Percentage(50), Fill(1) }
-- ┌───────────────────────┐┌───────────────────────┐
-- │ 25 px ││ 25 px │
-- └───────────────────────┘└───────────────────────┘
Ratio(num, den)
Applies a ratio of the available space to the element
Converts the given ratio to a floating-point value and multiplies that with area. This value is rounded back to a integer as part of the layout split calculation.
-- { Ratio(1, 2), Ratio(1, 2) }
-- ┌───────────────────────┐┌───────────────────────┐
-- │ 25 px ││ 25 px │
-- └───────────────────────┘└───────────────────────┘
-- { Ratio(1, 4), Ratio(1, 4), Ratio(1, 4), Ratio(1, 4) }
-- ┌───────────┐┌──────────┐┌───────────┐┌──────────┐
-- │ 13 px ││ 12 px ││ 13 px ││ 12 px │
-- └───────────┘└──────────┘└───────────┘└──────────┘
Fill(scale)
Applies the scaling factor proportional to all other Fill
elements
to fill excess space
The element will only expand or fill into excess available space, proportionally matching
other Fill
elements while satisfying all other constraints.
-- { Fill(1), Fill(2), Fill(3) }
-- ┌──────┐┌───────────────┐┌───────────────────────┐
-- │ 8 px ││ 17 px ││ 25 px │
-- └──────┘└───────────────┘└───────────────────────┘
-- { Fill(1), Percentage(50), Fill(1) }
-- ┌───────────┐┌───────────────────────┐┌──────────┐
-- │ 13 px ││ 25 px ││ 12 px │
-- └───────────┘└───────────────────────┘└──────────┘
See https://docs.rs/ratatui/latest/ratatui/layout/enum.Constraint.html for more information.
List
Create a List
that takes a table of ui.Text
:
ui.List { ui.Text("foo"), ui.Text("bar") }
For convenience, the following types are also supported:
-- Table of string
ui.List { "foo", "bar" }
-- Table of ui.Line
ui.List { ui.Line("foo"), ui.Line("bar") }
-- Table of ui.Span
ui.List { ui.Span("foo"), ui.Span("bar") }
-- Mixed table of string, ui.Line, ui.Span
ui.List { "foo", ui.Line("bar"), ui.Span("baz") }
Methods (return self
if not specified):
area(rect)
- accepts a Rect, changing the area of the text. If not specified, returns the current area.style(style)
- Set the style of the list, which accepts a Style
Bar
Create a bar:
ui.Bar(direction)
The first attribute denotes the direction of the bar and accepts the following constants:
ui.Bar.NONE
ui.Bar.TOP
ui.Bar.RIGHT
ui.Bar.BOTTOM
ui.Bar.LEFT
ui.Bar.ALL
Methods (return self
if not specified):
area(rect)
- accepts a Rect, changing the area of the bar. If not specified, returns the current area.symbol(symbol)
- accepts a string, specifying the symbol for the barstyle(style)
- accepts a Style, specifying the style of the bar
Border
Create a border:
ui.Border(position)
The first attribute denotes the position of the border and accepts the following constants:
ui.Border.NONE
ui.Border.TOP
ui.Border.RIGHT
ui.Border.BOTTOM
ui.Border.LEFT
ui.Border.ALL
Methods (return self
if not specified):
area(rect)
- accepts a Rect, changing the area of the border. If not specified, returns the current area.type(type)
- accepts a type, specifying the type of the border:ui.Border.PLAIN
ui.Border.ROUNDED
ui.Border.DOUBLE
ui.Border.THICK
ui.Border.QUADRANT_INSIDE
ui.Border.QUADRANT_OUTSIDE
style(style)
- accepts a Style, specifying the style of the border
Gauge
Create a gauge:
ui.Gauge()
Methods (return self
if not specified):
area(rect)
- accepts a Rect, changing the area of the gauge. If not specified, returns the current area.percent(percent)
- Set the percentage of the gaugeratio(ratio)
- Set the ratio of the gaugelabel(label)
- Set the label of the gaugestyle(style)
- Set the style of everything except the bar itself, which accepts a Stylegauge_style(style)
- Set the style of the bar, which accepts a Style
Clear
Clear the content of a specific area, which is a Rect. Place it followed by the component that you want to clear:
local components = {
ui.Text("..."):area(rect),
-- ...
ui.Clear(rect),
}
Methods (return self
if not specified):
area(rect)
- accepts a Rect, changing the area of the clear. If not specified, returns the current area.