Skip to content

Reference

Jump to bottom
github-actions[bot] edited this page Dec 16, 2025 · 2 revisions

Reference

Complete reference documentation for Myra UI Generator.

Supported Widgets

The generator recognizes the following Myra XML elements and maps them to C# types:

XML Element Generated C# Type Notes
Label Label Standard text label
Button Button Button widget
CheckBox CheckBox Checkbox control
TextBox TextBox Single-line text input
Panel Panel Container panel
VerticalStackPanel VerticalStackPanel Vertical layout container
HorizontalStackPanel HorizontalStackPanel Horizontal layout container
Grid Grid Grid layout container
ScrollViewer ScrollViewer Scrollable container
Slider Slider Numeric slider control
ProgressBar ProgressBar Progress indicator
ListBox ListBox List selection control
ComboBox ComboBox Dropdown selection
Image Image Image display widget
TextBlock TextBlock Rich text display
Unknown Widget Fallback for unrecognized types

Fallback Behavior

If the generator encounters an XML element it doesn't recognize, it will:

  1. Use Widget as the property type (the base type for all Myra widgets)
  2. Still generate the property if the element has an Id attribute
  3. You can cast to the specific type at runtime if needed

Example:

// Generated code for unknown widget type
public Widget CustomWidget { get; private set; }

// Usage with casting
var custom = _ui.CustomWidget as MyCustomWidgetType;

Generated Code Structure

File Naming

Generated files follow this pattern:

  • XML File: TitleScreen.xml
  • Generated File: TitleScreenUI.g.cs
  • Class Name: TitleScreenUI

The .g.cs suffix indicates a generated file (standard .NET convention).

Class Structure

Each generated class is a partial class with:

  1. Properties: One property per widget with an Id attribute
  2. Initialize Method: Binds widgets from the root widget

Example generated code:

using Myra.Graphics2D.UI;
using System;

namespace YourNamespace.UI.Generated;

/// <summary>
/// Auto-generated UI accessor for TitleScreen.xml
/// This file is automatically generated by MyraUIGenerator - do not edit manually.
/// </summary>
public partial class TitleScreenUI
{
    public Button StartButton { get; private set; }
    public Label TitleLabel { get; private set; }
    public Button SettingsButton { get; private set; }

    /// <summary>
    /// Initialize widgets from the loaded UI root.
    /// Call this after loading the XML via UiLoader.Load().
    /// </summary>
    public void Initialize(Widget root)
    {
        StartButton = root.FindChildById("StartButton") as Button;
        TitleLabel = root.FindChildById("TitleLabel") as Label;
        SettingsButton = root.FindChildById("SettingsButton") as Button;
    }
}

Property Generation Rules

  1. Property Name: Matches the Id attribute exactly (case-sensitive)
  2. Property Type: Based on XML element name (see Supported Widgets table)
  3. Access Modifier: public
  4. Mutability: private set (read-only from outside, set by Initialize)

Partial Class Support

Generated classes are partial, allowing you to extend them:

// Your code: MainMenuUI.cs
public partial class MainMenuUI
{
    public void Show() { /* custom logic */ }
    public void Hide() { /* custom logic */ }
}

API Reference

Generated Class API

Properties

All generated properties follow this pattern:

public {WidgetType} {PropertyName} { get; private set; }
  • WidgetType: The Myra widget type (e.g., Button, Label)
  • PropertyName: Matches the XML Id attribute
  • Access: Public getter, private setter
  • Initialization: Set to null until Initialize() is called

Initialize Method

public void Initialize(Widget root)

Parameters:

  • root (Widget): The root widget from UiLoader.Load().Root

Behavior:

  • Finds each widget by its Id using FindChildById()
  • Casts to the appropriate type
  • Sets the corresponding property
  • Properties may be null if widget not found or type mismatch

Usage:

var project = UiLoader.Load("TitleScreen.xml");
var ui = new TitleScreenUI();
ui.Initialize(project.Root);

Important Notes:

  • Must be called after loading the XML
  • Must be called before accessing properties
  • Properties will be null if widgets aren't found
  • No error is thrown if a widget is missing (check for null)

Type System

Widget Hierarchy

All generated types inherit from Myra.Graphics2D.UI.Widget:

Widget (base)
├── Label
├── Button
├── CheckBox
├── TextBox
├── Panel
│   ├── VerticalStackPanel
│   ├── HorizontalStackPanel
│   └── Grid
├── ScrollViewer
├── Slider
├── ProgressBar
├── ListBox
├── ComboBox
├── Image
└── TextBlock

Type Safety

The generator provides compile-time type safety:

// ✅ Correct - IntelliSense and type checking
ui.StartButton.Click += OnClick;
ui.TitleLabel.Text = "Hello";

// ❌ Compile error - wrong type
ui.StartButton.Text = "Hello"; // Button doesn't have Text property

// ❌ Compile error - property doesn't exist
ui.NonExistentButton.Click += OnClick;

Diagnostic Codes

The generator reports diagnostic messages during compilation. These help debug configuration and generation issues.

MYRA001: Error generating UI code

Severity: Warning

Message: Error processing {file}: {error}

Description: An error occurred while processing a specific XML file.

Common Causes:

  • Invalid XML syntax
  • Malformed XML structure
  • File encoding issues
  • File access permissions

Resolution:

  1. Validate XML syntax
  2. Check file encoding (should be UTF-8)
  3. Ensure file is readable
  4. Check XML structure matches Myra format

MYRA002: Generator executing

Severity: Warning

Message: MyraUIGenerator executing. Namespace: {namespace}, Directory: {directory}, AdditionalFiles count: {count}

Description: Informational message showing generator is running with current configuration.

Use: Verify configuration is being read correctly.

MYRA003: XML files found

Severity: Warning

Message: Found {count} XML files matching directory '{directory}'

Description: Shows how many XML files were found matching the configured directory.

Use: Verify XML files are being discovered.

If count is 0:

  • Check AdditionalFiles in .csproj
  • Verify directory path in configuration
  • Check file paths match directory setting

MYRA004: Generated UI class

Severity: Warning

Message: Generated {className}UI with {count} widgets

Description: Success message indicating a UI class was generated.

Use: Confirm generation succeeded.

MYRA005: No widgets found

Severity: Warning

Message: No widgets with Id found in {fileName}.xml

Description: XML file was processed but no widgets with Id attributes were found.

Resolution:

  • Add Id attributes to widgets you want to access
  • Verify XML structure is correct
  • Check that widgets are nested properly

MYRA999: Generator exception

Severity: Error

Message: MyraUIGenerator threw an exception: {exception}

Description: An unexpected exception occurred in the generator itself.

Resolution:

  1. Check the exception details in the message
  2. Verify project configuration
  3. Ensure all dependencies are installed
  4. Report as a bug if issue persists

Viewing Diagnostics

Visual Studio:

  • Check Error List window
  • Build Output window (set to "Detailed" or "Diagnostic")

Command Line:

dotnet build --verbosity detailed

VS Code:

  • Check Problems panel
  • Terminal output during build

Next Steps

Clone this wiki locally