How to use.

• Get SDL3 sourcefiles and put it in vendored/SDL* (currently using version 3.2.10)
• Add a /build directory, and do cmake .. to build from CMakeLists.txt
• Run nodemon in terminal during development, or use executable in /build/debug/.

Update 0.0.1

SDL3 Application Framework

This is what i want it to be after some iterations A lightweight application framework built on top of SDL3, providing a structured approach to building graphical applications.

Overview

This framework provides:

• Structured application lifecycle management
• Layout system for UI organization
• Page-based content management
• Basic widget system (shapes, buttons)
• Animation support
• Event handling system

Project Structure

├── include/              # Public header files
│   ├── app/             # Application-level components
│   ├── core/            # Core engine functionality
│   ├── layouts/         # Layout management system
│   └── widgets/         # UI widget components
│
├── src/                 # Implementation files
│   ├── app/            
│   ├── core/           
│   ├── layouts/        
│   └── widgets/        
│
└── docs/                # Documentation

Building

The project uses CMake as its build system. To build:

cmake -S . -B build
cmake --build build

Requirements

• SDL3
• CMake 3.16 or higher
• C compiler with C11 support

Core Components

Application Context

The AppContext struct (in application.h) manages:

• Window and renderer
• Performance timing
• Mouse input state
• Layout tree
• Current page

Layout System

Provides a tree-based layout management system for organizing UI elements.

Page Management

Pages encapsulate content and handle:

• Event processing
• Content updates
• Rendering
• Animation

Architecture

The framework follows a layered architecture:

1. Core Layer (SDL3 Abstraction)

   • Application lifecycle
   • Event system
   • Rendering system

2. Layout Layer

   • Tree-based layout management
   • Flexible positioning system
   • Container management

3. Widget Layer

   • Basic UI components
   • Event handling
   • Visual presentation

4. Page Layer

   • Content organization
   • State management
   • Scene composition

Usage

#include "core/application.h"
#include "layouts/app_layout.h"
#include "app/page.h"

int main(int argc, char* argv[]) {
    AppContext app_context;
    
    // Initialize the application
    if (!initialize_app(&app_context, "My App", 800, 600)) {
        return 1;
    }

    // Create layout structure
    app_context.root_layout = create_app_layout_structure(&app_context);

    // Create and set active page
    app_context.current_page = page_create();

    // Run the application
    run_main_loop(&app_context);

    cleanup_app(&app_context);
    return 0;
}

Extending the Framework

Creating New Widgets

1. Create header file in include/widgets/:

typedef struct MyWidget {
    // Widget-specific properties
} MyWidget;

MyWidget* my_widget_create(void);
void my_widget_destroy(MyWidget* widget);
void my_widget_handle_event(MyWidget* widget, SDL_Event* event);
void my_widget_update(MyWidget* widget, float delta_time);
void my_widget_render(MyWidget* widget, AppContext* context);

2. Implement in src/widgets/:
   • Follow existing widget patterns (button.c, shape.c)
   • Handle lifecycle, events, rendering
   • Use animation system if needed

Creating New Layouts

1. Create header file in include/layouts/:

typedef struct MyLayout {
    LayoutNode base;  // Inherit from base layout
    // Layout-specific properties
} MyLayout;

MyLayout* my_layout_create(void);
void my_layout_arrange(MyLayout* layout);

2. Implement in src/layouts/:
   • Inherit from base layout system
   • Implement arrangement logic
   • Handle child positioning

Suggestions for Improvement

1. Error Handling

   • Add more robust error checking throughout initialization
   • Implement error logging system beyond SDL_Log

2. Documentation

   • Add inline documentation for public APIs
   • Create usage examples for each component

3. Features

   • Add resource management system
   • Implement more widget types
   • Add theming support
   • Consider adding scene graph support

4. Testing

   • Add unit tests for core components
   • Implement integration tests for layout system
   • Add performance benchmarks

License

[Add appropriate license information]

Development Workflow (Git)

This project uses Git for version control. Here's a basic workflow for managing features or development versions:

1. Start a New Feature/Version:

   • Ensure your main branch is up-to-date:

     git checkout main
     git pull origin main

   • Create a new branch for your work (e.g., feature/new-widget or dev/v0.2):

     git checkout -b feature/new-widget

2. Work on the Feature Branch:

   • Make your code changes.
   • Commit your changes frequently:

     git add .
     git commit -m "Implement basic button widget"

   • Push your branch to the remote repository to back it up and potentially collaborate:

     git push -u origin feature/new-widget

     (The -u flag sets the upstream branch, so future git push commands from this branch will automatically go to origin/feature/new-widget)

3. Update Main Branch with Completed Feature:

   • Once the feature is complete and tested, switch back to the main branch:

     git checkout main

   • Ensure main is still up-to-date:

     git pull origin main

   • Merge your feature branch into main:

     git merge --no-ff feature/new-widget

     (Using --no-ff creates a merge commit, preserving the history of the feature branch)
   • Resolve any merge conflicts if they occur.
   • Push the updated main branch:

     git push origin main

     (Your feature/new-widget branch still exists locally and remotely at this point)

4. Clean Up:

   • If you no longer need the feature branch, you can delete it locally:

     git branch -d feature/new-widget

     (Use -D instead of -d if the branch hasn't been fully merged and you still want to delete it)
   • You can also delete it from the remote repository:

     git push origin --delete feature/new-widget

5. Moving between branches: git add README.md git commit -m "Update README with development workflow"

Now you can switch branches

git checkout main

or

• This saves the current branch git stash push -m "README workflow edits"

Now you can switch branches

git checkout main

• When back in the branch do: to load the saved state git checkout feature/new-widget git stash pop