[Renderers/Ncurses] Add Ncurses example and renderer#569
Open
Seintian wants to merge 9 commits intonicbarker:mainfrom
Open
[Renderers/Ncurses] Add Ncurses example and renderer#569Seintian wants to merge 9 commits intonicbarker:mainfrom
Seintian wants to merge 9 commits intonicbarker:mainfrom
Conversation
- **Renderer**: Implemented `clay_renderer_ncurses.c` supporting rectangles, text, borders, and clipping using standard ncurses plotting. - **Example**: Added `examples/ncurses-example` demonstrating a scrollable "Social Feed" UI with keyboard navigation. - **Build**: Added `CLAY_INCLUDE_NCURSES_EXAMPLES` option to root `CMakeLists.txt` and integrated the new example. - **CompConfig**: Updated `.gitignore` to strictly exclude `build/`, `_deps/`, and other standard CMake artifacts.
…mprovements
Significantly enhances the Ncurses renderer capabilities and updates the example application.
Renderer Changes:
- Unicode Support:
- Implemented automatic UTF-8 locale detection and initialization.
- Switched to wide-character handling (`wchar_t`, `mvaddnwstr`) for correct rendering of multi-byte characters (e.g., Emojis).
- Used `wcwidth` for accurate string width measurement.
- Color Support:
- Upgraded from 3-bit (8 colors) to 256-color support (xterm-256color).
- Added `Clay_Ncurses_MatchColor` to map arbitrary RGB values to the nearest color in the standard 6x6x6 color cube.
- Added capability detection to fallback gracefully on simpler terminals.
- Visual Fidelity:
- Implemented background color inheritance (`Clay_Ncurses_GetBackgroundAt`) to simulate transparency.
- Text and borders now render on top of existing background colors instead of resetting to the terminal default.
- Build & POSIX:
- Added `_XOPEN_SOURCE_EXTENDED` and `_XOPEN_SOURCE=700` definitions for standard compliance.
Example Application (clay-ncurses-example):
- Theme:
- Updated to a modern dark theme (Uniform `{20, 20, 20}` background).
- Switched to saturated/bright foreground colors for better contrast.
- Fixes:
- Replaced obsolete `usleep` with POSIX-compliant `nanosleep`.
- Build:
- Updated CMakeLists.txt to enforce linking against `ncursesw` (wide version).
Verified with `clay-ncurses-example` on Linux (xterm-256color).
…corners
Significantly improves the stability, performance, and visual quality of the ncurses renderer.
**Renderer Improvements (`clay_renderer_ncurses.c`):**
* **Flicker Reduction**:
* Removed `erase()` call at the start of the frame to enable differential rendering.
* Implemented "Dirty Check" optimizations for Rectangles, Borders, and Text. The renderer now reads the existing screen content (using `mvinch`, `mvin_wch`, `mvin_wchnstr`) and only issues draw commands if the content or color differs.
* Hardened Rectangle dirty check to mask out volatile attributes (comparing only `A_CHARTEXT | A_COLOR`), preventing false-positive redraws caused by internal terminal flags.
* **Memory Safety**:
* Fixed internal ncurses memory leaks by calling `delscreen(set_term(NULL))` in `Clay_Ncurses_Terminate` to properly free the default screen wrapper.
* **Visual Features**:
* Added support for **Rounded Corners**: Borders with `cornerRadius > 0` now render using Unicode arc characters (`╭`, `╮`, `╯`, `╰`).
* Upgraded standard borders to use full Unicode box-drawing characters.
**Example Application Updates (`ncurses-example/main.c`):**
* **Layout Stability**:
* Refactored all layout dimensions and gaps to use `CLAY_NCURSES_CELL_WIDTH` (8) and `CLAY_NCURSES_CELL_HEIGHT` (16) macros, ensuring strict grid alignment.
* Fixed vertical jitter in "Profile Icon" and text headers by enforcing exact height multiples and top-alignment, eliminating sub-pixel rounding errors during scroll.
* **New UI Elements**:
* Added a **Floating Help Modal** (toggled via 'H') to demonstrate Z-ordering and localized input handling.
* Added "Server Status" progress bars to the Sidebar to demonstrate percent-based sizing and colored rectangles.
* Added "Mixed Border" examples to the Sidebar to showcase the new rounded corner capabilities.
* Added "Black" background constant usage for cleaner code.
… functions and Doxygen docs
Major refactor of the Ncurses renderer and example application to improve code readability, maintainability, and documentation coverage.
**Ncurses Renderer (`renderers/ncurses/clay_renderer_ncurses.c`):**
* **Atomic Rendering Functions**: Decomposed the monolithic `Clay_Ncurses_Render` function into specialized handlers:
* `Clay_Ncurses_RenderRectangle`
* `Clay_Ncurses_RenderText`
* `Clay_Ncurses_RenderBorder`
* **Scissor Management**: Encapsulated scissor stack operations into `Clay_Ncurses_PushScissor` and `Clay_Ncurses_PopScissor`.
* **Visibility Logic**: Extracted visibility/clipping checks into `Clay_Ncurses_GetVisibleRect` for cleaner reuse.
* **Documentation**: Added comprehensive Doxygen documentation for file headers, internal state, constants, and all functions.
**Ncurses Example (`examples/ncurses-example/main.c`):**
* **Architecture Refactor**: Implementation split into clear "App State", "Input Processing", and "UI Components" sections.
* **UI Componentization**: Renamed and organized UI functions with a consistent `UI_` prefix (e.g., `UI_Sidebar`, `UI_FeedPost`, `UI_HelpModal`).
* **State Management**: Introduced `AppState` struct to centralize application state (sidebar visibility, scroll delta, etc.).
* **Input Handling**: Centralized input logic in `App_ProcessInput` loop.
* **Documentation**: Added full Doxygen documentation for the example source.
This refactor maintains identical runtime behavior while significantly improving the codebase's "spoken english" readability and modularity. loop.
* **Documentation**: Added full Doxygen documentation for the example source.
This refactor maintains identical runtime behavior while significantly improving the codebase's readability and modularity.
Introduces Input Processing and Interaction helpers for the Ncurses renderer, ensuring robust mouse support and simplified event handling. **Renderer (`renderers/ncurses`):** - **`Clay_Ncurses_ProcessInput`**: Added a dedicated input processing function that handles both keyboard and mouse events. - Implemented persistent `_isMouseDown` state tracking to fix missed "fast clicks" and preserve button state during drag operations. - Adjusted `mousemask` to `BUTTON1_PRESSED | BUTTON1_RELEASED | REPORT_MOUSE_POSITION` to bypass Ncurses' internal click resolution delay. - **`Clay_Ncurses_OnClick`**: Added a helper function to easily attach click listeners. - Registers the user's callback directly via `Clay_OnHover` (avoiding allocation/proxies). - Matches the standard Clay callback signature pattern. **Example (`examples/ncurses-example`):** - **Input Loop**: Migrated main loop to use `Clay_Ncurses_ProcessInput`. - **Interactions**: - Added a "Toggle Help" button to the sidebar. - Implemented `HandleHelpToggleClick` callback, which explicitly checks for `CLAY_POINTER_DATA_RELEASED_THIS_FRAME` to validate clicks. - Added visual hover effects to sidebar items. **Documentation (`renderers/ncurses/README.md`):** - Updated "Usage" section to demonstrate `Clay_Ncurses_ProcessInput`. - Added "Input & Interaction" section documenting the new helpers.
- Update `renderers/ncurses/clay_renderer_ncurses.c`: - Export `CLAY_NCURSES_KEY_SCROLL_UP` and `CLAY_NCURSES_KEY_SCROLL_DOWN` key codes. - Modify `Clay_Ncurses_ProcessInput` to map mouse wheel events (`BUTTON4`, `BUTTON5`) to these key codes. - Update `Clay_Ncurses_OnClick` to trigger on `CLAY_POINTER_DATA_PRESSED_THIS_FRAME` for immediate feedback. - Update `examples/ncurses-example/main.c`: - Handle `CLAY_NCURSES_KEY_SCROLL_UP/DOWN` in `App_ProcessInput` to drive `_appState.scrollDelta`. - Simplify `HandleHelpToggleClick` to toggle visibility directly. - Apply bold and underline font styles to sidebar items. - Convert input processing to a `while` loop to process all pending events per frame.
This commit addresses issues with mouse interaction reliability and build configuration in the Ncurses renderer and example. Renderer Changes: - Enable explicit xterm 1003 mouse tracking (Any Event) via escape sequences to ensure reliable hover sensing from the first frame (though not so portable). - Refactor `Clay_Ncurses_ProcessInput` to: - Correctly order `Clay_SetPointerState` calls to ensure the "Pressed" state is registered before the function returns. - Detect and return a new `CLAY_NCURSES_KEY_MOUSE_CLICK` event code for single, double, and triple clicks. - Make `Clay_Ncurses_OnClick` as a semantic wrapper around `Clay_OnHover`. - Add empty switch cases for `CLAY_RENDER_COMMAND_TYPE_IMAGE` and `CLAY_RENDER_COMMAND_TYPE_CUSTOM` to prevent unhandled enumeration warnings. Example Application Changes: - Update `main.c` to break the input processing loop immediately upon receiving `CLAY_NCURSES_KEY_MOUSE_CLICK`, ensuring the "Pressed" state is processed by the layout engine for that frame. Build System: - Update `CMakeLists.txt` to replace `FindCurses` with `find_library` and `find_path` for `ncursesw`.
…dundant conditional checks.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Feature: Add Ncurses Renderer and Example
Summary
This PR introduces a new Ncurses renderer backend and a corresponding example project, expanding Clay's TUI capabilities beyond the existing
termbox2andterminaloptions.Changes
renderers/ncurses/clay_renderer_ncurses.c(Ncurses implementation).examples/ncurses-example(Demo of the renderer).CLAY_INCLUDE_NCURSES_EXAMPLESoption toCMakeLists.txt(Default: OFF)..gitignorefor CMake artifacts.Why Ncurses?
terminalbackend), Ncurses relies on the system logic to safely handle different terminal types, preventing broken states.termbox2.