{"id":29376026,"url":"https://github.com/skhelladi/tuikit","last_synced_at":"2025-07-09T21:38:51.947Z","repository":{"id":302107888,"uuid":"1010349491","full_name":"skhelladi/TUIKit","owner":"skhelladi","description":"TUIKit is a C++ framework designed to build rich and interactive Terminal/Text User Interfaces (TUIs).","archived":false,"fork":false,"pushed_at":"2025-07-08T18:41:57.000Z","size":12205,"stargazers_count":17,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-08T19:48:45.373Z","etag":null,"topics":["command-line","command-line-tool","text-user-interface","tui","tui-cpp","user-interface"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skhelladi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-28T22:04:46.000Z","updated_at":"2025-07-08T18:42:00.000Z","dependencies_parsed_at":"2025-06-30T16:37:36.933Z","dependency_job_id":"8b2bc2f9-4be7-4cde-ae38-92e935172bf1","html_url":"https://github.com/skhelladi/TUIKit","commit_stats":null,"previous_names":["skhelladi/tuikit"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/skhelladi/TUIKit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skhelladi%2FTUIKit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skhelladi%2FTUIKit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skhelladi%2FTUIKit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skhelladi%2FTUIKit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skhelladi","download_url":"https://codeload.github.com/skhelladi/TUIKit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skhelladi%2FTUIKit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264503937,"owners_count":23618763,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line","command-line-tool","text-user-interface","tui","tui-cpp","user-interface"],"created_at":"2025-07-09T21:38:39.945Z","updated_at":"2025-07-09T21:38:51.936Z","avatar_url":"https://github.com/skhelladi.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TUIKit: A Qt-like Terminal User Interface Framework for C++\n\n## 🚀 Project Overview\n\nBased on [FTXUI](https://github.com/ArthurSonzogni/FTXUI), TUIKit is a modern C++ framework designed to build rich and interactive Terminal User Interfaces (TUIs). Inspired by the simplicity and power of the Qt framework, TUIKit aims to provide a familiar development experience for creating command-line applications, especially suited for scientific and engineering projects.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"docs/example_1.gif\" alt=\"Demo of TUIKit in action\"\u003e\u003cbr\u003e\n    \u003cstrong\u003eSee \u003ccode\u003eexample_1.cpp\u003c/code\u003e\u003c/strong\u003e\u003cbr\u003e\n\u003c/p\u003e\n\n## 🧩 Core Principles (Qt-like Philosophy)\n\n*   **Hierarchical Widgets:** Utilize a structured hierarchy of UI components (`TUIWidget`, `TUIForm`, `TUIMenu`, etc.).\n*   **Event Handling:** Manage user interactions through a signal/slot-like mechanism or callbacks.\n*   **Automatic Layouts:** Employ flexible layout managers (`TUIVBox`, `TUIHBox`) for responsive UI design.\n*   **Advanced Theming:** Customize colors, borders, and styles to create visually appealing interfaces.\n*  **UI Definition Files:** Support for defining UI layouts in JSON-like `.tuik` files, allowing dynamic loading and modification of interfaces.\n\n## ✨ Implemented Components (Current State)\n\nThe following core components are implemented and functional:\n\n*   `TUIApp`: The entry point for the application.\n*   `TUIWidget`: Base class for all UI components.\n*   `TUILabel`: Displays static text.\n*   `TUITextField`: Editable single-line text input.\n*   `TUIButton`: Interactive button with click events and icon support.\n*   `TUIMenu`: Vertical list of selectable options.\n*   `TUICheckBox`: Simple toggle checkbox.\n*   `TUIRadioBox`: Group of exclusive radio buttons.\n*   `TUIComboBox`: Dropdown list for selection.\n*   `TUISlider`: Horizontal slider for continuous value selection.\n*   `TUIToolbar`: A bar for action buttons.\n*   `TUIForm`: Organizes input fields with labels.\n*   `TUIGroupBox`: Groups related widgets with an optional title and border.\n*   `TUITabWidget`: Organizes content into multiple tabs.\n*   `TUIStatusBar`: Displays status messages at the bottom of the application.\n*   `TUITreeView`: Displays hierarchical data in a tree structure.\n*   `TUIResizableSplit`: Splitter for resizable panels (horizontal/vertical).\n*   `TUIScrollableContainer`: Scrollable area for any widget (with scrollbar, keyboard and mouse support).\n\n## 🛠️ Getting Started\n\n### Prerequisites\n\n*   **C++17 Compiler**: A compiler that supports C++17 (e.g., GCC, Clang, MSVC).\n*   **CMake**: Version 3.15 or higher.\n*   **FTXUI**: A terminal UI library that TUIKit is built upon.\n*   **nlohmann/json**: For JSON parsing, used in `.tuik` file handling.\n\n### Building the Project\n\n1.  **Clone the repository:**\n    ```bash\n    git clone https://github.com/skhelladi/TUIKit.git\n    cd TUIKit\n    ```\n2.  **Install dependencies:**\n    - Install FTXUI:\n    You need to clone it into the `external/ftxui` directory:\n    ```bash\n    git clone https://github.com/ArthurSonzogni/FTXUI.git external/ftxui\n    ```\n    - Install nolmann/json for JSON parsing into `external/json`:\n    ```bash\n    wget https://github.com/nlohmann/json/releases/download/v3.12.0/json.hpp -P external/json\n    ```\n\n3.  **Create a build directory and configure CMake:**\n    ```bash\n    mkdir build\n    cd build\n    cmake ..\n    ```\n\n4.  **Build the project:**\n    ```bash\n    cmake --build .\n    ```\n\n### Running the Example\n\nAfter a successful build, you can run the examples provided in the `examples` directory. The build process will generate executables in the `build` directory.:\n\n```bash\n./build/example_1\n```\nand \n```bash\n./build/example_2\n```\n\n## 🧪 Usage Example\n\nHere's a minimal example demonstrating how to create a simple TUI application with TUIKit, showcasing factory functions and the `connect` mechanism for event handling.\n\n```cpp\n#include \"tuikit.h\"\n\nusing namespace TUIKIT;\n\nint main() {\n    TUIApp app(\"My Simple TUI App\");\n\n    auto main_layout = vbox();\n    \n    auto my_label = label(\"Hello from TUIKit!\");\n    main_layout-\u003eaddWidget(my_label);\n\n    auto my_button = button(\"Click Me!\");\n    connect(my_button, [\u0026] {\n        my_label-\u003esetText(\"Button Clicked!\");\n    });\n    \n    // or you can use a lambda function directly\n    // my_button-\u003eonClick([]() {\n    //     my_label-\u003esetText(\"Button Clicked!\");\n    // });\n\n    main_layout-\u003eaddWidget(my_button);\n\n    app.setMainWidget(main_layout);\n    return app.exec();\n}\n```\n\n---\n\n## 🆕 Example: Embedding a `.tuik` UI file\n\nTUIKit supports embedding JSON UI definitions (`.tuik` files) directly into your binary using CMake and `xxd`.  \nFor each `.tuik` file listed in `TUIKIT_UI`, a header `\u003cname\u003e_tuik.h` is generated with a binary variable.\n\n**Example `.tuik` file (`examples/simple_ui.tuik`):**\n```json\n{\n  \"class\": \"TUIVBoxLayout\",\n  \"children\": [\n    { \"class\": \"TUILabel\", \"properties\": { \"text\": \"Hello from .tuik!\" } },\n    { \"class\": \"TUIButton\", \"properties\": { \"text\": \"Click Me\" }, \"name\": \"btn\" }\n  ]\n}\n```\n\n**C++ usage:**\n```cpp\n#include \"tuikit.h\"\n#include \"examples/simple_ui_tuik.h\"\n#include \u003cnlohmann/json.hpp\u003e\n\nusing namespace TUIKIT;\n\nint main() {\n    TUIApp app(\"TUI .tuik Example\");\n\n    // Load UI from embedded binary resource\n    std::string tuik_str(reinterpret_cast\u003cconst char*\u003e(simple_ui_tuik), simple_ui_tuik_len);\n    nlohmann::json tuik_json = nlohmann::json::parse(tuik_str);\n\n    TUIKLoader loader;\n    auto main_ui_widget = loader.createWidgetFromJson(tuik_json);\n    app.setMainWidget(main_ui_widget);\n\n    // Connect a slot to the button named \"btn\"\n    auto btn = std::dynamic_pointer_cast\u003cTUIButton\u003e(loader.getWidget(\"btn\"));\n    if (btn) {\n        connect(btn, [\u0026] { /* action */ });\n    }\n\n    return app.exec();\n}\n```\n\n**CMake integration:**\n```cmake\nfind_program(XXD_EXE xxd REQUIRED)\nset(TUIKIT_UI \"examples/simple_ui.tuik\")\nforeach(TUIK_FILE ${TUIKIT_UI})\n    get_filename_component(TUIK_NAME ${TUIK_FILE} NAME_WE)\n    get_filename_component(TUIK_DIR ${TUIK_FILE} DIRECTORY)\n    set(VAR_NAME \"${TUIK_NAME}_tuik\")\n    set(HEADER_FILE \"${TUIK_DIR}/${TUIK_NAME}_tuik.h\")\n    add_custom_command(\n        OUTPUT ${HEADER_FILE}\n        COMMAND ${CMAKE_COMMAND} -E make_directory ${TUIK_DIR}\n        COMMAND ${XXD_EXE} -i -n ${VAR_NAME} ${TUIK_FILE} \u003e ${HEADER_FILE}\n        DEPENDS ${TUIK_FILE}\n        COMMENT \"Generate ${HEADER_FILE} from ${TUIK_FILE} with variable ${VAR_NAME} (xxd required)\"\n        VERBATIM\n    )\n    list(APPEND EMBEDDED_HEADERS ${HEADER_FILE})\nendforeach()\nadd_custom_target(generate_embedded_headers ALL DEPENDS ${EMBEDDED_HEADERS})\n```\n\u003c!-- \n## 🗺️ Development Roadmap\n\nTUIKit is under active development, with future phases planned to enhance its capabilities:\n\n### Phase 1: Foundation (MVP) - *Mostly Complete*\n*   CMake template + basic structure\n*   `TUIApp`, `TUIWidget` (base classes)\n*   `TUIMenu`, `TUIForm`, `TUILabel`, `TUITextField`\n*   Basic Layouts (`TUIVBox`, `TUIHBox`)\n*   Simple Styling System\n\n### Phase 2: Enriched Widgets - *In Progress*\n*   `TUIComboBox`, `TUISpinBox`, `TUICheckBox`\n*   `TUIGroupBox` for sections\n*   `TUIToolbar` with action buttons\n*   First version of `TUIBarChart`\n\n### Phase 3: Advanced Visualization\n*   `TUILineChart`, `TUIHistogram`, `TUITable`\n*   `TUITree` for hierarchical navigation\n*   `TUITabWidget` for tabbed organization\n*   Advanced Theming System\n\n### Phase 4: Interactivity and Data Management\n*   JSON ↔ UI binding system\n*   `TUIProjectManager` for multiple projects\n*   Real-time field validation\n*   Multi-threading for long-running tasks\n\n### Phase 5: Scientific Specialization\n*   Specialized CFD/FEA widgets\n*   Plugin system\n*   Integration with external solvers\n*   Configuration export/import\n--\u003e\n## 🤝 Contributing\n\nContributions are welcome! Please refer to the `CONTRIBUTING.md` file (to be created) for guidelines on how to contribute to TUIKit.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the `LICENSE` file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskhelladi%2Ftuikit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskhelladi%2Ftuikit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskhelladi%2Ftuikit/lists"}