diff --git a/docs/dds.md b/docs/dds.md index 40f9b0c7..4c359aee 100644 --- a/docs/dds.md +++ b/docs/dds.md @@ -8,12 +8,6 @@ import TabItem from '@theme/TabItem'; # DDS -:::warning -This is a new feature that will be released in Yazi 0.2.5 and currently requires the latest code. - -Document is still being written... -::: - DDS (Data Distribution Service) is designed to achieve communication and state synchronization between multiple Yazi instances, as well as state persistence. It is built on a client-server architecture but does not require running additional server processes. It deeply integrates with a publish-subscribe model based on the Lua API. diff --git a/docs/plugins/layout.md b/docs/plugins/layout.md index ff1b8b7a..d256598a 100644 --- a/docs/plugins/layout.md +++ b/docs/plugins/layout.md @@ -3,82 +3,244 @@ sidebar_position: 2 description: Learn how to use Yazi's Lua API. --- +:::warning +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 -Paragraph, List, Bar, Border, and Gauge are renderable widgets; others need to be placed within any of them. +Text, List, Bar, Border, and Gauge are renderable elements; others need to be placed within any of them. -## Bar {#bar} +## Rect {#rect} -Create a bar: +A Rect is represented an area within the terminal by four attributes: ```lua -ui.Bar(rect, direction) +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 }` ``` -The first attribute is a [Rect](#rect), representing the position of this bar. -The second denotes the direction of the bar and accepts the following constants: +Properties: -- `ui.Bar.NONE` -- `ui.Bar.TOP` -- `ui.Bar.RIGHT` -- `ui.Bar.BOTTOM` -- `ui.Bar.LEFT` -- `ui.Bar.ALL` +- `x` - x position +- `y` - y position +- `w` - width +- `h` - height +- `left` - left position +- `right` - right position +- `top` - top position +- `bottom` - bottom position Methods (return `self` if not specified): -- `area(rect)` - accepts a [Rect](#rect), changing the area of the bar. If not specified, returns the current area. (Nightly version required for now) -- `symbol(symbol)` - accepts a string, specifying the symbol for the bar -- `style(style)` - accepts a [Style](#style), specifying the style of the bar +- `padding(padding)` - Set padding, accepts a [Padding](#padding) -## Border {#border} +You can get a pre-computed `Rect` through [`ui.Layout()`](#layout). +Note that if you intend to create a `Rect` yourself, ensure these values are calculated accurately; otherwise, it may cause Yazi to crash! -Create a border: +## Padding {#padding} + +All parameters for padding are integers: ```lua -ui.Border(rect, position) +ui.Padding(left, right, top, bottom) ``` -The first attribute is a [Rect](#rect), representing the position of this border. -The second denotes the position of the border and accepts the following constants: +Properties: -- `ui.Border.NONE` -- `ui.Border.TOP` -- `ui.Border.RIGHT` -- `ui.Border.BOTTOM` -- `ui.Border.LEFT` -- `ui.Border.ALL` +- `left` - left padding +- `right` - right padding +- `top` - top padding +- `bottom` - bottom padding + +If you want to specify only one of them, you can: + +- `ui.Padding.left(left)` equal to `ui.Padding(left, 0, 0, 0)` +- `ui.Padding.right(right)` equal to `ui.Padding(0, right, 0, 0)` +- `ui.Padding.top(top)` equal to `ui.Padding(0, 0, top, 0)` +- `ui.Padding.bottom(bottom)` equal to `ui.Padding(0, 0, 0, bottom)` -You can also use `ui.Border:type(type)` to specify different types for the border. It accepts the following type constants: +Or specify a particular direction for them: + +- `ui.Padding.x(x)` equal to `ui.Padding(x, x, 0, 0)` +- `ui.Padding.y(y)` equal to `ui.Padding(0, 0, y, y)` +- `ui.Padding.xy(x, y)` equal to `ui.Padding(x, x, y, y)` -- `ui.Border.PLAIN` -- `ui.Border.ROUNDED` -- `ui.Border.DOUBLE` -- `ui.Border.THICK` -- `ui.Border.QUADRANT_INSIDE` -- `ui.Border.QUADRANT_OUTSIDE` +## Style {#style} + +Create a style: + +```lua +ui.Style() +``` Methods (return `self` if not specified): -- `area(rect)` - accepts a [Rect](#rect), changing the area of the border. If not specified, returns the current area. (Nightly version required for now) -- `style(style)` - accepts a [Style](#style), specifying the style of the border +- `fg(color)` - Set the foreground color of the style, which accepts a [Color](/docs/configuration/theme#types.color) +- `bg(color)` - Set the background color of the style, which accepts a [Color](/docs/configuration/theme#types.color) +- `bold()` - Set the style to bold +- `dim()` - Set the style to dim +- `italic()` - Set the style to italic +- `underline()` - Set the style to underline +- `blink()` - Set the style to blink +- `blink_rapid()` - Set the style to blink rapidly +- `reverse()` - Set the style to reverse +- `hidden()` - Set the style to hidden +- `crossed()` - Set the style to crossed +- `reset()` - Reset the style +- `patch(style)` - Patch the style with another `Style` -## Clear {#clear} +## Span {#span} -Clear the content of a specific area, which is a [Rect](#rect). Place it followed by the component that you want to clear: +`ui.Span` is the smallest unit of text, yet a component of `ui.Line`. Create a span: ```lua -local components = { - ui.Paragraph(rect, {}), - -- ... +ui.Span("foo") +``` - ui.Clear(rect), -} +For convenience, `ui.Span` can also accept itself as a argument: + +```lua +ui.Span(ui.Span("bar")) ``` Methods (return `self` if not specified): -- `area(rect)` - accepts a [Rect](#rect), changing the area of the clear. If not specified, returns the current area. (Nightly version required for now) +- `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](#style) + +Besides applying the whole [`Style`](#style), you can also call those methods of `Style` directly on it, which means: + +```lua +local style = ui.Style():fg("white"):bg("black"):bold() +ui.Span("Hello world"):style(style) +``` + +can be also written as: + +```lua +ui.Span("Hello world"):fg("white"):bg("black"):bold() +``` + +## Line {#line} + +`ui.Line` represents a line, consisting of multiple `ui.Span`s, and it accepts a table of them: + +```lua +ui.Line { ui.Span("foo"), ui.Span("bar") } +``` + +For convenience, the following types are also supported: + +```lua +-- 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](#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](#style). + +Like with [`Span`](#span), you can directly call [`Style`](#style) methods on it + +```lua +ui.Line("Hello world"):fg("white"):bg("black"):bold() +``` + +## Text {#text} + +`ui.Text` is used to represent multi-line text, it takes a table of `ui.Line`: + +```lua +ui.Text { ui.Line("foo"), ui.Line("bar") } +``` + +For convenience, the following types are also supported: + +```lua +-- 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](https://en.wikipedia.org/wiki/ANSI_escape_code) string into a text. + +Methods (return `self` if not specified): + +- `area(rect)` - accepts a [Rect](#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 wrap + - `ui.Text.WRAP` - Wrap at the end of the line + - `ui.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 integer +- `style(style)` - Set the style of the text, which accepts a [Style](#style) + +Like with [`Span`](#span), you can directly call [`Style`](#style) methods on it: + +```lua +ui.Text("Hello world"):fg("white"):bg("black"):bold() +``` + +## Layout {#layout} + +Create a layout: + +```lua +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](#constraint). +- `split(rect)` - Accepts a [Rect](#rect) and split it into multiple [Rect](#rect) according to the constraints. ## Constraint {#constraint} @@ -216,243 +378,117 @@ other `Fill` elements while satisfying all other constraints. See https://docs.rs/ratatui/latest/ratatui/layout/enum.Constraint.html for more information. -## Gauge {#gauge} +## List {#list} -Create a gauge: +Create a `List` that takes a table of `ui.Text`: ```lua -ui.Gauge(rect) +ui.List { ui.Text("foo"), ui.Text("bar") } ``` -Methods (return `self` if not specified): - -- `area(rect)` - accepts a [Rect](#rect), changing the area of the gauge. If not specified, returns the current area. (Nightly version required for now) -- `percent(percent)` - Set the percentage of the gauge -- `ratio(ratio)` - Set the ratio of the gauge -- `label(label)` - Set the label of the gauge -- `style(style)` - Set the style of everything except the bar itself, which accepts a [Style](#style) -- `gauge_style(style)` - Set the style of the bar, which accepts a [Style](#style) - -## Layout {#layout} - -Create a layout: +For convenience, the following types are also supported: ```lua -local areas = ui.Layout() - :direction(ui.Layout.HORIZONTAL) - :constraints({ ui.Constraint.Percentage(50), ui.Constraint.Percentage(50) }) - :split(area) +-- Table of string +ui.List { "foo", "bar" } -local left = areas[1] -- The first rect -local right = areas[2] -- The second rect -``` +-- Table of ui.Line +ui.List { ui.Line("foo"), ui.Line("bar") } -Methods (return `self` if not specified): +-- Table of ui.Span +ui.List { ui.Span("foo"), ui.Span("bar") } -- `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](#constraint). -- `split(rect)` - Accepts a [Rect](#rect) and split it into multiple [Rect](#rect) according to the constraints. - -## Line {#line} - -Create a line, which accepts a string, or a list of [Span](#span) and [Line](#line): - -```lua -ui.Line("string") -ui.Line { span, line, span, ... } +-- 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](#rect), changing the area of the line. If not specified, returns the current area. (Nightly version required for now) -- `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. Nightly version required for now. -- `style(style)` - Set the style of the line, which accepts a [Style](#style). - -Like with [`Span`](#span), you can directly call [`Style`](#style) methods on it (Nightly version required for now): - -```lua -ui.Line("Hello world"):fg("white"):bg("black"):bold() -``` - -## List {#list} - -Create a list: - -```lua -ui.List(rect, items) -``` - -The first attribute is a [Rect](#rect), representing the position of this list. -The second denotes the items of the list and accepts a list of [ListItem](#list-item). - -Methods (return `self` if not specified): - +- `area(rect)` - accepts a [Rect](#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](#style) -## ListItem {#list-item} - -Create a list item: - -```lua -ui.ListItem(line) -ui.ListItem(span) -ui.ListItem("string") -``` - -Methods (return `self` if not specified): - -- `style(style)` - Set the style of the list item, which accepts a [Style](#style) - -## Padding {#padding} - -All parameters for padding are integers: - -```lua -ui.Padding(left, right, top, bottom) -``` - -Properties: - -- `left` - left padding -- `right` - right padding -- `top` - top padding -- `bottom` - bottom padding - -If you want to specify only one of them, you can: - -- `ui.Padding.left(left)` equal to `ui.Padding(left, 0, 0, 0)` -- `ui.Padding.right(right)` equal to `ui.Padding(0, right, 0, 0)` -- `ui.Padding.top(top)` equal to `ui.Padding(0, 0, top, 0)` -- `ui.Padding.bottom(bottom)` equal to `ui.Padding(0, 0, 0, bottom)` - -Or specify a particular direction for them: - -- `ui.Padding.x(x)` equal to `ui.Padding(x, x, 0, 0)` -- `ui.Padding.y(y)` equal to `ui.Padding(0, 0, y, y)` -- `ui.Padding.xy(x, y)` equal to `ui.Padding(x, x, y, y)` - -## Paragraph {#paragraph} +## Bar {#bar} -Create a paragraph: +Create a bar: ```lua -ui.Paragraph(rect, { line, line, ... }) +ui.Bar(direction) ``` -The first attribute is a [Rect](#rect), representing the position of this paragraph. -The second denotes the lines of the paragraph and accepts a list of [Line](#line). +The first attribute denotes the direction of the bar and accepts the following constants: -You can also use `ui.Paragraph.parse(string)` to parse an [ANSI escape sequence](https://en.wikipedia.org/wiki/ANSI_escape_code) string into a paragraph. +- `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](#rect), changing the area of the paragraph. If not specified, returns the current area. (Nightly version required for now) -- `align(alignment)` - Set the alignment of the paragraph. It accepts the following constants: - - `ui.Paragraph.LEFT` - - `ui.Paragraph.CENTER` - - `ui.Paragraph.RIGHT` -- `wrap(wrap)` - Set the wrap of the paragraph, which accepts the following constants: - - `ui.Paragraph.WRAP_NO` - No wrap - - `ui.Paragraph.WRAP` - Wrap at the end of the line - - `ui.Paragraph.WRAP_TRIM` - Wrap at the end of the line, and trim the leading whitespace -- `max_width()` - Get the maximum width of the paragraph, which returns an integer (Nightly version required for now). -- `style(style)` - Set the style of the paragraph, which accepts a [Style](#style) - -Like with [`Span`](#span), you can directly call [`Style`](#style) methods on it (Nightly version required for now): - -```lua -ui.Paragraph("Hello world"):fg("white"):bg("black"):bold() -``` +- `area(rect)` - accepts a [Rect](#rect), changing the area of the bar. If not specified, returns the current area. +- `symbol(symbol)` - accepts a string, specifying the symbol for the bar +- `style(style)` - accepts a [Style](#style), specifying the style of the bar -## Rect {#rect} +## Border {#border} -A Rect is represented an area within the terminal by four attributes: +Create a border: ```lua -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 }` +ui.Border(position) ``` -Properties: +The first attribute denotes the position of the border and accepts the following constants: -- `x` - x position -- `y` - y position -- `w` - width -- `h` - height -- `left` - left position -- `right` - right position -- `top` - top position -- `bottom` - bottom position +- `ui.Border.NONE` +- `ui.Border.TOP` +- `ui.Border.RIGHT` +- `ui.Border.BOTTOM` +- `ui.Border.LEFT` +- `ui.Border.ALL` Methods (return `self` if not specified): -- `padding(padding)` - Set padding. It accepts a [Padding](#padding) - -You can obtain a pre-computed `Rect` through [`ui.Layout()`](#layout). -Note that if you intend to create a `Rect` yourself, ensure these values are calculated accurately; otherwise, it may cause Yazi to crash! +- `area(rect)` - accepts a [Rect](#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](#style), specifying the style of the border -## Span {#span} +## Gauge {#gauge} -Create a span: +Create a gauge: ```lua -ui.Span("string") +ui.Gauge() ``` Methods (return `self` if not specified): -- `visible()` - Whether the span is visible (includes any printable characters), which returns a boolean. Nightly version required for now. -- `style(style)` - Set the style of the span, which accepts a [Style](#style) - -Besides applying the whole [`Style`](#style), you can also call those methods of `Style` directly on it, which means: +- `area(rect)` - accepts a [Rect](#rect), changing the area of the gauge. If not specified, returns the current area. +- `percent(percent)` - Set the percentage of the gauge +- `ratio(ratio)` - Set the ratio of the gauge +- `label(label)` - Set the label of the gauge +- `style(style)` - Set the style of everything except the bar itself, which accepts a [Style](#style) +- `gauge_style(style)` - Set the style of the bar, which accepts a [Style](#style) -```lua -local style = ui.Style():fg("white"):bg("black"):bold() -ui.Span("Hello world"):style(style) -``` +## Clear {#clear} -can be also written as (Nightly version required for now): +Clear the content of a specific area, which is a [Rect](#rect). Place it followed by the component that you want to clear: ```lua -ui.Span("Hello world"):fg("white"):bg("black"):bold() -``` - -## Style {#style} - -Create a style: +local components = { + ui.Text("..."):area(rect), + -- ... -```lua -ui.Style() + ui.Clear(rect), +} ``` Methods (return `self` if not specified): -- `fg(color)` - Set the foreground color of the style, which accepts a [Color](/docs/configuration/theme#types.color) -- `bg(color)` - Set the background color of the style, which accepts a [Color](/docs/configuration/theme#types.color) -- `bold()` - Set the style to bold -- `dim()` - Set the style to dim -- `italic()` - Set the style to italic -- `underline()` - Set the style to underline -- `blink()` - Set the style to blink -- `blink_rapid()` - Set the style to blink rapidly -- `reverse()` - Set the style to reverse -- `hidden()` - Set the style to hidden -- `crossed()` - Set the style to crossed -- `reset()` - Reset the style -- `patch(style)` - Patch the style with another `Style` +- `area(rect)` - accepts a [Rect](#rect), changing the area of the clear. If not specified, returns the current area. diff --git a/docs/plugins/types.md b/docs/plugins/types.md index 7e1ec1fb..6a39a490 100644 --- a/docs/plugins/types.md +++ b/docs/plugins/types.md @@ -80,7 +80,7 @@ Methods: - `name()` - Returns the filename in string if any, otherwise `nil` - `stem()` - Returns the filename without the extension in string if any, otherwise `nil` - `join(url)` - Joins with another `Url` or a string of url, returns a new `Url` -- `parent()` - Returns parent directory in string if any, otherwise `nil` +- `parent()` - Returns parent directory `Url` if any, otherwise `nil` - `starts_with(url)` - Whether the url starts with another `Url` or a string of url - `ends_with(url)` - Whether the url ends with another `Url` or a string of url - `strip_prefix(url)` - Strips the prefix of another `Url` or a string of url, returns a new `Url` diff --git a/docs/plugins/utils.md b/docs/plugins/utils.md index 3ca25535..1121a8df 100644 --- a/docs/plugins/utils.md +++ b/docs/plugins/utils.md @@ -218,7 +218,7 @@ This function is only available in the async context. - `file` - The previewed [File](/docs/plugins/types#shared.file) - `skip` - The number of units to skip. It's units largely depend on your previewer, such as lines for code, and percentages for videos - `window` - The [Window](/docs/plugins/types#shared.window) of the preview -- `widgets` - List of renderable widgets, such as `{ ui.Paragraph {...}, ui.List {...}, ... }` +- `widgets` - List of renderable widgets, such as `{ ui.Text {...}, ui.List {...}, ... }` This function is only available in the async context.