Create Customization Controls

Customization Controls — SucroseProperties.json

Audience: wallpaper creators. This page is the authoritative reference for SucroseProperties.json, the optional file that defines the user‑adjustable controls Sucrose renders in the Portal "Customize" panel, plus the JavaScript callback used to push each change into your running wallpaper. It documents the PropertyListener template, the PropertyList map, every control type and its fields, localization with loc_* keys, and the live re‑apply behavior. For the JS side of receiving values, see Create Property Listener Filters.

Contents

• What this file does
• Top‑level schema
• The PropertyListener template
• Control base fields
• Control types
• Localization (loc_*)
• Worked example
• Live re‑application
• See also

What this file does

SucroseProperties.json is an optional sibling of SucroseInfo.json. When present, the Portal renders a Customize panel from it (sliders, checkboxes, dropdowns, color pickers, and more). When the user changes a control, the engine serializes that control's value to JSON and calls the JavaScript function named in your PropertyListener template — so your wallpaper can react. The Property service is what hosts this editor; see Property Service and Customizing Wallpaper.

📷 Screenshot needed: The Portal "Customize" panel for a Web wallpaper showing a slider, a dropdown, a color picker, and a checkbox grouped under section labels.

Top‑level schema

Field	Type	Required	Meaning
PropertyListener	string	Always	A string.Format template for the JS call. {0} = property key, {1} = serialized control value JSON. Typical value: SucrosePropertyListener('{0}', {1});
PropertyList	Dictionary<string, ControlModel>	Always	Ordered map of property key → control definition. The key is what your JS receives as the name argument.
PropertyLocalization	Dictionary<lang, Dictionary<locKey, text>>	optional	Localized strings; controls reference them by loc_* keys in their text / value / help / items.

The PropertyListener template

PropertyListener is a string.Format template with two placeholders:

• {0} — the property key (the PropertyList dictionary key).
• {1} — the serialized control value JSON (the full control object, including its value).

The standard template is:

"PropertyListener": "SucrosePropertyListener('{0}', {1});"

With that template, when the user adjusts a control whose key is ui_font_size, the engine runs JavaScript equivalent to:

SucrosePropertyListener("ui_font_size", { "max": 30, "min": 5, "type": "slider", "value": 15 });

So your JS receives the property name and the full control object; read the chosen value from val.value (and for dropdowns val.valuetext, for sliders val.min/val.max/val.step, etc.). See Create Property Listener Filters for the receiving side.

Control base fields

Every control in PropertyList shares these base fields:

Field	Type	Required	Meaning
type	string	Yes	Discriminator that selects the control class (see table below). Case‑insensitive.
text	string	Yes (except label)	The label shown next to the control (often a loc_* key). label controls may omit text — the deserializer injects an empty string for them.
help	string	No	Tooltip text (often a loc_* key).
name	(runtime)	—	Injected at runtime = the dictionary key; do not put it in the input JSON.

An unknown type is rejected (NotSupportedException). label controls are commonly used as section dividers (keys like folder_audio, folder_color).

Control types

The exact type strings and their extra fields:

type	Extra fields	Value type	Notes
label	value	string	Used as a section header / static text; empty value allowed. Common divider control.
button	value	string	A button; value is its caption/payload.
slider	min, max, step, value	double	Numeric slider.
textbox	value	string	Free text input.
checkbox	value	bool	On/off toggle.
dropdown	items (string[]), value (int index)	int index	Selection list; exposes a computed valuetext for the selected item.
numberbox	min, max, places (int decimals), value	double	Numeric entry with decimal places.
colorpicker	value	string	ARGB hex, e.g. #FF00FF00 (#AARRGGBB).
passwordbox	value	string	Masked text input.
filedropdown	desc, value, title, folder, filter	string (file path)	File picker; filter constrains selectable files.

Localization (loc_*)

PropertyLocalization is keyed by language code (e.g. EN, DE, TR). Each value is a dictionary mapping a loc_* key to its translated text. Controls reference these keys in their text, value, help, or items fields. For example, a control with "text": "loc_rain_matrixspeed" displays the translation of loc_rain_matrixspeed for the current language. If a key has no entry for the active language, Sucrose falls back to another available language.

Worked example

Abbreviated SucroseProperties.json from the shipped Neo Matrix wallpaper:

{
  "PropertyListener": "SucrosePropertyListener('{0}', {1});",
  "PropertyList": {
    "folder_rain": {
      "type": "label",
      "value": "loc_folder_rain"
    },
    "ui_rain_matrixspeed": {
      "type": "slider",
      "text": "loc_rain_matrixspeed",
      "min": 10,
      "max": 60,
      "step": 1,
      "value": 24
    },
    "ui_color_matrixcolor": {
      "type": "colorpicker",
      "text": "loc_color_matrixcolor",
      "value": "#FF00FF00"
    },
    "ui_characters_customcharset": {
      "type": "textbox",
      "text": "loc_characters_customcharset",
      "help": "loc_characters_customcharset_help",
      "value": "0123456789ABCDEF"
    },
    "ui_color_colormode": {
      "type": "dropdown",
      "text": "loc_color_colormode",
      "value": 2,
      "items": [
        "loc_color_colormode_single",
        "loc_color_colormode_rgb_cycle"
      ]
    }
  },
  "PropertyLocalization": {
    "EN": {
      "loc_folder_rain": "Rain",
      "loc_rain_matrixspeed": "Matrix Speed"
    },
    "DE": { "loc_folder_rain": "Regen" },
    "TR": { "loc_folder_rain": "Yağmur" }
  }
}

On the JavaScript side, handle each key in your listener:

function SucrosePropertyListener(name, val) {
  switch (name) {
    case "ui_rain_matrixspeed":
      setMatrixSpeed(val.value);          // slider -> number
      break;
    case "ui_color_matrixcolor":
      setMatrixColor(val.value);          // colorpicker -> "#AARRGGBB"
      break;
    case "ui_characters_customcharset":
      setCharset(val.value);              // textbox -> string
      break;
    case "ui_color_colormode":
      setColorMode(val.value, val.valuetext); // dropdown -> index + selected text
      break;
  }
}

Live re‑application

You do not need to restart the wallpaper for the user to change settings. The engine watches a properties cache file with a FileSystemWatcher; when the Portal/Property tool writes new values, the engine re‑pushes them through the PropertyListener template so your wallpaper updates live. The watcher deletes its trigger file after about 3 seconds. On initial load, the engine also applies all current property values once. See Create Web Architecture for the full data flow.

See also

• Create Property Listener Filters
• Create Package Format
• Create JS Bridge
• Customizing Wallpaper
• Property Service