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

doc: correct alert blocks

Yves Biener
2025-10-26 21:43:44 +01:00
parent fc53243afd
commit 69604fb60e
6 changed files with 13 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
Design.md

@@ -2,19 +2,19 @@
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. 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] > [!note]
> All examples are implemented as *intermediate mode* rendered applications. > 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. [Elements](Elements.md) describe user defined content and behavior building on top of the existing `Container` layouting. 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. [Elements](Elements.md) describe user defined content and behavior building on top of the existing `Container` layouting.
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). 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] > [!caution]
> There are no built-in components to provide complex behavior. > 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. 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.
> [!TIP] > [!tip]
> Keep the tagged type of each user event as small as possible. If you need access to bigger structs you can also always use pointers. > Keep the tagged type of each user event as small as possible. If you need access to bigger structs you can also always 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 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.

6
Elements.md

@@ -67,7 +67,7 @@ pub fn Template(Model: type, Event: type) type {
} }
``` ```
> [!TIP] > [!tip]
> For example implementations of `Element` types, please refer to [examples](Examples.md). > For example implementations of `Element` types, please refer to [examples](Examples.md).
### Tips ### Tips
@@ -95,8 +95,8 @@ State using the first idea should be keept at a minimum and used if they are spe
State that shall be shared between other `Element`s in your application should propagate their state to the `Model`. State that shall be shared between other `Element`s in your application should propagate their state to the `Model`.
> [!WARN] > [!warning]
> However keep in might that this might cause side-effects (i.e. having the same `Element` implementation instanciated multiple times in the same `Container` tree, might cause the `handle` callback to be called multiple times in a single event loop iteration). > However keep in might that this might cause side-effects (i.e. having the same `Element` implementation instanciated multiple times in the same `Container` tree, might cause the `handle` callback to be called multiple times in a single event loop iteration).
> [!INFO] > [!note]
> This exact seperatation is also used in android app development using [Jetpack compose](https://developer.android.com/compose). Common patterns, best practices, etc. may also apply for *zterm*. > This exact seperatation is also used in android app development using [Jetpack compose](https://developer.android.com/compose). Common patterns, best practices, etc. may also apply for *zterm*.

4
Examples.md

@@ -6,7 +6,7 @@ You can build the every example through the example option. For example:
zig build --release=safe -Dexample=demo run zig build --release=safe -Dexample=demo run
``` ```
> [!TIP] > [!tip]
> Every example application can be quit using `ctrl+c`. > Every example application can be quit using `ctrl+c`.
You can also build all examples by providing no argument for the example option, as the default builds all examples. You can also build all examples by providing no argument for the example option, as the default builds all examples.
@@ -15,7 +15,7 @@ You can also build all examples by providing no argument for the example option,
zig build zig build
``` ```
> [!NOTE] > [!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-out/bin/demo run 2> log` > 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-out/bin/demo run 2> log`
For all available examples run `zig build --help` For all available examples run `zig build --help`

2
Home.md

@@ -2,5 +2,5 @@
This wiki contains documentation about the design goals, implementation details and the usage of the **zterm** library. This wiki contains documentation about the design goals, implementation details and the usage of the **zterm** library.
> [!NOTE] > [!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. > 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.

3
Roadmap.md

@@ -17,6 +17,9 @@ The following list contains goals for certain features the library supports or i
- Limit where Focus is actually necessary (and skip those accordingly) - Limit where Focus is actually necessary (and skip those accordingly)
- Enhance the rendering to make it obvious where the focus is currently at - Enhance the rendering to make it obvious where the focus is currently at
- [ ] Enhance performance through multi-threading?
- synchronization might be a bottleneck, but maybe interesting for bigger applications? would require some tests
- [x] Elm architecture support (through user defined `struct` acting as the *Model*) - [x] Elm architecture support (through user defined `struct` acting as the *Model*)
- [ ] Container rendering - [ ] Container rendering
- [x] Layout - [x] Layout

2
Testing.md

@@ -88,7 +88,7 @@ pub fn expectContainerScreen(size: Size, container: *Container(event.SystemEvent
} }
``` ```
> [!TIP] > [!tip]
> Create several *checkpoint screens* that should be tested against when testing for user interaction. > Create several *checkpoint screens* that should be tested against when testing for user interaction.
For testing user interaction you need to provide the container with the corresponding *events* it should receive. This includes user key presses, mouse presses (with their corresponding location on the screen), etc. For example see the test for `Scrollable` elements, which create the scrollable `Container` renders it and tests the screen, then scrolls down, re-renders the `Container` to test and finally tries to scroll further down to test for scrolling down after reaching the end of the `Scrollable` element: For testing user interaction you need to provide the container with the corresponding *events* it should receive. This includes user key presses, mouse presses (with their corresponding location on the screen), etc. For example see the test for `Scrollable` elements, which create the scrollable `Container` renders it and tests the screen, then scrolls down, re-renders the `Container` to test and finally tries to scroll further down to test for scrolling down after reaching the end of the `Scrollable` element: