From 140f27216a18c3811fabb1b19c2237037e94da93 Mon Sep 17 00:00:00 2001 From: Yves Biener Date: Sat, 22 Feb 2025 11:00:38 +0100 Subject: [PATCH] doc: move contents from README to wiki --- README.md | 202 +----------------------------------------------------- 1 file changed, 1 insertion(+), 201 deletions(-) diff --git a/README.md b/README.md index 7c4302b..8e6e844 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ To add or update `zterm` as a dependency in your project run the following comma zig fetch --save git+https://gitea.yves-biener.de/yves-biener/zterm ``` -Add the dependency to your module as follows in your _build.zig_: +Add the dependency to your module as follows in your *build.zig*: ```zig const zterm: *Dependency = b.dependency("zterm", .{ @@ -37,179 +37,6 @@ const zterm: *Dependency = b.dependency("zterm", .{ exe.root_module.addImport("zterm", zterm.module("zterm")); ``` -## 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, -the rendering is also part of the event loop. Such that every time an event -happens a render call will usually be done as well. However this is not strickly -necessary and can be separated to have a fixed rendering of every 16ms (i.e. for -60 fps), etc. - -There is only one generic container which contains properties and elements (or -children) which can also be containers, such that each layout in the end is -a tree. - -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). - -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. - -As this is a terminal based layout library it 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. -Even though the each frame is regenerated from scratch each render loop, the -corresponding application is still pretty performant as the renderer uses a -double buffered intermediate mode implementation to only apply the changes from -each frame to the next to the terminal. - -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. - -## Roadmap - -- [ ] 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 - -Decorations should respect the layout and the viewport accordingly. This means -that scrollbars are always visible (except there is no need to have a scrollbar) -irrelevant depending on the size of the content. The rectangle apply to all -cells of the content (and may be overwritten by child elements contents). -The border of an element should be around independent of the scrolling of the -contents, just like padding. - -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 contents - -Contents that is scrollable should be done *virtually* through the contents of -the `Container`. This means each container contents implements scrolling for -itself if required. - -This still has one issue: Layout of child elements that are already too large -(i.e. or become too small). The library could provide automatic rendering of a -scrollbar given the right parameters however. The scrolling input action would -then also be implemented by the user. - -Open questions are regarding the sizing options (i.e. how is the size of a -`Container` actually controlled?, how should it be controlled?, etc.). There -should be support for the child elements to provide some kind of 'list' -functionality built-in. - -**REMINDER**: (mostly for myself) The library should be and remain simple. This -means that some code for using the library may be duplicated, but this is not -the main goal. Others may provide more re-usable code snippets that build on top -of this library instead. - -### User specific event handling and content rendering - -For interactions controlled by the user each container can use an `Element` -interface which contains functions which are called by the `Container` -during event handling (i.e. `fn handle(..)`) and during rendering (i.e. `fn -content(..)`) to provide user specific content and user interaction. The -`Element` may be stateful, but may also be stateless and then be re-used in -multiple different `Container`s. - -Composing multiple `Element`s currently requires the implementation of a wrapper -which contains the `Element`s that need to be handled (should work pretty well -for stateless `Element`s). Such *stateless* `Element`s may be provided by this -library. - -### Input - -How is the user input handled in the containers? Should there be active -containers? Some input may happen for a specific container (i.e. when using -mouse input). How would I handle scrolling for outer and inner elements of -a container? - ### Documentation A wiki should be created containing a bright overview of the structure and usage @@ -217,30 +44,3 @@ of the library. For details it should refer to the examples. The documentation should be minimal in terms of updateability in case the library changes. Maybe some documentation could be derived from the code documentation (there is a tool for this if I recall correctly). - -Afterwards this README file contents can be updated to provide an actual -overview of the library in a short form containing links to the detailed -information required for usage. - -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. - -### Archive - -The alignment and sizing options only make sense if both are available. For -this the current implementation has the viewport size and the content size too -linked. Therefore they have both been removed (at least for now): - - - *fit*: adjust virtual space of container by the size of its children (i.e. a - container needs to be able to get the necessary size of its children) - - *grow*: use as much space as available (what exactly would be the difference - between this option and *fit*?) - - *fixed*: use exactly as much cells (in the specified direction) - - - *center*: elements should have their anchor be placed accordingly to their - size and the viewport size. - - *left*: the anchor remains at zero (relative to the location of the - container on the screen) -> similar to the current implementation! - - *right*: the anchor is fixed to the right side (i.e. size of the contents - - size of the viewport)