mattercontrol/research/14-utilities.md

Utilities & Helpers

Summary

MatterControl includes various utility classes and helper systems supporting caching, localization, networking, thumbnail generation, and common operations used throughout the application.

Technical Description

Web Cache

WebCache provides cached HTTP requests:

public static class WebCache
{
    public static Task<string> RetrieveText(string url);
    public static Task<ImageSequence> RetrieveImageSquenceAsync(string url);
    public static void ClearCache();
}

Features:

• Local file caching
• Configurable expiration
• Network error handling

Localization

The Localizations library handles internationalization:

string localized = "Text to translate".Localize();

Components:

• .po file format
• Runtime language switching
• Fallback to English

Thumbnail Generation

ThumbnailsConfig manages thumbnail creation:

public class ThumbnailsConfig
{
    public ImageBuffer LoadCachedThumbnail(ILibraryItem item, int width, int height);
    public Task<ImageBuffer> GetThumbnail(ILibraryItem item, int width, int height);
    public void Shutdown();
}

Sources:

1. Cached in database
2. Embedded in file (3MF, AMF)
3. Rendered from mesh
4. Default icon

Threading Utilities

UiThread ensures UI thread execution:

UiThread.RunOnIdle(() => {
    // UI operations
});

UiThread.CurrentTimerMs; // High-resolution timer

Safe Collections

Thread-safe collection wrappers:

public class SafeList<T> : IEnumerable<T>
{
    public void Add(T item);
    public bool Remove(T item);
    public void Clear();
}

Running Tasks

RunningTasksConfig manages background operations:

Tasks.Execute(
    "Task Name",
    owner,
    async (reporter, cancellationToken) => {
        reporter?.Invoke(0.5, "Progress message");
    },
    taskActions: new RunningTaskOptions()
    {
        PauseAction = () => { /* pause */ },
        StopAction = (abort) => { /* stop */ }
    });

Help System

HelpIndex provides searchable help:

public static class HelpIndex
{
    public static bool IndexExists { get; }
    public static Task RebuildIndex();
    public static IEnumerable<SearchResult> Search(string query);
}

Uses Lucene.Net for full-text search.

Markdown Support

MarkdownWidget renders markdown content:

var markdown = new MarkdownWidget(theme, scrollable: true)
{
    Markdown = "# Title\nContent here"
};

Uses Markdig parser with custom Agg renderer.

Vector Math

VectorMath library provides:

Type	Description
Vector2	2D vector
Vector3	3D vector
Matrix4X4	4x4 transformation matrix
Quaternion	Rotation representation
AxisAlignedBoundingBox	AABB bounds
Ray	Ray for intersections

Color Utilities

Color manipulation helpers:

Color.SetPreMultiply();
Color.GrayToColor(targetColor);
Color.AdjustLightness(factor);

File Utilities

Common file operations:

Class	Purpose
AggContext.FileDialogs	File open/save dialogs
StaticData	Resource file access
ApplicationDataStorage	App data paths

Extension Methods

Various extension helpers:

Extension	Purpose
string.Localize()	Translation
GuiWidget.AnchorAll()	Layout shortcut
IEnumerable.IndexOf()	Index finding
Color.WithAlpha()	Alpha adjustment

Clipboard Integration

System clipboard access:

Clipboard.Instance.SetText(text);
string text = Clipboard.Instance.GetText();
bool hasImage = Clipboard.Instance.ContainsImage;

Platform Abstraction

INativePlatformFeatures interface:

Feature	Description
OpenUrlInBrowser()	Launch browser
IsNetworkConnected()	Network check
GetSystemFonts()	Font enumeration
GetSerialPorts()	Serial port list

Design Rationale

Static Utility Classes: Common operations as static helpers:

• Easy access throughout codebase
• No instantiation overhead
• Clear naming conventions

Thread-Safe Collections: SafeList/SafeDictionary:

• Prevent race conditions
• Simple API
• Consistent behavior

Caching: WebCache and thumbnails:

• Improved performance
• Offline capability
• Reduced bandwidth

Reference

Core Utilities

Class	Location	Description
WebCache	Utilities/WebCache.cs	HTTP caching
UiThread	Submodules/agg-sharp	UI thread helper
SafeList<T>	Submodules/agg-sharp	Thread-safe list

Thumbnails

Class	Location	Description
ThumbnailsConfig	Library/ThumbnailsConfig.cs	Thumbnail manager
MeshThumbnails	Submodules/agg-sharp	Mesh rendering

Tasks

Class	Location	Description
RunningTasksConfig	PartPreviewWindow/RunningTasksConfig.cs	Task manager
RunningTaskOptions	PartPreviewWindow/RunningTaskOptions.cs	Task options

Help

Class	Location	Description
HelpIndex	Library/HelpIndex.cs	Help search
MarkdownWidget	Submodules/agg-sharp/MarkdigAgg	Markdown display

Math

Class	Location	Description
Vector3	Submodules/agg-sharp/VectorMath	3D vector
Matrix4X4	Submodules/agg-sharp/VectorMath	Transform matrix
AxisAlignedBoundingBox	Submodules/agg-sharp/VectorMath	AABB