doc: correct alert blocks

2025-10-26 21:43:44 +01:00
parent fc53243afd
commit 69604fb60e
6 changed files with 13 additions and 10 deletions

@@ -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.
> [!NOTE]
> [!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. [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).
> [!CAUTION]
> [!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.
> [!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.
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.

@@ -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).
### 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`.
> [!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).
> [!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*.

@@ -6,7 +6,7 @@ You can build the every example through the example option. For example:
zig build --release=safe -Dexample=demo run
```
> [!TIP]
> [!tip]
> 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.
@@ -15,7 +15,7 @@ You can also build all examples by providing no argument for the example option,
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`
For all available examples run `zig build --help`

@@ -2,5 +2,5 @@
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.

@@ -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)
- 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*)
- [ ] Container rendering
- [x] Layout

@@ -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.
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: