diff --git a/Design.md b/Design.md index 2e46a07..0cd6c7c 100644 --- a/Design.md +++ b/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. -> [!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. diff --git a/Elements.md b/Elements.md index 2237f58..a4a0b1c 100644 --- a/Elements.md +++ b/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). ### 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*. diff --git a/Examples.md b/Examples.md index a55f6b7..79cebe4 100644 --- a/Examples.md +++ b/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 ``` -> [!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` diff --git a/Home.md b/Home.md index 24646d7..0ff5796 100644 --- a/Home.md +++ b/Home.md @@ -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. diff --git a/Roadmap.md b/Roadmap.md index 5148d72..1d4b995 100644 --- a/Roadmap.md +++ b/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) - 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 diff --git a/Testing.md b/Testing.md index dcf8b6f..7518179 100644 --- a/Testing.md +++ b/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. 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: