176 lines
5 KiB
Markdown
176 lines
5 KiB
Markdown
# Plugin System
|
|
|
|
## Summary
|
|
|
|
MatterControl supports extensibility through plugin hooks, registered callbacks, and editor extensions. While not a traditional assembly-loading plugin system, it provides extension points for OEM customization, cloud services integration, and custom design tools.
|
|
|
|
## Technical Description
|
|
|
|
### Extension Points
|
|
|
|
The application provides several extension mechanisms:
|
|
|
|
```
|
|
ApplicationController
|
|
├── Plugin Delegates (cloud features)
|
|
├── Library.MenuExtensions (context menus)
|
|
├── EditorExtensions (property editors)
|
|
└── SceneOperations (design tools)
|
|
```
|
|
|
|
### Delegate-Based Plugins
|
|
|
|
`ApplicationController` exposes `Func`/`Action` delegates for plugin integration:
|
|
|
|
| Delegate | Type | Purpose |
|
|
|----------|------|---------|
|
|
| `GetPrinterProfileAsync` | `Func<PrinterInfo, string, Task<PrinterSettings>>` | Cloud profile retrieval |
|
|
| `SyncCloudProfiles` | `Func<string, Action<double,string>, Task>` | Profile sync |
|
|
| `GetPublicProfileList` | `Func<Task<OemProfileDictionary>>` | Public profile listing |
|
|
| `DownloadPublicProfileAsync` | `Func<string, Task<PrinterSettings>>` | Profile download |
|
|
| `GuestUserActive` | `Func<bool>` | Auth check |
|
|
| `GetAuthPage` | `Func<AuthenticationContext, DialogPage>` | Auth dialog |
|
|
| `UserHasPermission` | `Func<IObject3D, bool>` | Permission check |
|
|
| `UserHasPro` | `Func<bool>` | License validation |
|
|
| `PushPrintTaskToServer` | `Func<PrintTask, Task<Dictionary<string,string>>>` | Cloud tracking |
|
|
|
|
### Editor Extensions
|
|
|
|
Custom property editors registered via `EditorExtensionsConfig`:
|
|
|
|
```csharp
|
|
EditorExtensions.RegisterFactory((theme, undoBuffer) => new SheetEditor());
|
|
EditorExtensions.RegisterFactory((theme, undoBuffer) => new PropertyEditor(theme, undoBuffer));
|
|
```
|
|
|
|
**IObject3DEditor Interface:**
|
|
```csharp
|
|
public interface IObject3DEditor
|
|
{
|
|
string Name { get; }
|
|
bool Unlocked { get; }
|
|
GuiWidget Create(IObject3D item, UndoBuffer undoBuffer, ThemeConfig theme);
|
|
}
|
|
```
|
|
|
|
### Library Menu Extensions
|
|
|
|
Add custom actions to library context menus:
|
|
|
|
```csharp
|
|
Library.MenuExtensions.Add(new LibraryAction()
|
|
{
|
|
Title = "Custom Action",
|
|
Action = (items, library) => { /* implementation */ },
|
|
IsEnabled = (items, library) => true
|
|
});
|
|
```
|
|
|
|
### Scene Operations
|
|
|
|
Register custom design tools via `SceneOperations`:
|
|
|
|
```csharp
|
|
SceneOperations.RegisterOperation(
|
|
new SceneSelectionOperation()
|
|
{
|
|
Title = "Custom Operation",
|
|
Icon = iconImage,
|
|
Action = (sceneContext) => { /* implementation */ }
|
|
});
|
|
```
|
|
|
|
### OEM Customization
|
|
|
|
OEMs can customize via static data:
|
|
|
|
```
|
|
StaticData/
|
|
├── OEMSettings/
|
|
│ ├── OEMProfile.json (branding)
|
|
│ └── toc.json (help content)
|
|
├── Printers/
|
|
│ └── {OEM}/ (printer profiles)
|
|
└── Themes/
|
|
└── System/ (custom themes)
|
|
```
|
|
|
|
**OEMProfile.json:**
|
|
```json
|
|
{
|
|
"ShowHelpOption": true,
|
|
"ShowAuthenticationDialog": true,
|
|
"ShowGettingStarted": true,
|
|
"WindowTitleExtra": "OEM Edition"
|
|
}
|
|
```
|
|
|
|
### Content Providers
|
|
|
|
Register custom file format handlers:
|
|
|
|
```csharp
|
|
Library.ContentProviders.Add("custom", new CustomContentProvider());
|
|
```
|
|
|
|
**IContentProvider Interface:**
|
|
```csharp
|
|
public interface IContentProvider
|
|
{
|
|
Task<IObject3D> LoadAsync(Stream stream, CancellationToken cancellationToken);
|
|
Task SaveAsync(IObject3D object3D, Stream stream);
|
|
}
|
|
```
|
|
|
|
### Experimental Plugins
|
|
|
|
The `Plugins/Experimental` directory contains optional features:
|
|
|
|
| Plugin | Purpose |
|
|
|--------|---------|
|
|
| Part Sheet | Part information sheets |
|
|
| Custom experimental features | Beta functionality |
|
|
|
|
### Design Rationale
|
|
|
|
**Delegate Pattern**: Using function delegates instead of interfaces:
|
|
- Simplifies optional feature implementation
|
|
- No assembly scanning required
|
|
- Runtime flexibility
|
|
|
|
**Static Data Customization**: File-based OEM configuration:
|
|
- No code changes needed
|
|
- Easy deployment
|
|
- Clear separation of concerns
|
|
|
|
**Registration Patterns**: Factory/registration for extensions:
|
|
- Type-safe
|
|
- Discovery at startup
|
|
- Controlled lifecycle
|
|
|
|
## Reference
|
|
|
|
### Core Classes
|
|
|
|
| Class | Location | Description |
|
|
|-------|----------|-------------|
|
|
| `ApplicationController` | [ApplicationView/ApplicationController.cs](MatterControlLib/ApplicationView/ApplicationController.cs) | Plugin delegates |
|
|
| `EditorExtensionsConfig` | [DesignTools/EditorExtensionsConfig.cs](MatterControlLib/DesignTools/EditorExtensionsConfig.cs) | Editor registry |
|
|
| `SceneOperations` | [ApplicationView/SceneOperations.cs](MatterControlLib/ApplicationView/SceneOperations.cs) | Operations registry |
|
|
| `OemSettings` | [SettingsManagement/OemSettings.cs](MatterControlLib/SettingsManagement/OemSettings.cs) | OEM configuration |
|
|
|
|
### Interfaces
|
|
|
|
| Interface | Purpose |
|
|
|-----------|---------|
|
|
| `IObject3DEditor` | Custom object editor |
|
|
| `IContentProvider` | File format handler |
|
|
| `INativePlatformFeatures` | Platform features |
|
|
|
|
### Extension Directories
|
|
|
|
| Directory | Purpose |
|
|
|-----------|---------|
|
|
| `Plugins/Experimental/` | Beta features |
|
|
| `StaticData/OEMSettings/` | OEM configuration |
|
|
| `StaticData/Themes/` | Custom themes |
|