mattercontrol/research/03-ui-rendering.md

# UI & Rendering System

## Summary

MatterControl uses a custom UI framework called **agg-sharp** that provides both 2D vector graphics rendering and OpenGL-accelerated 3D viewport rendering. The UI is built on `GuiWidget` components with a flexible layout system, theming support, and cross-platform window abstraction.

## Technical Description

### agg-sharp Framework

The agg-sharp library (Anti-Grain Geometry for C#) is a custom rendering abstraction layer providing:

1. **2D Vector Graphics** - Software rendering with optional hardware acceleration
2. **Widget System** - `GuiWidget` base class with layout, input handling, and invalidation
3. **OpenGL Integration** - Hardware-accelerated 3D rendering
4. **Platform Abstraction** - Window creation via `ISystemWindowProvider`

### Widget Architecture

All UI elements inherit from `GuiWidget`:

```
GuiWidget (base)
├── BackgroundColor, Border, Padding, Margin
├── HAnchor, VAnchor (layout anchoring)
├── Children collection
├── Input events (Click, MouseMove, KeyDown, etc.)
└── Invalidation and redraw system
```

**Layout System:**
- `HAnchor` / `VAnchor` enums: `None`, `Left`, `Center`, `Right`, `Stretch`, `Fit`
- `FlowLayoutWidget` - horizontal or vertical flow layout
- `Toolbar` - specialized horizontal toolbar with overflow support
- `DockingTabControl` - sidebar panel docking

### Main UI Structure

```
RootSystemWindow
└── MainViewWidget (FlowLayoutWidget, TopToBottom)
    ├── TabBar (ChromeTabs)
    │   ├── ChromeTab (Design/Printer tabs)
    │   │   └── TabContent (PrinterTabPage or DesignTabPage)
    │   └── NewTabButton (+)
    └── StatusBar (Toolbar)
        ├── StatusMessage
        ├── UpdateAvailableButton
        └── TasksContainer
```

### Tab System

MatterControl uses a Chrome-style tabbed interface:

| Class | Purpose |
|-------|---------|
| `SimpleTabs` | Base tabs with toolbar and content area |
| `ChromeTabs` | Chrome-style tabs with drag, reorder, close |
| `ChromeTab` | Individual draggable tab |
| `ITab` | Tab interface (TabContent, Key, Text) |

**Tab Types:**
- **PrinterTabPage** - Printer-specific view with 3D preview, controls, settings
- **DesignTabPage** - Standalone design editing view
- **HelpTabPage** - Integrated help browser

### Theming System

Themes are managed through `ThemeConfig` and `ThemeSet`:

```
ThemeSet
├── Theme (ThemeConfig) - Main theme
├── MenuTheme (ThemeConfig) - Menu variant
└── Name, SchemeVersion
```

**ThemeConfig Properties:**
| Property | Type | Description |
|----------|------|-------------|
| `PrimaryAccentColor` | `Color` | Main accent color |
| `BackgroundColor` | `Color` | Window background |
| `TextColor` | `Color` | Primary text |
| `TabBarBackground` | `Color` | Tab bar background |
| `TabBodyBackground` | `Color` | Tab content background |
| `DefaultFontSize` | `int` | Base font size |
| `ButtonHeight` | `double` | Standard button height |

Themes are loaded from JSON files in `StaticData/Themes/System/`:
- `Modern-Dark.json`
- `Modern-Light.json`
- Custom OEM themes

### Custom Widgets

MatterControl provides specialized widgets beyond basic agg-sharp:

| Widget | Location | Purpose |
|--------|----------|---------|
| `DockingTabControl` | CustomWidgets/ | Collapsible side panel |
| `SolidSlider` | CustomWidgets/ | Value slider with fill |
| `DoubleSolidSlider` | CustomWidgets/ | Range slider (min/max) |
| `InlineEditControl` | CustomWidgets/ | Click-to-edit text |
| `DataViewGraph` | CustomWidgets/ | Real-time data graphing |
| `SlidePanelWidget` | CustomWidgets/ | Animated slide panel |
| `ColorPicker` | CustomWidgets/ColorPicker/ | HSV/RGB color selection |
| `ResizeContainer` | CustomWidgets/ResizeContainer/ | Resizable panels |

### Popover System

For context menus and tooltips:

```
Popover
├── ArrowDirection (Up, Down, Left, Right)
├── ArrowOffset
├── TagColor (accent color bar)
└── Content (any GuiWidget)

ClickablePopover extends Popover
└── Adds click-to-show behavior
```

Popovers are shown via `SystemWindow.ShowPopover()` with mate points:
```csharp
systemWindow.ShowPopover(
    new MatePoint(anchorWidget) { Mate = MateOptions(MateEdge.Right, MateEdge.Bottom) },
    new MatePoint(popover) { Mate = MateOptions(MateEdge.Left, MateEdge.Top) }
);
```

### Scaling and DPI

Device scaling is handled via `GuiWidget.DeviceScale`:

```csharp
// Set by user preference or TouchScreen detection
GuiWidget.DeviceScale = 1.3;  // 130% scaling

// All widgets should use scaled values
var buttonHeight = 30 * GuiWidget.DeviceScale;
```

Settings:
- `UserSettingsKey.ApplicationTextSize` - User-selected scale
- `UserSettingsKey.ApplicationUseHeigResDisplays` - Per-monitor DPI awareness

### Window Providers

Platform-specific window creation is abstracted:

| Provider | Assembly | Platform |
|----------|----------|----------|
| `WinformsSingleWindowProvider` | MatterControl.Winforms | Windows (primary) |
| `GlfwWindowProvider` | GlfwProvider | Cross-platform (secondary) |

Configuration via `AggContext.Config.ProviderTypes.SystemWindowProvider`.

### Design Rationale

**Custom UI Framework**: Using agg-sharp instead of WPF/WinForms/Qt provides:
- Identical rendering across platforms (pixel-perfect consistency)
- Full control over 3D viewport integration
- No dependency on platform-specific UI toolkits
- Easier custom widget creation

**Chrome-Style Tabs**: Familiar browser-like UX for managing multiple workspaces

**Theme System**: JSON-based themes allow:
- Easy customization by OEMs
- User-selectable themes
- Consistent styling across all widgets

**Popover System**: Provides contextual UI without modal dialogs, keeping workflow fluid

## Reference

### Core Classes

| Class | Location | Description |
|-------|----------|-------------|
| `MainViewWidget` | [PartPreviewWindow/MainViewWidget.cs](MatterControlLib/PartPreviewWindow/MainViewWidget.cs) | Main application view |
| `SimpleTabs` | [PartPreviewWindow/Tabs.cs](MatterControlLib/PartPreviewWindow/Tabs.cs) | Base tab implementation |
| `ChromeTabs` | [PartPreviewWindow/Tabs.cs](MatterControlLib/PartPreviewWindow/Tabs.cs) | Chrome-style tabs |
| `ThemeConfig` | Submodules/agg-sharp | Theme configuration |
| `ThemeSet` | [ApplicationView/Themes/ThemeSet.cs](MatterControlLib/ApplicationView/Themes/ThemeSet.cs) | Theme container |
| `ThemeConfigExtensions` | [ApplicationView/Themes/ThemeConfigExtensions.cs](MatterControlLib/ApplicationView/Themes/ThemeConfigExtensions.cs) | Theme helpers |

### Key Widgets

| Class | Location | Description |
|-------|----------|-------------|
| `DockingTabControl` | [CustomWidgets/DockingTabControl.cs](MatterControlLib/CustomWidgets/DockingTabControl.cs) | Side panel docking |
| `SolidSlider` | [CustomWidgets/SolidSlider.cs](MatterControlLib/CustomWidgets/SolidSlider.cs) | Value slider |
| `InlineEditControl` | [CustomWidgets/InlineEditControl.cs](MatterControlLib/CustomWidgets/InlineEditControl.cs) | Click-to-edit |
| `Popover` | [PartPreviewWindow/Popover.cs](MatterControlLib/PartPreviewWindow/Popover.cs) | Floating panel |
| `SearchPanel` | [PartPreviewWindow/SearchPanel.cs](MatterControlLib/PartPreviewWindow/SearchPanel.cs) | Search UI |

### Layout Classes

| Class | Purpose |
|-------|---------|
| `FlowLayoutWidget` | Horizontal/vertical flow |
| `Toolbar` | Horizontal toolbar with items |
| `OverflowBar` | Toolbar with overflow menu |
| `SectionWidget` | Collapsible section |
| `ResizableSectionWidget` | Section with resize handle |

### Events

| Event | Source | Description |
|-------|--------|-------------|
| `ActiveTabChanged` | `SimpleTabs` | Tab selection changed |
| `WorkspacesChanged` | `ApplicationController` | Tab added/removed |
| `AnyPrinterSettingChanged` | `PrinterSettings` | Setting modified |
| `UiHintChanged` | `ApplicationController` | Status message update |