ktsu.ImGuiApp 2.0.7-pre.1

ktsu.ImGuiApp

A .NET library that provides application scaffolding for Dear ImGui, using Silk.NET and Hexa.NET.ImGui.

Introduction

ImGuiApp is a .NET library that provides application scaffolding for Dear ImGui, using Silk.NET for OpenGL and window management and Hexa.NET.ImGui for the ImGui bindings. It simplifies the creation of ImGui-based applications by abstracting away the complexities of window management, rendering, and input handling.

Features

• Simple API: Create ImGui applications with minimal boilerplate code
• Full Integration: Seamless integration with Silk.NET for OpenGL and input handling
• Window Management: Automatic window state, rendering, and input handling
• DPI Awareness: Built-in support for high-DPI displays and scaling
• Font Management: Flexible font loading system with customization options
• Texture Support: Built-in texture management for ImGui
• Lifecycle Callbacks: Customizable delegate callbacks for application events
• Menu System: Easy-to-use API for creating application menus
• Positioning Guards: Offscreen positioning checks to keep windows visible
• Modern .NET: Supports .NET 8 and newer
• Active Development: Open-source and actively maintained

Getting Started

Prerequisites

• .NET 8.0 or later
• Windows OS (for DPI awareness features)

Installation

Package Manager Console

Install-Package ktsu.ImGuiApp

.NET CLI

dotnet add package ktsu.ImGuiApp

Package Reference

<PackageReference Include="ktsu.ImGuiApp" Version="x.y.z" />

Usage Examples

Basic Application

Create a new class and call ImGuiApp.Start() with your application config:

using ktsu.ImGuiApp;
using Hexa.NET.ImGui;

static class Program
{
    static void Main()
    {
        ImGuiApp.Start(new ImGuiAppConfig()
        {
            Title = "ImGuiApp Demo",
            OnStart = () => { /* Initialization code */ },
            OnUpdate = delta => { /* Logic updates */ },
            OnRender = delta => { ImGui.Text("Hello, ImGuiApp!"); },
            OnAppMenu = () =>
            {
                if (ImGui.BeginMenu("File"))
                {
                    // Menu items
                    if (ImGui.MenuItem("Exit"))
                    {
                        ImGuiApp.Stop();
                    }
                    ImGui.EndMenu();
                }
            }
        });
    }
}

Custom Font Management

Use the resource designer to add font files to your project, then load the fonts:

ImGuiApp.Start(new()
{
    Title = "ImGuiApp Demo",
    OnRender = OnRender,
    Fonts = new Dictionary<string, byte[]>
    {
        { nameof(Resources.MY_FONT), Resources.MY_FONT }
    },
});

Or load the font data manually:

var fontData = File.ReadAllBytes("path/to/font.ttf");
ImGuiApp.Start(new()
{
    Title = "ImGuiApp Demo",
    OnRender = OnRender,
    Fonts = new Dictionary<string, byte[]>
    {
        { "MyFont", fontData }
    },
});

Then apply the font to ImGui using the FontAppearance class:

private static void OnRender(float deltaTime)
{
    ImGui.Text("Hello, I am normal text!");

    using (new FontAppearance("MyFont", 24))
    {
        ImGui.Text("Hello, I am BIG fancy text!");
    }

    using (new FontAppearance(32))
    {
        ImGui.Text("Hello, I am just huge text!");
    }

    using (new FontAppearance("MyFont"))
    {
        ImGui.Text("Hello, I am somewhat fancy!");
    }
}

Texture Management

Load and manage textures with the built-in texture management system:

private static void OnRender(float deltaTime)
{
    // Load texture from file path
    var textureInfo = ImGuiApp.GetOrLoadTexture("path/to/texture.png");

    // Use the texture in ImGui (using the new TextureRef API for Hexa.NET.ImGui)
    ImGui.Image(textureInfo.TextureRef, new Vector2(128, 128));

    // Clean up when done (optional - textures are cached and managed automatically)
    ImGuiApp.DeleteTexture(textureInfo);
}

Full Application with Multiple Windows

using ktsu.ImGuiApp;
using Hexa.NET.ImGui;
using System.Numerics;

class Program
{
    private static bool _showDemoWindow = true;
    private static bool _showCustomWindow = true;

    static void Main()
    {
        ImGuiApp.Start(new ImGuiAppConfig
        {
            Title = "Advanced ImGuiApp Demo",
            Width = 1280,
            Height = 720,
            OnStart = OnStart,
            OnUpdate = OnUpdate,
            OnRender = OnRender,
            OnAppMenu = OnAppMenu,
            OnShutdown = OnShutdown
        });
    }

    private static void OnStart()
    {
        // Initialize your application state
        Console.WriteLine("Application started");
    }

    private static void OnUpdate(float deltaTime)
    {
        // Update your application state
        // This runs before rendering each frame
    }

    private static void OnRender(float deltaTime)
    {
        // ImGui demo window
        if (_showDemoWindow)
            ImGui.ShowDemoWindow(ref _showDemoWindow);

        // Custom window
        if (_showCustomWindow)
        {
            ImGui.Begin("Custom Window", ref _showCustomWindow);

            ImGui.Text($"Frame time: {deltaTime * 1000:F2} ms");
            ImGui.Text($"FPS: {1.0f / deltaTime:F1}");

            if (ImGui.Button("Click Me"))
                Console.WriteLine("Button clicked!");

            ImGui.ColorEdit3("Background Color", ref _backgroundColor);

            ImGui.End();
        }
    }

    private static void OnAppMenu()
    {
        if (ImGui.BeginMenu("File"))
        {
            if (ImGui.MenuItem("Exit"))
                ImGuiApp.Stop();

            ImGui.EndMenu();
        }

        if (ImGui.BeginMenu("Windows"))
        {
            ImGui.MenuItem("Demo Window", string.Empty, ref _showDemoWindow);
            ImGui.MenuItem("Custom Window", string.Empty, ref _showCustomWindow);
            ImGui.EndMenu();
        }
    }

    private static void OnShutdown()
    {
        // Clean up resources
        Console.WriteLine("Application shutting down");
    }

    private static Vector3 _backgroundColor = new Vector3(0.45f, 0.55f, 0.60f);
}

API Reference

ImGuiApp Static Class

The main entry point for creating and managing ImGui applications.

Methods

ImGuiAppConfig Class

Configuration for the ImGui application.

Properties

FontAppearance Class

A utility class for applying font styles using a using statement.

Constructors

Demo Application

Check out the included demo project to see a working example:

1. Clone or download the repository
2. Open the solution in Visual Studio (or run dotnet build)
3. Start the ImGuiAppDemo project to see a basic ImGui application

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure to update tests as appropriate and adhere to the existing coding style.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Versioning

Check the CHANGELOG.md for detailed release notes and version changes.

Acknowledgements

• Dear ImGui - The immediate mode GUI library
• Hexa.NET.ImGui - .NET bindings for Dear ImGui
• Silk.NET - .NET bindings for OpenGL and windowing
• All contributors and the .NET community for their support

Support

If you encounter any issues or have questions, please open an issue.