Merge pull request #3752 from myk002/myk_overlay

[overlay] allow widgets to bump their version and reset their saved settings

docs/changelog.txt

@@ -63,6 +63,7 @@ Template for new versions:
 ## Documentation
 
 ## API
+- `overlay`: overlay widgets can now declare a ``version`` attribute. changing the version of a widget will reset its settings to defaults. this is useful when changing the overlay layout and old saved positions will no longer be valid.
 
 ## Lua
 

docs/dev/overlay-dev-guide.rst

@@ -90,6 +90,10 @@ The ``overlay.OverlayWidget`` superclass defines the following class attributes:
     This will be filled in with the display name of your widget, in case you
     have multiple widgets with the same implementation but different
     configurations.
+- ``version``
+    You can set this to any string. If the version string of a loaded widget
+    does not match the saved settings for that widget, then the configuration
+    for the widget (position, enabled status) will be reset to defaults.
 - ``default_pos`` (default: ``{x=-2, y=-2}``)
     Override this attribute with your desired default widget position. See
     the `overlay` docs for information on what positive and negative numbers

plugins/lua/overlay.lua

@@ -261,7 +261,11 @@ local function load_widget(name, widget_class)
         next_update_ms=widget.overlay_onupdate and 0 or math.huge,
     }
     if not overlay_config[name] then overlay_config[name] = {} end
+    if widget.version ~= overlay_config[name].version then
+        overlay_config[name] = {}
+    end
     local config = overlay_config[name]
+    config.version = widget.version
     if config.enabled == nil then
         config.enabled = widget.default_enabled
     end