@mywallpaper/addon-sdk 2.11.1 → 2.12.0

package/README.md

@@ -48,7 +48,7 @@ my-addon/
 {
   "name": "My Awesome Addon",
   "version": "1.0.0",
-  "sdkVersion": "2.7.0",
+  "sdkVersion": "2.12.0",
   "description": "A cool widget for your desktop",
   "author": "Your Name",
   "capabilities": {
@@ -226,6 +226,34 @@ api.onSettingsChange((settings, changedKeys) => {
 })
 ```
 
+##### `onButtonClick(settingKey, callback)` / `offButtonClick(settingKey)`
+
+Handle button setting clicks.
+
+```typescript
+// Register a handler for a button setting
+api.onButtonClick('resetButton', () => {
+  resetToDefaults()
+  console.log('Reset clicked!')
+})
+
+// Remove the handler when no longer needed
+api.offButtonClick('resetButton')
+```
+
+With manifest:
+
+```json
+{
+  "settings": {
+    "resetButton": {
+      "type": "button",
+      "buttonLabel": "Reset to Defaults"
+    }
+  }
+}
+```
+
 ##### `onEvent(event, callback)` / `offEvent(event, callback)`
 
 Subscribe/unsubscribe to system events.

package/dist/index.d.mts

@@ -476,6 +476,30 @@ interface MyWallpaperAPI {
      * @param callback - Function called with new settings and changed keys
      */
     onSettingsChange(callback: SettingsCallback): void;
+    /**
+     * Register a callback for when a button setting is clicked.
+     * Buttons are defined in manifest.json with `type: "button"`.
+     *
+     * @param settingKey - The button's setting key from manifest
+     * @param callback - Function called when the button is clicked
+     *
+     * @example
+     * ```typescript
+     * // manifest.json:
+     * // "refreshButton": { "type": "button", "label": "Refresh", "buttonLabel": "Refresh Now" }
+     *
+     * api.onButtonClick('refreshButton', () => {
+     *   console.log('Refresh button clicked!')
+     *   fetchLatestData()
+     * })
+     * ```
+     */
+    onButtonClick(settingKey: string, callback: () => void): void;
+    /**
+     * Unregister a button click callback.
+     * @param settingKey - The button's setting key
+     */
+    offButtonClick(settingKey: string): void;
     /**
      * Subscribe to a system event.
      * @param event - Event type to subscribe to

package/dist/index.d.ts

@@ -476,6 +476,30 @@ interface MyWallpaperAPI {
      * @param callback - Function called with new settings and changed keys
      */
     onSettingsChange(callback: SettingsCallback): void;
+    /**
+     * Register a callback for when a button setting is clicked.
+     * Buttons are defined in manifest.json with `type: "button"`.
+     *
+     * @param settingKey - The button's setting key from manifest
+     * @param callback - Function called when the button is clicked
+     *
+     * @example
+     * ```typescript
+     * // manifest.json:
+     * // "refreshButton": { "type": "button", "label": "Refresh", "buttonLabel": "Refresh Now" }
+     *
+     * api.onButtonClick('refreshButton', () => {
+     *   console.log('Refresh button clicked!')
+     *   fetchLatestData()
+     * })
+     * ```
+     */
+    onButtonClick(settingKey: string, callback: () => void): void;
+    /**
+     * Unregister a button click callback.
+     * @param settingKey - The button's setting key
+     */
+    offButtonClick(settingKey: string): void;
     /**
      * Subscribe to a system event.
      * @param event - Event type to subscribe to

package/dist/manifest.d.mts

@@ -461,6 +461,30 @@ interface MyWallpaperAPI {
      * @param callback - Function called with new settings and changed keys
      */
     onSettingsChange(callback: SettingsCallback): void;
+    /**
+     * Register a callback for when a button setting is clicked.
+     * Buttons are defined in manifest.json with `type: "button"`.
+     *
+     * @param settingKey - The button's setting key from manifest
+     * @param callback - Function called when the button is clicked
+     *
+     * @example
+     * ```typescript
+     * // manifest.json:
+     * // "refreshButton": { "type": "button", "label": "Refresh", "buttonLabel": "Refresh Now" }
+     *
+     * api.onButtonClick('refreshButton', () => {
+     *   console.log('Refresh button clicked!')
+     *   fetchLatestData()
+     * })
+     * ```
+     */
+    onButtonClick(settingKey: string, callback: () => void): void;
+    /**
+     * Unregister a button click callback.
+     * @param settingKey - The button's setting key
+     */
+    offButtonClick(settingKey: string): void;
     /**
      * Subscribe to a system event.
      * @param event - Event type to subscribe to

package/dist/manifest.d.ts

@@ -461,6 +461,30 @@ interface MyWallpaperAPI {
      * @param callback - Function called with new settings and changed keys
      */
     onSettingsChange(callback: SettingsCallback): void;
+    /**
+     * Register a callback for when a button setting is clicked.
+     * Buttons are defined in manifest.json with `type: "button"`.
+     *
+     * @param settingKey - The button's setting key from manifest
+     * @param callback - Function called when the button is clicked
+     *
+     * @example
+     * ```typescript
+     * // manifest.json:
+     * // "refreshButton": { "type": "button", "label": "Refresh", "buttonLabel": "Refresh Now" }
+     *
+     * api.onButtonClick('refreshButton', () => {
+     *   console.log('Refresh button clicked!')
+     *   fetchLatestData()
+     * })
+     * ```
+     */
+    onButtonClick(settingKey: string, callback: () => void): void;
+    /**
+     * Unregister a button click callback.
+     * @param settingKey - The button's setting key
+     */
+    offButtonClick(settingKey: string): void;
     /**
      * Subscribe to a system event.
      * @param event - Event type to subscribe to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mywallpaper/addon-sdk",
-  "version": "2.11.1",
+  "version": "2.12.0",
   "description": "SDK for building MyWallpaper addons - TypeScript types, manifest validation, and utilities",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/runtime/addon-client.js

@@ -32,6 +32,7 @@
   var pendingNetworkAccess = new Map()  // For on-demand domain permission requests
   var grantedBlobUrls = new Map() // settingKey -> blobUrl
   var dynamicSettingsOptions = new Map() // settingKey -> options[] (dynamic options from widget)
+  var buttonCallbacks = new Map() // settingKey -> callback function for button clicks
 
   // Audio state (synced from host)
   var audioState = {
@@ -250,6 +251,15 @@
           try { cb(audioState) } catch (err) { console.error('[MyWallpaper] Audio callback error:', err) }
         })
         break
+
+      case 'BUTTON_CLICK':
+        // Handle button click from settings panel
+        var btnKey = d.payload.settingKey
+        var btnCb = buttonCallbacks.get(btnKey)
+        if (btnCb) {
+          try { btnCb() } catch (err) { console.error('[MyWallpaper] Button callback error:', err) }
+        }
+        break
     }
   }
 
@@ -420,6 +430,25 @@
 
     onSettingsChange: function (fn) { if (typeof fn === 'function') settingsCallbacks.push(fn) },
 
+    /**
+     * Register a callback for a button click in settings panel
+     * @param {string} settingKey - The button's setting key from manifest
+     * @param {function} callback - Function called when button is clicked
+     */
+    onButtonClick: function (settingKey, callback) {
+      if (typeof settingKey === 'string' && typeof callback === 'function') {
+        buttonCallbacks.set(settingKey, callback)
+      }
+    },
+
+    /**
+     * Unregister a button click callback
+     * @param {string} settingKey - The button's setting key
+     */
+    offButtonClick: function (settingKey) {
+      buttonCallbacks.delete(settingKey)
+    },
+
     onEvent: function (event, fn) {
       if (typeof fn !== 'function') return
       if (!eventCallbacks.has(event)) eventCallbacks.set(event, new Set())