[experiments] volume widget improvements

2 files changed, 62 insertions, 26 deletions

diff --git a/experiments/volume/README.md b/experiments/volume/README.md
index 1210ced..973bb49 100644
--- a/experiments/volume/README.md
+++ b/experiments/volume/README.md
@@ -13,7 +13,36 @@ A right-click on the widget opens a popup where you can choose a sink/source:
 
  - switch between sinks/sources by right clicking on the widget;
  - more responsive than previous versions of volume widget, which were refreshed once a second;
- - 5 predefined looks (check the screenshots below);
+ - 5 predefined customizable looks;
+
+## Installation
+
+Clone the repo under **~/.config/awesome/** and add widget in **rc.lua**:
+
+```lua
+local volume_widget = require('awesome-wm-widgets.experiments.volume.volume')
+...
+s.mytasklist, -- Middle widget
+	{ -- Right widgets
+    	layout = wibox.layout.fixed.horizontal,
+        ...
+        -- default
+        volume_widget(),
+        -- customized
+        volume_widget{
+            type = 'arc'
+        },
+```
+
+### Shortcuts
+
+To improve responsiveness of the widget when volume level is changed by a shortcut use corresponding methods of the widget:
+
+```lua
+awful.key({ modkey }, "]", function() volume_widget:inc() end),
+awful.key({ modkey }, "[", function() volume_widget:dec() end),
+awful.key({ modkey }, "\\", function() volume_widget:toggle() end),
+```
 
 ## Customization
 
@@ -25,7 +54,9 @@ It is possible to customize the widget by providing a table with all or some of
 |---|---|---|
 | `type`| `icon_and_text`| Widget type, one of `horizontal_bar`, `vertical_bar`, `icon`, `icon_and_text`, `arc` | 
 
-### `icon` parameters
+Depending on the chosen widget type add parameters from the corresponding section below:
+
+#### `icon` parameters
 
 | Name | Default | Description |
 |---|---|---|
@@ -37,14 +68,14 @@ _Note:_ if you are changing icons, the folder should contain following .svg imag
  - audio-volume-low-symbolic
  - audio-volume-muted-symbolic
 
-### `icon_and_text` parameters
+#### `icon_and_text` parameters
 
 | Name | Default | Description |
 |---|---|---|
 | `icon_dir`| `./icons`| Path to the folder with icons | 
 | `font` | `beautiful.font` | Font name and size, like `Play 12` |
 
-### `arc` parameters
+#### `arc` parameters
 
 | Name | Default | Description |
 |---|---|---|
@@ -54,7 +85,7 @@ _Note:_ if you are changing icons, the folder should contain following .svg imag
 | `mute_color` | `beautiful.fg_urgent` | Color of the arc when mute |
 | `size` | 18 | Size of the widget |
 
-### `horizontal_bar` parameters
+#### `horizontal_bar` parameters
 
 | Name | Default | Description |
 |---|---|---|
@@ -68,7 +99,7 @@ _Note:_ if you are changing icons, the folder should contain following .svg imag
 
 _Note:_ I didn't figure out how does the `forced_height` property of progressbar widget work (maybe it doesn't work at all), thus there is a workaround with margins.
 
-### `vertical_bar` parameters
+#### `vertical_bar` parameters
 
 | Name | Default | Description |
 |---|---|---|
diff --git a/experiments/volume/volume.lua b/experiments/volume/volume.lua
index 7daeb40..7bdda1c 100644
--- a/experiments/volume/volume.lua
+++ b/experiments/volume/volume.lua
@@ -30,8 +30,7 @@ local widget_types = {
     horizontal_bar = require("awesome-wm-widgets.experiments.volume.widgets.horizontal-bar-widget"),
     vertical_bar = require("awesome-wm-widgets.experiments.volume.widgets.vertical-bar-widget")
 }
-
-local volume_widget = wibox.widget{}
+local volume = {}
 
 local rows  = { layout = wibox.layout.fixed.vertical }
 
@@ -168,9 +167,9 @@ local function worker(user_args)
     local refresh_rate = args.refresh_rate or 1
 
     if widget_types[widget_type] == nil then
-        volume_widget = widget_types['icon_and_text'].get_widget(user_args.icon_and_text_args)
+        volume.widget = widget_types['icon_and_text'].get_widget(user_args.icon_and_text_args)
     else
-        volume_widget = widget_types[widget_type].get_widget(args)
+        volume.widget = widget_types[widget_type].get_widget(args)
     end
 
     local function update_graphic(widget, stdout)
@@ -178,12 +177,24 @@ local function worker(user_args)
         if mute == 'off' then widget:mute()
         elseif mute == 'on' then widget:unmute()
         end
-        local volume = string.match(stdout, "(%d?%d?%d)%%") -- (\d?\d?\d)\%)
-        volume = string.format("% 3d", volume)
-        widget:set_volume_level(volume)
+        local volume_level = string.match(stdout, "(%d?%d?%d)%%") -- (\d?\d?\d)\%)
+        volume_level = string.format("% 3d", volume_level)
+        widget:set_volume_level(volume_level)
+    end
+
+    function volume:inc()
+        spawn.easy_async(INC_VOLUME_CMD, function(stdout) update_graphic(volume.widget, stdout) end)
+    end
+
+    function volume:dec()
+        spawn.easy_async(DEC_VOLUME_CMD, function(stdout) update_graphic(volume.widget, stdout) end)
     end
 
-    volume_widget:buttons(
+    function volume:toggle()
+        spawn.easy_async(TOG_VOLUME_CMD, function(stdout) update_graphic(volume.widget, stdout) end)
+    end
+
+    volume.widget:buttons(
             awful.util.table.join(
                     awful.button({}, 3, function()
                         if popup.visible then
@@ -193,21 +204,15 @@ local function worker(user_args)
                             popup:move_next_to(mouse.current_widget_geometry)
                         end
                     end),
-                    awful.button({}, 4, function()
-                        spawn.easy_async(INC_VOLUME_CMD, function(stdout) update_graphic(volume_widget, stdout) end)
-                    end),
-                    awful.button({}, 5, function()
-                        spawn.easy_async(DEC_VOLUME_CMD, function(stdout) update_graphic(volume_widget, stdout) end)
-                    end),
-                    awful.button({}, 1, function()
-                        spawn.easy_async(TOG_VOLUME_CMD, function(stdout) update_graphic(volume_widget, stdout) end)
-                    end)
+                    awful.button({}, 4, function() volume:inc() end),
+                    awful.button({}, 5, function() volume:dec() end),
+                    awful.button({}, 1, function() volume:toggle() end)
             )
     )
 
-    watch(GET_VOLUME_CMD, refresh_rate, update_graphic, volume_widget)
+    watch(GET_VOLUME_CMD, refresh_rate, update_graphic, volume.widget)
 
-    return volume_widget
+    return volume.widget
 end
 
-return setmetatable(volume_widget, { __call = function(_, ...) return worker(...) end })
+return setmetatable(volume, { __call = function(_, ...) return worker(...) end })