Window Framework for UI Toolkit v2.0.x
GWG.WindowFramework.Theming.IPlayerThemeAssetExtension Interface Reference

Optional raster-asset capability for compiled purchaser theme extensions. More...

Inheritance diagram for GWG.WindowFramework.Theming.IPlayerThemeAssetExtension:
Collaboration diagram for GWG.WindowFramework.Theming.IPlayerThemeAssetExtension:

Public Member Functions

IDisposable ApplyWithAssets (VisualElement scope, string sectionJson, IReadOnlyDictionary< string, Texture2D > images)
 Applies validated data and borrowed imported images within the purchaser scope.
IReadOnlyDictionary< string, string > DeclareImages (string sectionJson)
 Declares this section's logical image keys and relative raster filenames without acquiring resources.
string SnapshotWithAssets (VisualElement scope, Func< string, Texture2D, string > writeImage)
 Exports complete effective section data and independent effective raster images.
Public Member Functions inherited from GWG.WindowFramework.Theming.IPlayerThemeExtension
IDisposable Apply (VisualElement scope, string sectionJson)
 Applies already validated settings within an explicit scope.
string Snapshot (VisualElement scope)
 Exports current effective purchaser settings, including its authoritative defaults.
bool Validate (string sectionJson, out string error)
 Validates every supported key and explicit value without mutating UI or files.

Additional Inherited Members

Properties inherited from GWG.WindowFramework.Theming.IPlayerThemeExtension
string Namespace [get]
 Gets a stable dotted namespace, such as mygame.inventory.

Detailed Description

Optional raster-asset capability for compiled purchaser theme extensions.

WHY: use this rather than opening player paths or implementing a second image exporter. The framework validates declared images with its common path, header, count and decoded-memory limits, owns imported textures, and copies assets independently. Existing data-only IPlayerThemeExtension implementations remain unchanged. HOW: implement alongside your existing handler, register before discovery, declare stable logical image keys, consume borrowed textures in ApplyWithAssets, and export effective textures with the supplied writer. Player JSON never creates handlers. The original Validate/Apply/Snapshot methods remain the data-only API; implementations should explain/refuse asset-bearing use without a resource context, not open paths themselves.

// Section: { "slotImage": "Images/slot.png" }
// DeclareImages returns { ["slotImage"] = relativePath }.
// ApplyWithAssets uses images["slotImage"] as a borrowed texture (null means recoverable missing image).
// SnapshotWithAssets writes an effective texture:
// string relative = writeImage("slotImage", effectiveTexture);
// Return your bounded section JSON with slotImage = relative, or null for an explicit empty image.
// Returned application lease restores UI references BEFORE the framework releases folder textures.

Member Function Documentation

◆ ApplyWithAssets()

IDisposable GWG.WindowFramework.Theming.IPlayerThemeAssetExtension.ApplyWithAssets ( VisualElement scope,
string sectionJson,
IReadOnlyDictionary< string, Texture2D > images )

Applies validated data and borrowed imported images within the purchaser scope.

Parameters
scopeExplicit application subtree.
sectionJsonRecovered valid section; original source is never rewritten.
imagesDeclared logical keys mapped to textures or null for safe missing/corrupt files.
Returns
Non-null idempotent reversible lease.

Use application defaults for null resources. Never destroy borrowed textures. Undo partial mutations before throwing; Dispose must remove owned image references and preserve newer purchaser overrides.

Exceptions
ArgumentExceptionData or required application defaults are invalid.

◆ DeclareImages()

IReadOnlyDictionary< string, string > GWG.WindowFramework.Theming.IPlayerThemeAssetExtension.DeclareImages ( string sectionJson)

Declares this section's logical image keys and relative raster filenames without acquiring resources.

Parameters
sectionJsonRecovered, structurally validated section JSON.
Returns
Non-null bounded dictionary; omit absent/null image overrides. Keys are stable logical identifiers.

Validate known keys/types first. Paths remain untrusted until the framework validates them. PNG/JPG only; no URLs, SVG/fonts, bundles or arbitrary filesystem access. Declarations must be deterministic.

Exceptions
ArgumentExceptionSection cannot be interpreted safely.

◆ SnapshotWithAssets()

string GWG.WindowFramework.Theming.IPlayerThemeAssetExtension.SnapshotWithAssets ( VisualElement scope,
Func< string, Texture2D, string > writeImage )

Exports complete effective section data and independent effective raster images.

Parameters
scopeApplication subtree supplying effective values/defaults.
writeImageWrites a borrowed texture to staging and returns its safe relative filename. Supply one stable logical key per image. Null returns null without a file.
Returns
Bounded JSON object referencing only filenames returned by the writer.

The delegate is valid only during this call; never retain it. Do not return original-folder paths. Framework re-import validates declarations before commit. Copy failures leave sources unchanged.

Exceptions
InvalidOperationExceptionA complete safe snapshot is unavailable.