H073.SurfaceKit 1.0.4.5-preview

SurfaceKit

SurfaceKit is a modular, UI framework for C# and MonoGame, designed to help developers build flexible, organized, and interactive interfaces for games and applications. The library offers container views, input handling, graphics overlays, and now, tools for building complex view hierarchies with ViewBuilder.

Features

• Container-Based Layouts: Arrange UI elements using HStack, VStack, and ZStack for horizontal, vertical, and layered arrangements.
• Modifiers and Gestures: Enhance views with padding, backgrounds, and gestures like tap actions.
• Graphics Overlay System: Customizable strategies for layout calculation, rendering, and interaction handling.
• Input Management: Capture keyboard and mouse input with SurfaceInputManager.
• View Building Tools: Construct complex view structures using ViewBuilder and ViewHelper.
• Customizable UI Elements: Includes essential components like Text, Image, and Background.

Installation

To install SurfaceKit via NuGet:

dotnet add package SurfaceKit

Core Concepts

Views

View is the base class for UI elements. Views have position, dimension, layout flexibility, and modifier properties, which allow them to be customized and controlled in a parent view. Common UI components like Text, Image, and Background inherit from View.

Container Views

SurfaceKit provides HStack, VStack, and ZStack for arranging views horizontally, vertically, and in layers, respectively. These containers allow for easy, nested layouts.

var hStack = new HStack();
hStack.Add(new Image("texture.png"));
hStack.Add(new Text("Hello World", "Arial") { ForegroundStyle = Color.White });

Modifiers and Gestures

SurfaceKit includes ModifierBase and specific modifiers like Padding to customize views. Gestures such as OnTapGesture add interactive behaviors to views.

var onTap = new OnTapGesture(() => Console.WriteLine("Tapped!"));
var paddedView = new Padding(10);
paddedView.Add(onTap);

View Building with ViewBuilder

ViewBuilder simplifies the construction of complex view hierarchies, allowing views to be created and nested declaratively.

• ViewBuilder enables recursive building of views and applies modifiers to each view.
• Use Build() to finalize and retrieve the structured view.

Example:

var view = new ViewBuilder {
    new VStack {
        new Image("logo"),
        new Text("Welcome", "Arial"),
        new Padding(10) {
            new Background(Color.Gray) {
                new Text("Start Game", "Arial")
            }
        }
    }
}.Build();

Utility Functions with ViewHelper

ViewHelper provides utility functions, such as EnsureCorrectViewType<T>, to verify view types at runtime.

var correctView = ViewHelper.EnsureCorrectViewType<Text>(someView);

Graphics Overlay System

Calculation Strategies

CalculationStrategyBase defines methods for layout calculations, handling proposed and desired sizes, and arranging child views.

Interaction Strategies

InteractionStrategyBase provides input-handling methods for views, enabling interactive responses to user actions.

Render Strategies

RenderStrategyBase manages view rendering, enabling custom drawing logic for different view types.

System Components

GraphicOverlayCalculator

Manages layout calculations for each view using specific calculation strategies.

GraphicOverlayInteractor

Processes input across views with interaction strategies for gesture and input handling.

GraphicOverlayRenderer

Draws each view using assigned render strategies for flexible UI rendering.

Example: Custom View with StartMenuView

The StartMenuView class demonstrates how to create a custom view with nested structures using ViewBuilder and built-in views.

public class StartMenuView : View
{
    protected override View BuildBody()
    {
        return new ViewBuilder {
            new VStack
            {
                new Image("heart"),
                new OnTapGesture(() => 
                {
                    TheaterKit.SceneManager.Instance.StageAsync(GlobalSceneTag.Game);
                })
                {
                    new Background(Color.Red) {
                        new Padding(10) {
                            new Text("Hallo", "Arial")
                        }
                    }
                },
                new Text("Was Geht", "Arial"),
            }
        }.Build();
    }
}

In this example:

• VStack vertically arranges Image and Text views.
• OnTapGesture wraps a nested Background with padding, which triggers an action upon tapping.
• BuildBody() uses ViewBuilder to construct and return the entire view hierarchy.

License

SurfaceKit is licensed under the MIT License.

SurfaceKit offers a flexible, extensible framework for creating user interfaces in MonoGame. With tools like ViewBuilder and strategy-driven graphics overlays, SurfaceKit provides powerful options for managing complex UI layouts and interactions.