327 lines
13 KiB
Markdown
327 lines
13 KiB
Markdown
# API reference (`LiveWall.Sdk` 1.0)
|
||
|
||
Everything below lives in the namespace `LiveWall.Sdk`, in the single assembly `LiveWall.Sdk.dll`
|
||
(target `net8.0-windows`, WPF). Nullable reference types are enabled.
|
||
|
||
---
|
||
|
||
## `PluginApi` (static)
|
||
|
||
| Member | Value | Meaning |
|
||
|---|---|---|
|
||
| `Version` | `"1.0"` | Contract version. Must match the `apiVersion` in `plugin.json`. |
|
||
| `HostVersion` | e.g. `"1.8.0"` | LiveWall version this SDK shipped with. Informational. |
|
||
|
||
## `PluginPermission` (`[Flags]`)
|
||
|
||
| Flag | Dialog text |
|
||
|---|---|
|
||
| `None` | — |
|
||
| `ReadWallpaper` | Read your current wallpaper, playback state and settings |
|
||
| `ControlPlayback` | Start, stop, skip and replace your wallpaper |
|
||
| `DesktopOverlay` | Draw content on top of your desktop wallpaper |
|
||
| `SettingsUi` | Add pages to the LiveWall settings window |
|
||
| `Commands` | Add commands to LiveWall |
|
||
| `TrayMenu` | Add entries to the LiveWall tray menu |
|
||
| `Hotkeys` | Register system-wide keyboard shortcuts |
|
||
| `FileSystem` | Read and write files on your computer |
|
||
| `Network` | Connect to the internet |
|
||
| `Renderer` | Take over wallpaper playback with its own renderer |
|
||
| `Filters` | Rewrite or block wallpaper changes |
|
||
| `All` | Union of all of the above |
|
||
|
||
`PluginPermissionInfo.Describe(PluginPermission)` returns the text for one flag;
|
||
`PluginPermissionInfo.Expand(PluginPermission)` returns `(Permission, Description)` pairs — this is
|
||
what the warning dialog iterates.
|
||
|
||
> Permissions are **declarations**, not a sandbox. The host enforces them where it can (it will refuse
|
||
> to register an overlay without `DesktopOverlay`, or to change the wallpaper without
|
||
> `ControlPlayback`), but nothing stops a determined plugin from calling Win32 directly. They exist so
|
||
> the user knows what they are agreeing to — see [security.md](security.md).
|
||
|
||
---
|
||
|
||
## `ILiveWallPlugin`
|
||
|
||
```csharp
|
||
public interface ILiveWallPlugin
|
||
{
|
||
void Initialize(IPluginContext context);
|
||
void Shutdown();
|
||
}
|
||
```
|
||
|
||
* One public parameterless class per assembly, named by `"type"` in `plugin.json`.
|
||
* `Initialize` runs on the WPF UI thread. Register extensions and subscribe to events here; do not
|
||
block (no long `Thread.Sleep`, no `.Result`), and start expensive work on a background task.
|
||
* Any exception escaping `Initialize` marks the plugin **Failed**; it is never retried automatically
|
||
and the message is shown in the Plugins tab.
|
||
* `Shutdown` may run on any thread during unload/exit. It must not block for long and must not throw.
|
||
|
||
## `IPluginContext`
|
||
|
||
| Member | Type | Notes |
|
||
|---|---|---|
|
||
| `Info` | `PluginInfo` | Identity, paths, hash, verification flag |
|
||
| `Log` | `IPluginLog` | Prefixed with your plugin id, written to LiveWall's log |
|
||
| `Storage` | `IPluginStorage` | Per-plugin JSON key/value store |
|
||
| `Settings` | `ISettingsSnapshot` | Read-only settings snapshot (a fresh one each get) |
|
||
| `Host` | `IHostActions` | Actions in the host |
|
||
| `Events` | `IPluginEvents` | Subscribe / publish |
|
||
| `Extensions` | `IPluginRegistrar` | Register overlays, pages, commands, filters, renderers, hotkeys |
|
||
| `ShutdownToken` | `CancellationToken` | Cancelled when the plugin is being unloaded |
|
||
|
||
## `PluginInfo`
|
||
|
||
| Member | Type | Notes |
|
||
|---|---|---|
|
||
| `Id`, `Name`, `Version`, `Author`, `Description`, `Homepage` | `string` | From `plugin.json` |
|
||
| `ApiVersion` | `string` | Version the plugin declared (normalised to `"1.0"`) |
|
||
| `Permissions` | `PluginPermission` | Parsed from the manifest |
|
||
| `Folder` | `string` | Absolute plugin folder |
|
||
| `AssemblyPath` | `string` | Absolute path of the entry assembly |
|
||
| `Sha256` | `string` | Lower-case hex SHA-256 of the assembly |
|
||
| `Verified` | `bool` | `true` when this exact hash was approved on this machine |
|
||
|
||
## `IPluginLog`
|
||
|
||
```csharp
|
||
void Debug(string message);
|
||
void Info(string message);
|
||
void Warn(string message);
|
||
void Error(string message, Exception? exception = null);
|
||
```
|
||
|
||
Lines land in `%APPDATA%\LiveWall\logs\livewall-YYYYMMDD.log` as
|
||
`[com.example.clock] your message`. `Debug` only writes when LiveWall's debug logging is on.
|
||
|
||
## `IPluginStorage`
|
||
|
||
| Member | Notes |
|
||
|---|---|
|
||
| `string DataFolder` | `%APPDATA%\LiveWall\plugin-data\<id>\`, created on demand |
|
||
| `T? Get<T>(string key, T? fallback = default)` | Deserialised with `System.Text.Json` |
|
||
| `void Set<T>(string key, T value)` | Buffered; flushed automatically (debounced) and on shutdown |
|
||
| `bool Remove(string key)` | Removes one key |
|
||
| `IReadOnlyCollection<string> Keys` | All keys in the store |
|
||
| `string PathFor(string fileName)` | Absolute path inside `DataFolder`; parent dirs created |
|
||
| `void Flush()` | Force a write now |
|
||
|
||
The store is one JSON object per plugin (`storage.json`). Concurrent `Set` calls from different
|
||
threads are safe. Keep it small (it is rewritten wholesale).
|
||
|
||
## `ISettingsSnapshot`
|
||
|
||
| Member | Type | Notes |
|
||
|---|---|---|
|
||
| `SnapshotId` | `Guid` | Changes on every snapshot |
|
||
| `SourceKind` | `string` | `Video`, `AnimatedGif`, `Image`, `YouTube`, `WebPage` |
|
||
| `SourceLocation` | `string` | File path or URL |
|
||
| `Muted` | `bool` | |
|
||
| `Volume` | `double` | 0–100 |
|
||
| `Speed` | `double` | 0.25–4 |
|
||
| `Loop` | `bool` | |
|
||
| `InteractiveMode` | `bool` | `true` when the wallpaper accepts clicks |
|
||
| `Paused` | `bool` | |
|
||
| `DimPercent` | `int` | 0–100 |
|
||
| `DimColor` | `string` | `#RRGGBB` |
|
||
| `DisplayDevices` | `IReadOnlyList<string>` | Device names, primary first |
|
||
|
||
## `WallpaperState`
|
||
|
||
`Kind`, `Source`, `Title`, `IsPlaying`, `IsPaused`, `IsInteractive`, `SuppliedByPlugin`,
|
||
`RendererName`. This is `IHostActions.Current`.
|
||
|
||
## `IHostActions`
|
||
|
||
| Member | Permission | Behaviour |
|
||
|---|---|---|
|
||
| `WallpaperState Current { get; }` | `ReadWallpaper` | `Kind`/`Source` empty when unknown |
|
||
| `void SetWallpaper(WallpaperRequest)` | `ControlPlayback` | Routes through the normal filter chain then reloads |
|
||
| `void Play()` | `ControlPlayback` | |
|
||
| `void Pause()` | `ControlPlayback` | |
|
||
| `void TogglePause()` | `ControlPlayback` | |
|
||
| `void NextWallpaper()` | `ControlPlayback` | Next playlist entry |
|
||
| `void ReloadWallpaper()` | `ControlPlayback` | Re-applies the current source |
|
||
| `void Reattach()` | — | Re-parents the wallpaper window to WorkerW |
|
||
| `void OpenSettings()` | — | Shows the settings window |
|
||
| `void SetStatus(string)` | — | Status line text |
|
||
| `void ShowNotification(string, string)` | — | Balloon, respects the user's notification setting |
|
||
| `void SetOverlayVisible(bool)` | `DesktopOverlay` | Shows/hides **this plugin's** overlays |
|
||
|
||
Calls the plugin lacks permission for are logged and ignored — they never throw.
|
||
|
||
## `WallpaperRequest`
|
||
|
||
```csharp
|
||
public sealed class WallpaperRequest
|
||
{
|
||
public string Kind { get; set; } = "Custom"; // Video | AnimatedGif | Image | YouTube | WebPage | Custom
|
||
public string Source { get; set; } = ""; // path, URL, or anything your renderer understands
|
||
public string Title { get; set; } = "";
|
||
public Dictionary<string, string> Metadata { get; } // free-form, survives filters, not persisted
|
||
public WallpaperRequest Clone();
|
||
}
|
||
```
|
||
|
||
`Metadata` keys are case-insensitive. Use it to hand parameters to your own renderer.
|
||
|
||
---
|
||
|
||
## Extension points
|
||
|
||
### `IPluginRegistrar`
|
||
|
||
```csharp
|
||
void AddOverlay(IWallpaperOverlay overlay); // DesktopOverlay
|
||
void RemoveOverlay(IWallpaperOverlay overlay);
|
||
void AddSettingsPage(IPluginSettingsPage page); // SettingsUi
|
||
void AddCommand(PluginCommand command); // Commands / TrayMenu
|
||
void AddFilter(IWallpaperFilter filter); // Filters
|
||
void AddRenderer(IWallpaperRendererPlugin renderer); // Renderer
|
||
void AddHotkey(PluginHotkey hotkey); // Hotkeys
|
||
```
|
||
|
||
Registering without the matching permission logs a warning and does nothing.
|
||
|
||
### `IWallpaperOverlay`
|
||
|
||
```csharp
|
||
string Name { get; }
|
||
FrameworkElement CreateView(OverlayContext context);
|
||
void Update(OverlayState state);
|
||
void OnVisibilityChanged(bool visible) { } // default: do nothing
|
||
```
|
||
|
||
* `CreateView` is called once per display, on the UI thread, when the overlay is attached.
|
||
* The element is stretched to the display's DIP size and **is not hit-testable by default** — a
|
||
click on your overlay falls through to the desktop. If you need clicks, use `InteractiveMode` plus a
|
||
renderer instead; the overlay layer is deliberately click-through.
|
||
* Keep it cheap: it repaints whenever anything below it repaints. Avoid `Effect`s on large elements,
|
||
prefer text and simple shapes, and stop timers in `OnVisibilityChanged(false)`.
|
||
|
||
`OverlayContext`: `DisplayIndex`, `DeviceName`, `Width`, `Height` (DIP), `DpiScale`, `Primary`.
|
||
|
||
`OverlayState`: `Kind`, `Source`, `Title`, `IsPlaying`, `IsPaused`, `IsInteractive`, `TimestampUtc`.
|
||
|
||
### `IPluginSettingsPage`
|
||
|
||
```csharp
|
||
string Title { get; }
|
||
string Description { get; }
|
||
FrameworkElement CreateView();
|
||
```
|
||
|
||
Pages appear under **Plugins ▸ Installed plugins ▸ Settings**. Several pages = several tabs in one
|
||
window. `CreateView` is called when the window opens, so build fresh controls and read your state
|
||
there. The element tree is LiveWall's; if it throws, the message is shown in the page instead of
|
||
crashing the app.
|
||
|
||
Style your controls like the rest of the app — `(Brush)Application.Current.Resources["TextBrush"]`,
|
||
`["TextDim"]`, `["BgField"]`, `["AccentBrush"]`, `["DangerBrush"]`, and the `Card`, `Hint`,
|
||
`SectionTitle`, `AccentButton`, `GhostButton`, `TinyButton` styles. They are always present.
|
||
|
||
### `PluginCommand`
|
||
|
||
```csharp
|
||
new PluginCommand("id", "Human title", ctx => { /* ... */ })
|
||
{
|
||
Category = "Clock", // optional grouping label
|
||
CanExecute = () => true // optional; evaluated when the menu opens
|
||
};
|
||
```
|
||
|
||
`ctx.Plugin` is the plugin's `IPluginContext`, `ctx.Host` is `IHostActions`. Commands appear in
|
||
**Plugins ▸ Plugin commands** with a **Run** button; those with the `TrayMenu` permission also appear
|
||
in the tray menu under **Plugins**.
|
||
|
||
### `PluginHotkey`
|
||
|
||
```csharp
|
||
new PluginHotkey("clock.toggle24", "Ctrl+Alt+F9", () => { /* ... */ })
|
||
{
|
||
Description = "Clock: toggle 12/24 hour" // tooltip text in the hotkey list
|
||
};
|
||
```
|
||
|
||
Gestures accept the same syntax as LiveWall's own hotkeys: modifiers `Ctrl`/`Control`, `Alt`,
|
||
`Shift`, `Win` plus one key (`F1`–`F24`, letters, digits, `Space`, `Pause`, `PrintScreen`,
|
||
`Insert`/`Delete`/`Home`/`End`/`PageUp`/`PageDown`, arrows, numpad keys). Registration failure (the
|
||
combination is taken) is logged and reported — LiveWall's own hotkeys always win.
|
||
|
||
### `IWallpaperFilter`
|
||
|
||
```csharp
|
||
int Priority { get; } // higher runs first
|
||
WallpaperRequest Apply(WallpaperRequest request, IHostActions host);
|
||
```
|
||
|
||
Filters run in the UI thread **before** renderer selection, in descending `Priority` order (ties run in
|
||
registration order). Return the (possibly new) request; returning the argument unchanged leaves it
|
||
alone. Throwing removes your filter from that pass and is logged — other filters still run.
|
||
|
||
A filter can therefore: rewrite `Source` (resolve `ytsearch:` links, expand `%DATE%`), add
|
||
`Metadata`, or veto by returning the current state (`host.Current`).
|
||
|
||
### `IWallpaperRendererPlugin` / `IWallpaperRenderer`
|
||
|
||
```csharp
|
||
public interface IWallpaperRendererPlugin
|
||
{
|
||
string Name { get; }
|
||
int Priority { get; } // higher wins among plugins
|
||
bool CanRender(WallpaperRequest request);
|
||
IWallpaperRenderer Create();
|
||
}
|
||
|
||
public interface IWallpaperRenderer : IDisposable
|
||
{
|
||
FrameworkElement View { get; } // the wallpaper visual, keep it opaque
|
||
void Load(WallpaperRequest request); // throw to report a failure
|
||
void Play();
|
||
void Pause();
|
||
void Unload();
|
||
void ApplyPlayback(bool muted, double volume, double speed);
|
||
event EventHandler<string>? Failed;
|
||
event EventHandler? Ended;
|
||
}
|
||
```
|
||
|
||
LiveWall asks every renderer, highest `Priority` first, whether it `CanRender`s the request. The first
|
||
`true` wins and the built-in players (video/GIF/YouTube/web) are skipped — so a plugin can take over
|
||
sources LiveWall would otherwise handle. Then `Create()` is called once, `Load(request)` once per
|
||
source, and `View` is placed in the wallpaper window. `Failed`/`Ended` surface in the status line and
|
||
the log. `Dispose` is called when the renderer is replaced or the plugin unloads.
|
||
|
||
Remember: the wallpaper window is behind the desktop icons and **not** interactive unless
|
||
`InteractiveMode` is on.
|
||
|
||
---
|
||
|
||
## Events (`Events.cs`)
|
||
|
||
| Event | Payload |
|
||
|---|---|
|
||
| `AppStartedEvent` | `HostVersion`, `PluginApiVersion` |
|
||
| `AppStoppingEvent` | `Reason` |
|
||
| `WallpaperChangedEvent` | `Kind`, `Source`, `RendererName`, `FromPlugin` |
|
||
| `PlaybackChangedEvent` | `IsPlaying`, `IsPaused`, `Reason` |
|
||
| `InteractionChangedEvent` | `Interactive` |
|
||
| `SettingsChangedEvent` | `Property`, `Snapshot` |
|
||
| `DisplayChangedEvent` | `Devices`, `Reattached` |
|
||
| `SessionChangedEvent` | `Locked`, `OnBattery`, `RemoteSession` |
|
||
| `HostErrorEvent` | `Message`, `Source` |
|
||
| `PluginMessageEvent` | `FromPluginId`, `Topic`, `Payload` (string) |
|
||
|
||
```csharp
|
||
IDisposable Subscribe<TEvent>(Action<TEvent> handler) where TEvent : class;
|
||
void Publish<TEvent>(TEvent payload) where TEvent : class;
|
||
```
|
||
|
||
* Handlers always run on the WPF UI thread. Never block in one — bounce work to `Task.Run` if needed.
|
||
* Always keep the returned `IDisposable` and dispose it in `Shutdown`.
|
||
* `Publish` anything you like: it is a type-based bus, so you can define your own event classes for
|
||
plugin-to-plugin messaging (`PluginMessageEvent` is the conventional envelope).
|
||
* Publishing a host event type is allowed but only reaches other plugins — the host does not re-apply
|
||
it.
|