Class ViewEngine
Definition
Namespace: StardewUI.Framework.Api
Assembly: StardewUI.dll
Implementation for the public IViewEngine API.
Inheritance
Object ⇦ ViewEngine
Implements
IViewEngine
Members
Constructors
| Name | Description |
|---|---|
| ViewEngine(IAssetCache, IModHelper, IViewNodeFactory) | Initializes a new ViewEngine instance. |
Properties
| Name | Description |
|---|---|
| SourceResolver | Source resolver for resolving documents created by this view engine back to their original mod. |
Methods
| Name | Description |
|---|---|
| CreateDrawableFromAsset(string) | Creates an IViewDrawable from the StarML stored in a game asset, as provided by a mod via SMAPI or Content Patcher. |
| CreateDrawableFromMarkup(string) | Creates an IViewDrawable from arbitrary markup. |
| CreateMenuControllerFromAsset(string, Object) | Creates a menu from the StarML stored in a game asset, as provided by a mod via SMAPI or Content Patcher, and returns a controller for customizing the menu's behavior. |
| CreateMenuControllerFromMarkup(string, Object) | Creates a menu from arbitrary markup, and returns a controller for customizing the menu's behavior. |
| CreateMenuFromAsset(string, Object) | Creates a menu from the StarML stored in a game asset, as provided by a mod via SMAPI or Content Patcher. |
| CreateMenuFromMarkup(string, Object) | Creates a menu from arbitrary markup. |
| EnableHotReloading(string) | Starts monitoring this mod's directory for changes to assets managed by any of the Register methods, e.g. views and sprites. |
| PreloadAssets() | Begins preloading assets found in this mod's registered asset directories. |
| PreloadModels(Type) | Declares that the specified context types will be used as either direct arguments or subproperties in one or more subsequent CreateMenu or CreateDrawable APIs, and instructs the framework to begin inspecting those types and optimizing for later use. |
| RegisterCustomData(string, string) | Registers a mod directory to be searched for special-purpose mod data, i.e. that is not either views or sprites. |
| RegisterSprites(string, string) | Registers a mod directory to be searched for sprite (and corresponding texture/sprite sheet data) assets. |
| RegisterViews(string, string) | Registers a mod directory to be searched for view (StarML) assets. Uses the .sml extension. |
Details
Constructors
ViewEngine(IAssetCache, IModHelper, IViewNodeFactory)
Initializes a new ViewEngine instance.
public ViewEngine(StardewUI.Framework.Content.IAssetCache assetCache, StardewModdingAPI.IModHelper helper, StardewUI.Framework.Binding.IViewNodeFactory viewNodeFactory);
Parameters
assetCache IAssetCache
Cache for obtaining document assets. Used for asset-based views.
helper IModHelper
SMAPI mod helper for the API consumer mod (not for StardewUI).
viewNodeFactory IViewNodeFactory
Factory for creating and binding IViewNodes.
Properties
SourceResolver
Source resolver for resolving documents created by this view engine back to their original mod.
Property Value
Methods
CreateDrawableFromAsset(string)
Creates an IViewDrawable from the StarML stored in a game asset, as provided by a mod via SMAPI or Content Patcher.
Parameters
assetName string
The name of the StarML view asset in the content pipeline, e.g. Mods/MyMod/Views/MyView.
Returns
An IViewDrawable for drawing directly to the SpriteBatch of a rendering event or other draw handler.
Remarks
The Context and MaxSize can be provided after creation.
CreateDrawableFromMarkup(string)
Creates an IViewDrawable from arbitrary markup.
Parameters
markup string
The markup in StarML format.
Returns
An IViewDrawable for drawing directly to the SpriteBatch of a rendering event or other draw handler.
Remarks
The Context and MaxSize can be provided after creation.
Warning: Ad-hoc menus created this way cannot be cached, nor patched by other mods. Most mods should not use this API except for testing/experimentation.
CreateMenuControllerFromAsset(string, Object)
Creates a menu from the StarML stored in a game asset, as provided by a mod via SMAPI or Content Patcher, and returns a controller for customizing the menu's behavior.
public StardewUI.Framework.IMenuController CreateMenuControllerFromAsset(string assetName, System.Object context);
Parameters
assetName string
The name of the StarML view asset in the content pipeline, e.g. Mods/MyMod/Views/MyView.
context Object
The context, or "model", for the menu's view, which holds any data-dependent values. Note: The type must implement INotifyPropertyChanged in order for any changes to this data to be automatically reflected in the UI.
Returns
A controller object whose Menu is the created menu and whose other properties can be used to change menu-level behavior.
Remarks
The menu that is created is the same as the result of CreateMenuFromMarkup(string, Object). The menu is not automatically shown; to show it, use activeClickableMenu or equivalent.
CreateMenuControllerFromMarkup(string, Object)
Creates a menu from arbitrary markup, and returns a controller for customizing the menu's behavior.
public StardewUI.Framework.IMenuController CreateMenuControllerFromMarkup(string markup, System.Object context);
Parameters
markup string
The markup in StarML format.
context Object
The context, or "model", for the menu's view, which holds any data-dependent values. Note: The type must implement INotifyPropertyChanged in order for any changes to this data to be automatically reflected in the UI.
Returns
A controller object whose Menu is the created menu and whose other properties can be used to change menu-level behavior.
Remarks
Warning: Ad-hoc menus created this way cannot be cached, nor patched by other mods. Most mods should not use this API except for testing/experimentation.
CreateMenuFromAsset(string, Object)
Creates a menu from the StarML stored in a game asset, as provided by a mod via SMAPI or Content Patcher.
public StardewValley.Menus.IClickableMenu CreateMenuFromAsset(string assetName, System.Object context);
Parameters
assetName string
The name of the StarML view asset in the content pipeline, e.g. Mods/MyMod/Views/MyView.
context Object
The context, or "model", for the menu's view, which holds any data-dependent values. Note: The type must implement INotifyPropertyChanged in order for any changes to this data to be automatically reflected in the UI.
Returns
IClickableMenu
A menu object which can be shown using the game's standard menu APIs such as activeClickableMenu.
Remarks
Does not make the menu active. To show it, use activeClickableMenu or equivalent.
CreateMenuFromMarkup(string, Object)
Creates a menu from arbitrary markup.
public StardewValley.Menus.IClickableMenu CreateMenuFromMarkup(string markup, System.Object context);
Parameters
markup string
The markup in StarML format.
context Object
The context, or "model", for the menu's view, which holds any data-dependent values. Note: The type must implement INotifyPropertyChanged in order for any changes to this data to be automatically reflected in the UI.
Returns
IClickableMenu
A menu object which can be shown using the game's standard menu APIs such as activeClickableMenu.
Remarks
Warning: Ad-hoc menus created this way cannot be cached, nor patched by other mods. Most mods should not use this API except for testing/experimentation.
EnableHotReloading(string)
Starts monitoring this mod's directory for changes to assets managed by any of the Register methods, e.g. views and sprites.
Parameters
sourceDirectory string
Optional source directory to watch and sync changes from. If not specified, or not a valid source directory, then hot reload will only pick up changes from within the live mod directory.
Remarks
If the sourceDirectory argument is specified, and points to a directory with the same asset structure as the mod, then an additional sync will be set up such that files modified in the sourceDirectory while the game is running will be copied to the active mod directory and subsequently reloaded. In other words, pointing this at the mod's .csproj directory allows hot reloading from the source files instead of the deployed mod's files.
Hot reload may impact game performance and should normally only be used during development and/or in debug mode.
PreloadAssets()
Begins preloading assets found in this mod's registered asset directories.
Remarks
Preloading is performed in the background, and can typically help reduce first-time latency for showing menus or drawables, without any noticeable lag in game startup.
Must be called after asset registration (RegisterViews(string, string), RegisterSprites(string, string) and so on) in order to be effective, and must not be called more than once per mod otherwise errors or crashes may occur.
PreloadModels(Type)
Declares that the specified context types will be used as either direct arguments or subproperties in one or more subsequent CreateMenu or CreateDrawable APIs, and instructs the framework to begin inspecting those types and optimizing for later use.
Parameters
types Type
The types that the mod expects to use as context.
Remarks
Data binding to mod-defined types uses reflection, which can become expensive when loading a very complex menu and/or binding to a very complex model for the first time. Preloading can perform this work in the background instead of causing latency when opening the menu.
RegisterCustomData(string, string)
Registers a mod directory to be searched for special-purpose mod data, i.e. that is not either views or sprites.
Parameters
assetPrefix string
The prefix for all asset names, excluding the category which is deduced from the file extension as described in the remarks. For example, given a value of Mods/MyMod, a file named foo.buttonspritemap.json would be referenced in views as @Mods/MyMod/ButtonSpriteMaps/Foo.
modDirectory string
The physical directory where the asset files are located, relative to the mod directory. Typically a path such as assets/ui or assets/ui/data.
Remarks
Allowed extensions for files in this folder and their corresponding data types are:
.buttonspritemap.json- ButtonSpriteMapData
RegisterSprites(string, string)
Registers a mod directory to be searched for sprite (and corresponding texture/sprite sheet data) assets.
Parameters
assetPrefix string
The prefix for all asset names, e.g. Mods/MyMod/Sprites. This can be any value but the same prefix must be used in @AssetName view bindings.
modDirectory string
The physical directory where the asset files are located, relative to the mod directory. Typically a path such as assets/sprites or assets/ui/sprites.
RegisterViews(string, string)
Registers a mod directory to be searched for view (StarML) assets. Uses the .sml extension.
Parameters
assetPrefix string
The prefix for all asset names, e.g. Mods/MyMod/Views. This can be any value but the same prefix must be used in include elements and in API calls to create views.
modDirectory string
The physical directory where the asset files are located, relative to the mod directory. Typically a path such as assets/views or assets/ui/views.