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:

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:

// 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	Main application view
SimpleTabs	PartPreviewWindow/Tabs.cs	Base tab implementation
ChromeTabs	PartPreviewWindow/Tabs.cs	Chrome-style tabs
ThemeConfig	Submodules/agg-sharp	Theme configuration
ThemeSet	ApplicationView/Themes/ThemeSet.cs	Theme container
ThemeConfigExtensions	ApplicationView/Themes/ThemeConfigExtensions.cs	Theme helpers

Key Widgets

Class	Location	Description
DockingTabControl	CustomWidgets/DockingTabControl.cs	Side panel docking
SolidSlider	CustomWidgets/SolidSlider.cs	Value slider
InlineEditControl	CustomWidgets/InlineEditControl.cs	Click-to-edit
Popover	PartPreviewWindow/Popover.cs	Floating panel
SearchPanel	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