local function onEditorPreferenceValueChanged(prefPath, value)
  -- when a preference value changes, this function will be called with the path and the actual new value (number or string)
  -- here we check for a specific path, if changed, then we can do something
  if prefPath == "general.units.unitSize" then
    -- do something here if value changed
  end
end

-- when a deprecated preference item is found in the user settings, the system will call back this function so you can deal with this case
-- usually you will set a new preference item, based on the new name/path, if that changed, and using the old value given as argument
local function onEditorDeprecatedPreferencesItem(itemPath, value)
  -- here we check for an old path lets say, and we set the new preference path with the custom old value the user had
  -- we can also adjust or discard that value if it doesnt make sense in the new preference item context
  if itemPath = "some.oldname.prefItem" then
    editor.setPreference("some.newrenamed.item", value)
  end
end

local function onEditorRegisterPreferences(prefsRegistry)
  prefsRegistry:registerCategory("general")
  prefsRegistry:registerSubCategory("general", "files")
  prefsRegistry:registerSubCategory("general", "units")

  -- the label for the category is created by converting the name to `Sentence Case`, unless the label is explicitly given like the example below
  prefsRegistry:registerCategory("ui", "User Interface")
  prefsRegistry:registerSubCategory("ui", "gizmo")
  prefsRegistry:registerSubCategory("ui", "handles")

  prefsRegistry:registerPreferences("general", "files",
  {
    -- the structure of each item is:
    -- {name = {type, default value, desc, label (nil for auto Sentence Case), min, max, hidden, advanced, customUiFunc, enumLabels}}
    -- to find out more of each, check the Preferences API
    {autobackup = { "bool", true, "The auto backup", "Auto Backup Custom Label" }},
    {saveAll = { "bool", true, "The save all" }}
  })

  prefsRegistry:registerPreferences("general", "units",
  {
    {unitSize = { "bool", true, "Size" }}
  })

  prefsRegistry:registerPreferences("ui", "handles",
  {
    {size = { "int", 111, "The handle size" }}
  })

  prefsRegistry:registerPreferences("ui", "gizmo",
  {
    {color = { "ColorI", ColorI(255, 0, 0, 255), "The color" }},
    {color2 = { "ColorF", ColorI(1, 1, 0, 1), "The second color" }},
    {scale = { "float", 1, "The scale of the gizmo" }}
  })
end

-- expose our functions to the extensions hook system
M.onEditorInitialized = onEditorInitialized
M.onEditorDeprecatedPreferencesItem = onEditorDeprecatedPreferencesItem
M.onEditorPreferenceValueChanged = onEditorPreferenceValueChanged
M.onEditorRegisterPreferences = onEditorRegisterPreferences