Gondwana.Widgets 2.6.1

Gondwana.Widgets

Gondwana.Widgets provides reusable UI and gameplay widgets for the Gondwana game engine, including menus, dialogs, labels, buttons, form-style controls, overlays, HUD elements, and other DirectDrawing-friendly 2D/2.5D game controls.

It builds on the core Gondwana rendering model and is intended for in-game interface elements rather than platform-native UI. Widgets are designed to render inside Gondwana scenes, views, and backbuffers using the same engine-driven drawing pipeline as the rest of the game.

Features

• Reusable in-game UI widgets for Gondwana projects
• DirectDrawing-friendly controls and overlays
• Common controls including labels, buttons, check boxes, radio buttons, list boxes, combo boxes, tabbed containers, and editable text boxes
• Game-oriented components such as HUD elements, health bars, name tags, dialogs, conversation boxes, menus, and an opt-in runtime profiler HUD
• Code-first widget composition with no external editor or scene GUI required
• Designed for 2D and 2.5D games using Gondwana's scene, view, and rendering systems
• Cross-platform-friendly architecture through the core Gondwana rendering pipeline

Installation

Interactive desktop video is available separately in Gondwana.Video.Widgets. Its VideoWidget composes DirectVideo with ordinary Widget input/lifecycle and dragging (disabled by default). Installing Widgets alone adds no Video or LibVLC dependency. Native requirements remain those of Gondwana.Video.

dotnet add package Gondwana.Widgets

Usage

Add the package to your game project, then create and register widgets as part of your normal Gondwana scene or DirectDrawing setup.

Example:

using Gondwana.Widgets;

A typical widget can be used for in-game interface elements such as:

• HUD overlays
• Dialog boxes and NPC conversation boxes
• Labels, text panels, and editable text boxes
• Menu screens, list boxes, and combo boxes
• Buttons, check boxes, radio buttons, and selectable options
• Health bars, name tags, and status indicators

Exact usage depends on the specific widget type being used.

Runtime profiler HUD

ProfilerWidget displays detached Engine.Instance.Profiler measurements in-game. It can filter individual sources/measurements, optionally include current Scene/View/ backbuffer/configuration/MSAA context, accept application-specific lines through AdditionalLinesProvider, show hover definitions, and expose a built-in Metrics selector for runtime visibility changes. The saved-scene Scene Viewer uses the same widget for its F3 diagnostics overlay, providing a built-in real-world consumer of the API.

TooltipWidget is also available as a reusable non-interactive view overlay for contextual pointer help outside the profiler.

See the ProfilerWidget guide.

Menu bars

MenuBarWidget supports callback commands, immutable optional item keys, check/radio items, recursive submenus, SKImage icons, typed KeyGesture shortcuts, and explicit mnemonics. Fluent AddItem construction remains available. Use GetItem(key) or the indexer to update enabled/checked state later. Keyboard shortcuts receive unhandled input after the focused widget, including while dropdowns are closed.

See the menu guide and Demos/WidgetsTest/WidgetsTestHost.cs for complete consumer examples.

Tabbed containers

TabControlWidget groups ordinary child widgets into selectable TabPageWidget containers. Tab headers resize across the configured rows, can select pages through explicit Alt mnemonics, and support optional primary-pointer drag reordering. Use AutoExpandRows and PreferredTabWidth when the control should add header rows as pages are added.

See the tab-control guide and Demos/WidgetsTest/WidgetsTestHost.cs for a working example.

Toast notifications

var toast = new ToastWidget(
    RenderSurface.Host,
    view,
    new Size(320, 72),
    "Game saved",
    WidgetAnchor.TopRight)
{
    Transition = ToastTransition.Slide,
    SlideOrigin = ToastSlideOrigin.Right,
    HoldDurationSec = 2.5f
};

toast.ShowToast();

Set HoldDurationSec to null for a toast that remains until Dismiss() is called. An explicit Rectangle constructor and SourceLocationPx allow exact screen-coordinate placement when the standard anchors are not appropriate.

Floating text and images

var damage = new PopupWidget(
        RenderSurface.Host,
        targetSprite,
        new Size(96, 36),
        "-25",
        WidgetAnchor.TopCenter)
    .SetTextColor(SKColors.OrangeRed);

damage.VelocityPxPerSec = new Vector2(0f, -64f);
damage.ShowPopup();

PopupWidget also accepts view or scene-layer bounds and SKImage/SKBitmap content. Use BindTo(sceneLayer, gridLocation) to originate an effect from a fixed grid cell.

Image-filled rectangles

panel.SetFillImage(
    smallTileBitmap,
    DirectRectangle.ImageFillMode.Repeat,
    filterQuality: SKFilterQuality.None);

Image fills support Stretch, Fit, Fill, Center, PixelPerfect, and Repeat. The image is clipped to the rectangle, including rounded corners.

Widget Scope

Gondwana.Widgets is intended for game UI, not operating-system UI.

Use it for interface elements that should appear inside the game world or game viewport, such as dialog boxes, overlays, HUDs, menus, and sprite-adjacent indicators.

For platform-specific hosting and application surfaces, use one of the hosting or adapter packages instead, such as:

• Gondwana.WinForms
• Gondwana.Avalonia
• Gondwana.Blazor

Documentation

• Source Code
• Architecture & Guides
• API Reference (Doxygen)
• Release History

Related Packages

• Gondwana --- Core engine

License

MIT