# Application Controller

## Summary

The `ApplicationController` is the central singleton orchestrating all major application functionality in MatterControl. It manages workspaces, printers, library containers, tasks, theming, and serves as the plugin registration point for extensibility.

## Technical Description

### Singleton Architecture

`ApplicationController` uses a lazy singleton pattern accessed via `ApplicationController.Instance`. The constructor is private, ensuring only one instance exists throughout the application lifecycle. This design:

- Provides a single coordination point for all subsystems
- Enables plugins to register callbacks and hooks
- Maintains consistent state across the application
- Simplifies cross-component communication

### Workspace Management

The application uses an `ObservableCollection<PartWorkspace>` to manage open tabs:

```
PartWorkspace
├── SceneContext (ISceneContext) - 3D scene editing context
├── Printer (PrinterConfig) - Associated printer (null for design-only tabs)
├── LibraryView (ILibraryContext) - Library browsing context
├── Name - Display name for the tab
└── ContentPath - Path to source file
```

**Workspace Types:**
1. **Design Workspaces**: `Printer == null`, standalone 3D design editing
2. **Printer Workspaces**: `Printer != null`, tied to a specific printer for printing

**Persistence**: Workspace layouts are persisted to `OpenTabsPath` as JSON when:
- Tabs are added/removed (via `CollectionChanged` event)
- Application closes
- User explicitly saves

### Library System Integration

ApplicationController initializes and manages the library hierarchy:

```
Library.RootLibaryContainer
├── Computer (FileSystemContainer)
├── Local Library (SqliteLibraryContainer) - if items exist
├── Queue (FileSystemContainer)
├── Bundled Parts (BundledPartsCollectionContainer)
├── Custom Library Folders (from CustomLibraryFoldersPath)
└── History (RootHistoryContainer)
```

Content providers are registered for file types:
| Extensions | Provider |
|------------|----------|
| stl, obj, 3mf, amf, mcx | `MeshContentProvider` |
| gcode | `GCodeContentProvider` |
| png, gif, jpg, jpeg | `ImageContentProvider` |
| scad | `OpenScadContentProvider` |

### Task Management System

The `Tasks` property (`RunningTasksConfig`) provides background task execution:

```csharp
Tasks.Execute("Task Name", owner, async (progress, cancellationToken) => {
    // Background work with progress reporting
    progress?.Invoke(0.5, "Halfway done");
});
```

Features:
- Progress reporting with percentage and status text
- Cancellation support
- Optional pause/resume/stop actions
- Visual task display in UI via `RunningTasksWidget`

### Plugin Registration Points

ApplicationController exposes several `Func` and `Action` delegates for plugin integration:

| Property | Type | Purpose |
|----------|------|---------|
| `GetPrinterProfileAsync` | `Func<PrinterInfo, string, Task<PrinterSettings>>` | Cloud profile retrieval |
| `SyncCloudProfiles` | `Func<string, Action<double,string>, Task>` | Cloud sync execution |
| `GetPublicProfileList` | `Func<Task<OemProfileDictionary>>` | Public profile listing |
| `DownloadPublicProfileAsync` | `Func<string, Task<PrinterSettings>>` | Public profile download |
| `GuestUserActive` | `Func<bool>` | Authentication state check |
| `GetAuthPage` | `Func<AuthenticationContext, DialogPage>` | Auth dialog factory |
| `UserHasPermission` | `Func<IObject3D, bool>` | Object permission check |
| `UserHasPro` | `Func<bool>` | Pro license validation |
| `PushPrintTaskToServer` | `Func<PrintTask, Task<Dictionary<string,string>>>` | Cloud print tracking |

### Font Management

The `TypeFaceCache` dictionary manages loaded fonts with lazy loading:

1. Static fonts loaded at startup (Liberation Sans/Mono)
2. User fonts loaded from `ApplicationFontsDataPath` on demand
3. System fonts loaded from Windows Fonts folder as fallback
4. Falls back to Liberation_Sans if font not found

### Event System

Key events for application coordination:

| Event | Purpose |
|-------|---------|
| `WorkspacesChanged` | Tab added/removed/restored |
| `CloudSyncStatusChanged` | Cloud sync state changes |
| `DoneReloadingAll` | Full UI reload completed |
| `ActiveProfileModified` | Printer profile changed |
| `ReloadSettingsTriggered` | Settings panel refresh needed |
| `ShellFileOpened` | External file opened |
| `AnyPrintStarted/Canceled/Complete` | Print lifecycle |
| `ApplicationError` | Error logging |
| `ApplicationEvent` | General event logging |

### AppContext Static Class

`AppContext` provides global application state:

| Property | Type | Description |
|----------|------|-------------|
| `Platform` | `INativePlatformFeatures` | Platform-specific functionality |
| `Options` | `MatterControlOptions` | Runtime options |
| `IsLoading` | `bool` | Application loading state |
| `RootSystemWindow` | `SystemWindow` | Main window reference |
| `Theme` | `ThemeConfig` | Current theme |
| `MenuTheme` | `ThemeConfig` | Menu theme variant |
| `ThemeProviders` | `Dictionary<string, IColorTheme>` | Available themes |

### Design Rationale

**Singleton vs Dependency Injection**: The singleton pattern was chosen over DI for simplicity and because the application has a single-user, single-window model. All state is naturally global.

**Plugin Delegates vs Interfaces**: Using `Func`/`Action` delegates instead of interfaces for plugins allows:
- Optional plugin features (null = not implemented)
- Simple registration without assembly scanning
- Runtime flexibility in plugin loading

**Observable Workspaces**: Using `ObservableCollection` enables automatic UI updates when tabs change without manual event wiring in the view layer.

## Reference

### Core Classes

| Class | Location | Description |
|-------|----------|-------------|
| `ApplicationController` | [ApplicationView/ApplicationController.cs](MatterControlLib/ApplicationView/ApplicationController.cs) | Central singleton |
| `AppContext` | [ApplicationView/AppContext.cs](MatterControlLib/ApplicationView/AppContext.cs) | Global static state |
| `PartWorkspace` | [ApplicationView/PartWorkspace.cs](MatterControlLib/ApplicationView/PartWorkspace.cs) | Tab/workspace definition |
| `WorkspacesChangedEventArgs` | [ApplicationView/WorkspacesChangedEventArgs.cs](MatterControlLib/ApplicationView/WorkspacesChangedEventArgs.cs) | Workspace change event |

### Key Properties

| Property | Type | Description |
|----------|------|-------------|
| `Instance` | `ApplicationController` | Singleton accessor |
| `Workspaces` | `ObservableCollection<PartWorkspace>` | Open tabs |
| `ActivePrinters` | `IEnumerable<PrinterConfig>` | Connected printers |
| `Library` | `LibraryConfig` | Library configuration |
| `LibraryTabContext` | `ILibraryContext` | SaveAs library context |
| `Tasks` | `RunningTasksConfig` | Background task manager |
| `Thumbnails` | `ThumbnailsConfig` | Thumbnail generation |
| `EditorExtensions` | `EditorExtensionsConfig` | Editor plugin registry |
| `Theme` | `ThemeConfig` | Current theme |
| `MenuTheme` | `ThemeConfig` | Menu theme |
| `MainView` | `MainViewWidget` | Main UI widget |
| `HelpArticles` | `HelpArticle` | Help content |
| `TypeFaceCache` | `Dictionary<string, TypeFace>` | Loaded fonts |

### Key Methods

| Method | Description |
|--------|-------------|
| `OnWorkspacesChanged()` | Fire workspace change event |
| `ClosePrinter()` | Disconnect and close printer |
| `ExportLibraryItems()` | Export items to file |
| `PersistOpenTabsLayout()` | Save workspace state |
| `PersistPrintTabsContent()` | Save printer workspace content |
| `ReloadSettings()` | Refresh settings UI |
| `ShowNotification()` | Display timed notification |
| `Shutdown()` | Graceful application shutdown |
| `GetTypeFace()` | Lazy-load font by name |
| `GetWorkspaceActions()` | Build context menu actions |
| `LaunchBrowser()` | Open URL in default browser |

### Supporting Classes

| Class | Location | Description |
|-------|----------|-------------|
| `RunningTasksConfig` | [PartPreviewWindow/RunningTasksConfig.cs](MatterControlLib/PartPreviewWindow/RunningTasksConfig.cs) | Task execution |
| `LibraryConfig` | [Library/LibraryConfig.cs](MatterControlLib/Library/LibraryConfig.cs) | Library management |
| `ThumbnailsConfig` | [Library/ThumbnailsConfig.cs](MatterControlLib/Library/ThumbnailsConfig.cs) | Thumbnail generation |
| `EditorExtensionsConfig` | [DesignTools/EditorExtensionsConfig.cs](MatterControlLib/DesignTools/EditorExtensionsConfig.cs) | Editor plugins |