Add hooks for Volume widgets

CHANGELOG

@@ -1,3 +1,4 @@
+2024-04-26: [FEATURE] Add hooks to `ALSAWidget` and `PulseVolumeExtra`
 2024-04-25: [FEATURE] Add ability to drag `PopupSlider` and `PopupCircularProgress` controls (NB experimental)
 2024-04-25: [BREAKING CHANGE] Update to using lazy calls in popups. Needs latest qtile.
 2024-04-08: [RELEASE] v0.25.0 release - compatible with qtile 0.25.0

qtile_extras/hook.py

@@ -376,6 +376,56 @@ def new_track(status):
 
 hooks.extend(mpris_hooks)
 
+# Volume hooks
+volume_hooks = [
+    Hook(
+        "volume_change",
+        """
+        Fired when the volume value changes.
+
+        Receives an integer volume percentage (0-100) and boolean muted status.
+
+        .. code:: python
+
+          from libqtile import qtile
+          from libqtile.utils import send_notification
+
+          import qtile_extras.hook
+
+          @qtile_extras.hook.subscribe.volume_change
+          def vol_change(volume, muted):
+              send_notification("Volume change", f"Volume is now {volume}%")
+
+        """,
+    ),
+    Hook(
+        "volume_mute_change",
+        """
+        Fired when the volume mute status changes.
+
+        Receives an integer volume percentage (0-100) and boolean muted status.
+
+        The signature is the same as ``volume_change`` to allow the same function to be
+        used for both hooks.
+
+        .. code:: python
+
+          from libqtile import qtile
+          from libqtile.utils import send_notification
+
+          import qtile_extras.hook
+
+          @qtile_extras.hook.subscribe.volume_mute_change
+          def mute_change(volume, muted):
+              if muted:
+                send_notification("Volume change", "Volume is now muted.")
+
+        """,
+    ),
+]
+
+hooks.extend(volume_hooks)
+
 # Build the registry and expose helpful entrypoints
 qte = Registry("qtile-extras", hooks)
 

qtile_extras/widget/base.py

@@ -26,6 +26,7 @@
 from libqtile.log_utils import logger
 from libqtile.widget import base
 
+from qtile_extras import hook
 from qtile_extras.popup.templates.volume import VOLUME_NOTIFICATION
 from qtile_extras.widget.mixins import ExtendedPopupMixin, ProgressBarMixin
 
@@ -85,6 +86,8 @@ class _Volume(base._Widget, ExtendedPopupMixin, ProgressBarMixin):
         ),
     ]
 
+    _hooks = [h.name for h in hook.volume_hooks]
+
     def __init__(self, **config):
         base._Widget.__init__(self, bar.CALCULATED, **config)
         ExtendedPopupMixin.__init__(self, **config)
@@ -187,6 +190,12 @@ def status_change(self, vol, muted):
         # Unhide bar
         self.hidden = False
 
+        # Fire any hooks
+        if muted != self.muted:
+            hook.fire("volume_mute_change", int(vol), bool(muted))
+        elif vol != self.volume:
+            hook.fire("volume_change", int(vol), bool(muted))
+
         # Get new values
         self.volume = vol
         self.muted = muted