TUI-1

[linrongbin16]

This doc describes basic architecture of rsvim, that support it runs as a TUI application.

Device

rsvim uses crossterm as its driver to handle keyboards input and mouse clicks/drags from hardware devices, and also the text-based rendering to the terminal application, e.g. kitty/wezterm/alacritty/MacOS iTerm2/Windows Terminal/etc.

Technically we can also use ncurses or other implementations, it provides the very fundamental layer of TUI event loop:

 -------------------
|   keyboard/mouse  |
|       input       |
 -------------------
         ↓
 -------------------
|   editing logic   |
|        or         |  ----------
|  use `:q` to quit |→|   exit   |
 -------------------   ----------
         ↓
 -------------------
|  terminal output  |
 -------------------

This is the device layer.

UI

The UI terminology here is more close to the concept that been used in most GUI frameworks and even Web UI frameworks/libraries. For example QT6, tkinker, and react.js.

People would say: Vim/Neovim is only a TUI app that editing a file, with some statusline, sign column, split windows. Why talking about GUI framework here? - Yes, and No.

Vim/Neovim is definitely not only some simple window/buffer layout today, it try to extend to much more complicated UI components, we need to consider it seriously by introducing hard-core GUI framework design & concept, to help build better TUI. In this section, we will introduce a stack-based UI components tree, it helps reduce the maintain and logic burden for higher-level logic development.

While on another hand, Vim/Neovim is much simpler than QT and react, so we only need part of them.

The stack-based components tree is the classic design been widely used by many GUI frameworks/libraries. For example we have a TUI below:

     --------------
     |            |
--------------------------------
| A  |    B       |            |
|    |            |            |
|    --------------            |
|                              |
|  ------------------          |
|  |                |          |
|  | C              |          |
|  |     ---------------       |
|  |     |     ------  |       |
|  |     |  D  | E  |  |       |
|  ------|     |    |  |       |
|        |     ------  |       |
|        ---------------       |
--------------------------------

A is the root component of the tree, we would think it as the terminal we are working on. It has 3 child components: B, C and D.

Parts of B is outside of A, so we actually only see half of it.

Parts of C is covered by D, and D has a child component: E, inside of it.

Once there are keyboard/mouse events, this UI layer will calculates the positions, and tell us where does the device events happen: is mouse click on A or E? is keyboard editing something in C or D? This includes the graphic layout, border, overlap and top/bottom detection.

Each component will have a binded callback on them when created, and been triggered once there are device events happened on them. The components on top (e.g. E is on top of D, D is on top of C) will have higher priority to consume the device events. If there's an input event that a component cannot handle, the component will ask its parent component to handle the event.

On this basis, the window, statusline, sign column, float window are all specialized Vim UI components.

This is the UI layer.

Rendering

The Device and UI sections are about only inputs, this section we will discuss the output, e.g. the rendering.

After running the binded callbacks on each UI component, they will either:

• Change the text content inside them.
• Change the child components inside them: create new child, destroy old child, change child layout, etc.

Every component from top to buttom can do these changes, but finally these logic changes will be merged into the text changes in plane 2D, and finally flushed to the device, this is the rendering process.

References

• Qt 6.7.1 - Qt Core Documents

[linrongbin16]

RFC is moved to https://github.com/rsvim/rfc, this discussion is closed.