Property Service

Property Service

Sucrose.Property.exe is the WPF process behind the Customize action — the per-wallpaper settings editor. When you customize a wallpaper, this process reads the wallpaper's SucroseInfo.json and SucroseProperties.json, renders a control for each property the author defined (sliders, dropdowns, color pickers, and so on), and writes your changes back so the running engine can re-apply them live. This page documents how the Property process resolves which file to edit, which wallpaper types it supports, and how its controls map to the property schema. It is written for developers; wallpaper authors should also read Create Customization Controls for the JSON schema, and end users Customizing Wallpaper for the workflow.

Contents

• Role and launch
• Supported wallpaper types
• Resolving the properties file (PropertiesType)
• Working copy and live re-apply
• Controls
• Error handling
• See also

Role and launch

The Property process is a single-instance WPF window guarded by the {Sucrose-Wallpaper-Engine-Property} mutex, with the full crash-handler set like every other Sucrose app (see Crash Reporting). It is launched through Commandog in one of two forms:

✔Property✖<path-to-Sucrose.Property.exe>                    (edit the currently selected wallpaper)
✔PropertyA✖<path-to-Sucrose.Property.exe>✖<selectedTheme>  (edit a specific wallpaper)

App.Configure(args):

• Defaults the target to Manager.Library.Selected (the currently selected wallpaper). If an argument is passed (split on ✖, exactly one value), it overrides LibrarySelected with that theme id.
• The theme folder is <LibraryLocation>\<Selected>.
• Reads SucroseInfo.json (Content.SucroseInfo) into a ThemeInfo to learn the wallpaper's WallpaperType.

Supported wallpaper types

The Property editor only opens for wallpaper types that have an editable property schema:

WallpaperType	Editable here?
Gif	Yes
Web	Yes
Video	Yes
YouTube	Yes
Url	No
Application	No

Url, Application, and static images have no property editor in this process. (Note: although the broader project layout describes the Property service as handling "Gif/Web/Video/YouTube," Url is excluded here because it has no customizable properties.)

Resolving the properties file (PropertiesType)

Where the SucroseProperties.json source lives depends on the wallpaper type and the engine configured for it. The PropertiesType enum (src/Shared/Sucrose.Shared.Dependency/Enum/PropertiesType.cs) selects the location:

Base, WebView, CefSharp, MpvPlayer, VlcPlayer

Wallpaper type	Source resolution
Web (with properties present)	Base — the properties file shipped in the wallpaper folder.
Gif / Video / YouTube	Engine-specific cache, chosen by the engine configured for that type.

For the engine-specific case, the file is read from:

%AppData%\Sucrose\Cache\<MpvPlayer | VlcPlayer | CefSharp | WebView2>\SucroseProperties

The subfolder matches the configured engine: Engine.Gif / Engine.Video may each be MpvPlayerLive, VlcPlayerLive, CefSharpLive, or WebViewLive, while Engine.YouTube resolves only to CefSharpLive or WebViewLive (MpvPlayer is not a valid YouTube engine). This is why the same wallpaper can expose different controls depending on the engine you assigned to its type. See Choosing Engines and Engines Overview.

Working copy and live re-apply

To edit safely without corrupting the source, the process copies the resolved properties file into a working cache:

%AppData%\Sucrose\Cache\Properties\<Selected><PropertiesType>

(PropertiesFile). It then:

1. Records the engine drop-path glob (WatcherFile, *.<Selected><PropertiesType> in the same Cache\Properties folder). The Property process does not watch any file itself; the running engine's FileSystemWatcher (in Sucrose.Shared.Engine.Helper.Properties) monitors that folder, and each control change drops a GUID-named file matching this glob to trigger live re-apply.
2. Reads the JSON (Theme.Helper.Properties.ReadJson).
3. Shows MainWindow with one control per property.

Because the running engine also watches its properties source, changes you make are re-applied to the live wallpaper as you edit — sliders and toggles update the wallpaper without a restart. This live re-apply path is the same one wallpaper authors target with SucrosePropertyListener (see Create Property Listener & Filters).

Controls

Each property type in the wallpaper's schema maps to a WPF UserControl:

Control	Property kind
Label	Static text / section header
Button	Action trigger
Slider	Numeric range (min / max / step)
TextBox	Free text
NumberBox	Numeric entry
CheckBox	Boolean toggle
DropDown	Single choice from a list
FileDropDown	File picker / file list
ColorPicker	ARGB color
PasswordBox	Masked text

These correspond directly to the control types authors define in SucroseProperties.json. For the authoring side — field names, the PropertyListener template, and localization (loc_*) — see Create Customization Controls.

Error handling

If the working JSON is corrupt, the process deletes the working file and rethrows, so a bad edit does not get stuck — re-opening Customize re-copies a fresh source. Unhandled exceptions route through the standard Crash Reporting pipeline like every other Sucrose process.

See also

• Customizing Wallpaper — the end-user workflow for the Customize panel.
• Create Customization Controls — the SucroseProperties.json schema and control fields.
• Create Property Listener & Filters — how property changes reach the wallpaper at runtime.
• Commandog Dispatcher — the ✔Property✖… / ✔PropertyA✖… commands.
• Choosing Engines — why the configured engine changes which properties appear.