Merge branch 'main' of https://github.com/kimkulling/tiny_ui

Author: kimkulling

AGENTS.md

@@ -0,0 +1,219 @@
+# AGENTS.md - Agentic Coding Guidelines for tiny_ui
+
+## Project Overview
+
+tiny_ui is a C++17 library for creating simple UIs on Windows and Linux, using SDL2 as the renderer. The project is built with CMake and vcpkg for dependency management.
+
+---
+
+## Build, Lint, and Test Commands
+
+### Building the Project
+
+```bash
+# Configure with CMake (uses vcpkg toolchain)
+cmake -B build -DCMAKE_BUILD_TYPE=Release
+
+# Build the library and samples
+cmake --build build --config Release
+```
+
+On Windows with Visual Studio, you can also open `tiny_ui.slnx` or use the `.vcxproj` files.
+
+### Dependencies
+
+The project requires:
+- SDL2
+- SDL2_image
+- SDL2_ttf
+- glm
+
+These are managed via vcpkg (see `vcpkg.json`).
+
+### Running the Sample Application
+
+```bash
+# After building, run the sample
+./bin/release/tiny_ui_sample.exe   # Windows
+./bin/tiny_ui_sample              # Linux
+```
+
+### Linting and Formatting
+
+The project uses `.clang-format` for code formatting:
+
+```bash
+# Format a single file
+clang-format -i src/tinyui.cpp
+
+# Format all source files
+find src -name "*.cpp" -o -name "*.h" | xargs clang-format -i
+```
+
+### Testing
+
+**Note**: This project currently has no automated tests. The test step in CI (`.github/workflows/cmake.yml`) is commented out. If adding tests:
+
+```bash
+# Run tests via CTest (when implemented)
+cd build
+ctest -C Release
+```
+
+To run a single test (when tests exist), use CTest's filtering:
+```bash
+ctest -R test_name_pattern
+```
+
+---
+
+## Code Style Guidelines
+
+### General Style
+
+- **C++ Standard**: C++17
+- **Formatting**: Uses `.clang-format` (LLVM-based, see `.clang-format`)
+- **Indentation**: 4 spaces, no tabs
+- **Column Limit**: 0 (unlimited)
+
+### File Organization
+
+- Header files (`.h`) go in `src/`
+- Implementation files (`.cpp`) go in `src/`
+- Backend-specific code goes in `src/backends/`
+- Samples go in `samples/`
+- All source files must include the MIT License header
+
+### Imports and Includes
+
+```cpp
+// Order: 1. Project headers, 2. STL/Standard headers, 3. External libraries
+#include "tinyui.h"
+#include "widgets.h"
+#include "backends/sdl2_renderer.h"
+
+#include <iostream>
+#include <cstring>
+
+#include "stb_image.h"
+```
+
+Include order (per `.clang-format`):
+1. Local project headers (`"*.h"`)
+2. System headers (`<*.h>`)
+3. Other system headers (`<*>`)
+
+### Naming Conventions
+
+- **Types/Structs/Enums**: PascalCase (e.g., `struct Widget`, `enum class Alignment`)
+- **Functions**: camelCase (e.g., `createContext()`, `initScreen()`)
+- **Member Variables**: `m` prefix (e.g., `mId`, `mType`, `mParent`)
+- **Constants**: PascalCase or `k` prefix (e.g., `InvalidHandle`, `kDefaultSize`)
+- **Namespaces**: lowercase (e.g., `namespace tinyui`)
+
+### Type Conventions
+
+- Use `int32_t` for explicit-width integers
+- Use `ret_code` (defined as `int32_t`) for return codes
+- Use `nullptr` instead of `NULL`
+- Use `const` extensively for pointer parameters and member functions
+- Use `constexpr` for compile-time constants
+- Use `static constexpr` for class-level constants
+
+### Return Codes
+
+The library uses a consistent return code pattern:
+```cpp
+static constexpr ret_code InvalidRenderHandle = -3;
+static constexpr ret_code InvalidHandle = -2;
+static constexpr ret_code ErrorCode = -1;
+static constexpr ret_code ResultOk = 0;
+```
+
+### Error Handling
+
+- Return error codes for recoverable errors
+- Use `assert()` for programming errors/invariants (development only)
+- Validate input parameters at the start of functions
+
+### Enums
+
+Use `enum class` for type-safe enums:
+```cpp
+enum class Alignment : int32_t {
+    Invalid = -1,
+    Left = 0,
+    Center,
+    Right,
+    Count  // Use Count for array sizing
+};
+```
+
+### Structs and Classes
+
+- Use structs for POD (Plain Old Data) types
+- Use `= default` for trivial constructors/destructors
+- Initialize member variables with default values in class definition
+- Use Doxygen-style comments for documentation
+
+### Code Example
+
+```cpp
+/// @brief The tiny ui context.
+struct Context {
+    bool               mCreated{false};
+    bool               mRequestShutdown{false};
+    const char        *mAppTitle{nullptr};
+    Widget            *mRoot{nullptr};
+
+    /// @brief Will create a new tiny ui context.
+    /// @param title The title of the context.
+    /// @return The created context.
+    static Context *create(const char *title);
+    
+    /// @brief Will destroy a valid tinyui context.
+    /// @param ctx The context to destroy.
+    static void destroy(Context *ctx);
+};
+```
+
+### Common Patterns
+
+```cpp
+// Function returning error code
+ret_code TinyUi::initScreen(int32_t x, int32_t y, int32_t w, int32_t h) {
+    if (w <= 0 || h <= 0) {
+        return ErrorCode;
+    }
+    // ... implementation
+    return ResultOk;
+}
+
+// Callback interface
+struct CallbackI {
+    typedef int (*funcCallback) (uint32_t id, void *data);
+    funcCallback mfuncCallback[Events::NumEvents];
+    void *mInstance{nullptr};
+};
+```
+
+---
+
+## CI/CD
+
+The project uses GitHub Actions (see `.github/workflows/cmake.yml`):
+- Builds on Ubuntu latest
+- Installs SDL2, SDL2-image, SDL2-ttf via apt
+- Runs CMake configure and build
+
+---
+
+## Key Files
+
+- `CMakeLists.txt` - Main build configuration
+- `vcpkg.json` - Dependency manifest
+- `.clang-format` - Code formatting rules
+- `.github/workflows/cmake.yml` - CI pipeline
+- `src/tinyui.h` - Main header with core types
+- `src/widgets.h` - Widget definitions
+- `src/backends/` - Platform-specific rendering backends

CMakeLists.txt

@@ -20,8 +20,8 @@ SET( CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_HOME_DIRECTORY}/lib )
 SET( CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_HOME_DIRECTORY}/bin )
 
 INCLUDE_DIRECTORIES( 
-    ${CMAKE_CURRENT_BINARY_DIR}/src
-    ${CMAKE_CURRENT_BINARY_DIR}/contrib/stb_image    
+    src
+    contrib/stb_image    
 )
 
 find_package(SDL2 CONFIG REQUIRED)

README.md

@@ -3,83 +3,71 @@
 </p>
 
 # tiny_ui
-This repo contains a small library to generate simple UIs on different platforms. I am using it for my own games.
-
-Currently this works on Windows and Linux. The renderer is based on SDL2. An OSRE Renderbackend is planned.
-
-# Features
-- Elements
-  - Panel
-  - Buttons
-  - Labels
-  - Progress Bar (experimental)
-- Platform support for
-  - Windows
-  - Linux
- 
-# Planned
-- Treeview
-- Status Bar
-- Default dialogs
-
-# Examples:
-## Quickstart
+
+A lightweight C++17 UI library for Windows and Linux, using SDL2 as the renderer.
+
+## Features
+
+- **Widgets**: Panel, Button, Label, Progress Bar (experimental)
+- **Platforms**: Windows, Linux
+
+## Build
+
+```bash
+# Configure and build
+cmake -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build --config Release
+```
+
+## Quick Start
 
 ```cpp
 #include <iostream>
 #include "widgets.h"
 
-#ifdef main
-#  undef main
-#endif
-
 using namespace tinyui;
 
-static int quit(unsigned int id, void *data) {
-    if (data == nullptr) {
-        return ErrorCode;
-    }
-    
-    Context *ctx = static_cast<Context*>(data);
+static int onQuit(unsigned int id, void *data) {
+    auto *ctx = static_cast<Context*>(data);
     ctx->mRequestShutdown = true;
-
     return ResultOk;
 }
 
-int main(int argc, char *argv[]) {
+int main() {
     Style style = TinyUi::getDefaultStyle();
-    Context &ctx = Context::create("Sample-Screen",  style);
-
-    if (TinyUi::initScreen(ctx, 20, 20, 1024, 768) == -1) {
-        ctx.mLogger(LogSeverity::Error, "Cannot init screen");
-        return ErrorCode;
-    }
+    Context *ctx = Context::create("Sample", style);
 
-    Widgets::panel(ctx, RootPanelId, 0, "Sample-Dialog", 90, 5, 120, 300, nullptr);
-    Widgets::label(ctx, 2, RootPanelId, "Title", 100, 10, 100, 20, Alignment::Center);
-    Widgets::button(ctx, 3, RootPanelId, "Test 1", nullptr, 100, 50, 100, 40, nullptr);
-    Widgets::button(ctx, 4, RootPanelId, "Test 2", nullptr, 100, 100, 100, 40, nullptr);
-    Widgets::button(ctx, 5, RootPanelId, "Test 3", nullptr, 100, 150, 100, 40, nullptr);
-    Widgets::button(ctx, 6, RootPanelId, nullptr,  "button_test.png", 100, 200, 100, 40, nullptr);
+    TinyUi::initScreen(20, 20, 1024, 768);
 
-    CallbackI quit(quit, &ctx);
-    Widgets::button(ctx, 7, RootPanelId, "Quit", nullptr, 100, 250, 100, 40, &quit);
+    Widgets::panel(ctx, RootPanelId, 0, "Dialog", 90, 5, 120, 300, nullptr);
+    Widgets::label(ctx, 1, RootPanelId, "Title", 100, 10, 100, 20, Alignment::Center);
+    Widgets::button(ctx, 2, RootPanelId, "Quit", nullptr, 100, 50, 100, 40, &onQuit);
 
-    while (TinyUi::run(ctx)) {
-        TinyUi::beginRender(ctx, style.mClearColor);
+    while (TinyUi::run()) {
+        TinyUi::beginRender(style.mClearColor);
         Widgets::renderWidgets(ctx);
-        TinyUi::endRender(ctx);
+        TinyUi::endRender();
     }
 
-    TinyUi::release(ctx);
-
+    TinyUi::release();
     return 0;
 }
+```
 
+## Running the Sample
+
+```bash
+./bin/release/tiny_ui_sample.exe   # Windows
+./bin/tiny_ui_sample               # Linux
 ```
-results to
 
-![Sample screen](assets/images/sample1.png "The sample screen").
+![Sample](assets/images/sample1.png)
+
+## Planned
+
+- TreeView, Status Bar, Default dialogs
+
+---
 
-Build Status: [![CMake](https://github.com/kimkulling/tiny_ui/actions/workflows/cmake.yml/badge.svg)](https://github.com/kimkulling/tiny_ui/actions/workflows/cmake.yml)
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=kimkulling_tiny_ui&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=kimkulling_tiny_ui)
+[![CMake](https://github.com/kimkulling/tiny_ui/actions/workflows/cmake.yml/badge.svg)](https://github.com/kimkulling/tiny_ui/actions/workflows/cmake.yml)
+[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=kimkulling_tiny_ui&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=kimkulling_tiny_ui)