yves-biener/zterm
1
0
Fork 0
Code Issues Pull Requests Actions Wiki Activity

update wiki structure with WIP documentation

Yves Biener
2025-02-22 10:55:46 +01:00
parent ab8798806e
commit 78fd7d8408
9 changed files with 159 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.helix/languages.toml Normal file

@@ -0,0 +1,6 @@
[[language]]
name = "markdown"
scope = "source.md"
file-types = ["markdown", "md"]
text-width = 100
soft-wrap.wrap-at-text-width = true

42
Built-in Layouts.-.md

@@ -1,42 +0,0 @@
`App.Layout` serve several different purposes. They provide one or multiple of the following features for contained elements (`Layout`'s and/or `Widget`'s):
- structuring
- decorating
The following Layouts are provided by `zterm`:
- `VContainer`
- `VStack`
- `HContainer`
- `HStack`
- `Padding`
- `Margin`
- `Framing`
# VContainer
Vertical container for sized elements.
# VStack
Vertical stacking of contained elements. Essentially a `VContainer` where every element has equivalent size.
# HContainer
Horizontal container for sized elements.
# HStack
Horizontal stacking of contained elements. Essentially a `HContainer` where every element has equivalent size.
# Padding
Provide absolute padding for the contained single element.
# Margin
Provide relative (percentual) margins for the contained single element.
# Framing
Provide a frame (stylable through configuration parameter) for the contained single element.

19
Built-in Widgets.-.md

@@ -1,19 +0,0 @@
`Widget`'s provide an isolated struct which provides the contents to display in the provided `Size` on the terminal. Each `Widget` can control how and when to update their displayed contents.
The following `Widget`'s are provided by `zterm`:
- `Text`
- `RawText`
- `Spacer`
# Text
Static display of provided `Cell` array, which allows for styling (e.g. coloring of text, decoration of text, etc.) of displayed contents.
# RawText
Pager `Widget` for the provided file. Mainly used for Debugging purposes.
# Spacer
Empty `Widget` that is supposed to remain empty and serve as a placeholder for corresponding areas of the terminal screen.

26
Design.md Normal file

@@ -0,0 +1,26 @@
## Design Goals
This project draws heavy inspiration from [clay](https://github.com/nicbarker/clay) in the way the layout is declared by the user. As terminal applications usually are rendered in [intermediate mode](https://en.wikipedia.org/wiki/Immediate_mode_(computer_graphics)), a render loop is also completed at the end of a single event loop. Such that every time an event happens a render call will usually be done as well. However this is not strickly necessary forced by *zterm* and can be separated to have a fixed rendering of every 16ms (i.e. for 60 fps), etc.
> [!NOTE]
> All examples are implemented as *intermediate mode* rendered applications.
There is only one generic `Container` which includes properties, child container and optionally an `Element`. In the end a `Container` describes a tree structure containing layout and content.
The library is designed to be very basic and *not to provide* any more complex elements such as input fields, drop-down menu's, buttons, etc. Some of them are either easy to implement yourself, specific for you needs or a too complex to be provided by the library effectively. For these use-cases there may be other libraries that build on top of this one to provide the complex elements as some sort of pre-built elements for you to use in your application (or you create them yourself).
> [!CAUTION]
> There are no built-in components to provide complex behavior.
There are only very few system events, that are used by the built-in containers and properties accordingly. For you own widgets (i.e. a collection of elements) you can extend the events to include your own events to communicate between elements, effect the control flow and the corresponding generated layouts and much more.
> [!TIPS]
> Keep the tagged type of each user event as small as possible. If you need access to bigger structs you can also aways use pointers.
This library also provides a rendering pipeline alongside the event loop implementation. Usually the event loop is waiting blocking and will only cause a re-draw (*intermediate mode*) after each event - some events usually don't cause a draw (i.e. `.init` or your own if you want them not to). Even though each frame is regenerated from scratch each render loop, the corresponding application is still pretty performant as the renderer uses a *double buffered* implementation to only apply the changes from each frame to the next to the screen.
This library is also designed to work accordingly in ssh hosted environments, such that an application created using this library can be accessed directly via ssh. This provides security through the ssh protocol and can defer the synchronization process, as users may access the same running instance. Which is the primary use-case for myself to create this library in the first place.
---
1. [clay - High performance UI layout library in C | Github](https://github.com/nicbarker/clay)
2. [clay layout library | YouTube](https://www.youtube.com/watch?v=DYWTw19_8r4)

13
Elements.md Normal file

@@ -0,0 +1,13 @@
## [TODO] Elements
The documentation may contain tips about how to implement corresponding event loops or how to design own `Element`s. And also on how to test accordingly and use the library itself for examples on how to design the test cases.
For most of the `Element`s a standalone implementation would not make a lot
of sense due to the complexity of the user application states. Therefore the
library should instead provide small examples to show how you can implement
such user fields yourself and connect them using your own event system loops to
communicate with other `Container`s and/or `Element`s.
### Scrollable
### Advanced usage

28
Examples.md Normal file

@@ -0,0 +1,28 @@
## Examples
You can build the every example through the example option. For example:
```sh
zig build --release=safe -Dexample=demo run
```
> [!NOTE]
> In debug build mode log messages will be written to stderr. You can pipe the output of stderr to a file when running in debug mode to not disturb the tui rendering. e.g. `zig build run 2> log`
For all available examples run `zig build --help`
> [!TIP]
> Every example application can be quit using `ctrl+c`.
The examples are structured in four categories:
- Overall examples:
i.e. Error handling, Demo application, ..
- Elements:
i.e. Button, Input, Scrollable, ..
- Layouts:
i.e. Vertical, Horizontal, Grid, Mixed, ..
- Styles:
i.e. Color palette, Text styles, ..
They serve to provide examples on how to use the library as well as showcase the capabilities of the library. For the implementation source files see [examples](https://gitea.yves-biener.de/yves-biener/zterm/src/branch/main/examples).

9
Home.md

@@ -1,7 +1,6 @@
Welcome to the Wiki Documentation for **zterm**. # Welcome to the Wiki Documentation for *zterm*
This wiki contains documentation about the built-in `App.Layout`'s and `App.Widget`'s and how to write own `Layout` and `Widget` types. This wiki contains documentation about the design goals, implementation details and the usage of the **zterm** library.
For example implementations see [examples](https://gitea.yves-biener.de/yves-biener/zterm/src/branch/main/examples). > [!NOTE]
> Use the link tree on the right to navigate to the sections that you are interested in. It is recommended to read the **Design** first to get a broughter understanding of the concept of the library before jumping into examples.
You can clone this repository and run `zig build --release=fast` to build the example applications in release mode and run them to test them out on your machine.

77
Roadmap.md Normal file

@@ -0,0 +1,77 @@
## Roadmap
The following list contains goals for certain features the library supports or is planned on supporting.
- [ ] Container rendering
- [x] Layout
- [x] direction
- [x] vertical
- [x] horizontal
- [x] padding
- [x] gap
- [x] Border
- [x] sides
- [x] corners
- [x] separators
- [x] Rectangle
- [x] min size
- [ ] User control
- [x] event loop handling
- [x] mouse support
- [x] user content
- [ ] Default `Element` implementations
- [ ] Scrollable
- [x] user input handling
- [x] vertical
- [x] horizontal
- [x] mouse input
- [ ] scroll bar(s) rendering
- [ ] vertical
- [ ] horizontal
- [ ] Content alignment (i.e. standard calculations done with the provided `Size`)
- [x] User input
- [x] single line
- [x] multi line
- [x] min size (provide size to use which would be a minimal size - as if the actual size is smaller then the `Container` will scroll and otherwise the contents expand to the available space instead?)
- [ ] image support through kitty protocol (**later**)
- [ ] Inline rendering (**later**)
- [ ] Examples
- [x] Layouts
- [x] vertical
- [x] horizontal
- [x] grid
- [x] mixed (some sort of form)
- [ ] Elements
- [x] Button
- [x] Text Input field
- [ ] Popup-menu
- [x] Scrollable Content (i.e. show long text of an except of something and other smaller `Container`)
- [x] min size
- [x] mouse scrolling aware of mouse position (i.e. through multiple different scrollable `Container`)
- [ ] Styles
- [ ] Text styles
- [ ] Colors
- [x] foreground
- [x] background
- [ ] underline
- [ ] Emphasis
- [x] none
- [x] bold
- [x] dim
- [x] italic
- [x] underline
- [x] blink
- [x] invert
- [x] hidden
- [x] strikethrough
- [ ] combinations
- [x] Color palette
- [x] Error Handling
- log and show error's without crashing the application
- [ ] Demo
- [x] use another tui application to launch and come back to (showcase the interrupt behavior)
- [x] Launch sub-applications (not inside of a `Container` but during the application workflow, like an editor)
- [ ] implement some functionality to have it be more like a working demo application
- [ ] Testability
- [ ] snapshot ability to safe current screen (from `Renderer`) to test against
- [ ] try to integrate them into the library itself such that they also serve as examples on how to test

5
Testing.md Normal file

@@ -0,0 +1,5 @@
## [TODO] Testing
Using a different testing renderer (in a corresponding namespace `zterm.testing`) renderes without flushing to the screen, but keeps the corresponding `zterm.Cell` slice for comparison. The main question would rather be how to provide the expected value for the `zterm.Cell` slice.
The test renderer shall be configured with a given size (as the corresponding terminal for the screen size will not be available). This serves two aspects: Firstly, `.resize` Event triggering and secondly, the rendering into a `zterm.Cell` slice with the provided size dimensions (for testing layout handling and rendering (i.e. of a scrollable element, etc.)).