From a19b9d705a962d5211ee3a73d7513bd95b22fbdf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rados=C5=82aw=20Kintzi?= <r.kintzi@pobox.net.pl>
Date: Sat, 11 Nov 2023 20:06:10 +0100
Subject: [PATCH] Describe the Volume widget in the README.md file

---
 README.md         | 26 ++++++++++++++++++++
 widgets/volume.go | 61 ++++++++++++++++++++++++-----------------------
 2 files changed, 57 insertions(+), 30 deletions(-)

diff --git a/README.md b/README.md
index 9a2e3b8..1482232 100644
--- a/README.md
+++ b/README.md
@@ -143,6 +143,32 @@ necessary, and will display two digits for the fractional part. Please note
 that the width and precision specification should be followed by the 'f'
 suffix, but no '%' prefix should be included.
 
+### Volume
+
+The Volume widget shows and allows you to adjust the volume of an audio
+device. It offers the following options for customization:
+
+- `format`: Determines how the widget is displayed. The default format is
+  `{icon} {level}%`.
+- `icon`: Specifies the icon that appears when the device is not muted.
+- `muteIcon`: Specifies the icon that appears when the device is muted.
+- `leftClickCommand`: Specifies the command that is executed when the left
+  mouse button is clicked.
+- `rightClickCommand`: Specifies the command that is executed when the right
+  mouse button is clicked.
+- `scrollUpCommand`: Specifies the command that is executed when the mouse
+  scroll up event occurs.
+- `scrollDownCommand`: Specifies the command that is executed when the mouse
+  scroll down event occurs.
+- `volMonCommand`: Specifies the program responsible for monitoring the volume
+  level of the devices. The program should print the volume level to its
+  standard output each time it detects a change. An example program that works
+  with the PulseAudio (and PipeWire) server is available in the project's
+  `cmds/pavolmon` directory. Please refer to its
+  [README.md](https://git.sr.ht/~rkintzi/statusbar/tree/master/item/cmds/pavolmon/README.md)
+  for instructions on how to install it.
+
+
 ## statusbar - The Library
 
 If there is a widget that you believe is missing from the project, you can
diff --git a/widgets/volume.go b/widgets/volume.go
index 6866808..f8c031d 100644
--- a/widgets/volume.go
+++ b/widgets/volume.go
@@ -15,20 +15,21 @@ import (
 )
 
 type Volume struct {
-	Format        string `yaml:"format"`
-	Icon          string `yaml:"icon"`
-	MuteIcon      string `yaml:"muteIcon"`
-	VolMonCmd     string `yaml:"volMonCommand"`
-	VolUpCmd      string `yaml:"volUpCommand"`
-	VolDownCmd    string `yaml:"volDownCommand"`
-	MuteToggleCmd string `yaml:"muteToggleCommand"`
-	OnClickCmd    string `yaml:"onClickCommand"`
+	Format   string `yaml:"format"`
+	Icon     string `yaml:"icon"`
+	MuteIcon string `yaml:"muteIcon"`
 
-	volMonCmd     *exec.Cmd
-	volUpCmd      []string
-	volDownCmd    []string
-	muteToggleCmd []string
-	onClickCmd    []string
+	VolMonCmd         string `yaml:"volMonCommand"`
+	ScrollDownCmd     string `yaml:"scrollDownCommand"`
+	ScrollUpCmd       string `yaml:"scrollUpCommand"`
+	RightClickCommand string `yaml:"rightClickCommand"`
+	LeftClickCommand  string `yaml:"leftClickCommand"`
+
+	volMonCmd         *exec.Cmd
+	scrollDownCommand []string
+	scrollUpCmd       []string
+	rigthClickCmd     []string
+	leftClickCmd      []string
 
 	fmt     Format
 	rc      io.ReadCloser
@@ -70,13 +71,13 @@ func (w *Volume) Event(ev statusbar.Event) {
 	var cmd []string
 	switch ev.Button {
 	case 4:
-		cmd = w.volUpCmd
+		cmd = w.scrollDownCommand
 	case 5:
-		cmd = w.volDownCmd
+		cmd = w.scrollUpCmd
 	case 1:
-		cmd = w.onClickCmd
+		cmd = w.leftClickCmd
 	case 3:
-		cmd = w.muteToggleCmd
+		cmd = w.rigthClickCmd
 	}
 	if len(cmd) == 0 {
 		return
@@ -136,7 +137,7 @@ func (w *Volume) emitVol(vol int, mute bool, update statusbar.UpdateFunc) {
 func (w *Volume) init() {
 	w.prefix = "Volume"
 	if w.Format == "" {
-		w.Format = "{icon} {level}"
+		w.Format = "{icon} {level}%"
 	}
 	if w.Icon == "" {
 		w.Icon = "\ue892"
@@ -153,32 +154,32 @@ func (w *Volume) init() {
 	} else {
 		w.volMonCmd = exec.Command(cmd[0], cmd[1:]...)
 	}
-	if w.VolUpCmd != "" {
-		if cmd, err := shlex.Split(w.VolUpCmd); err != nil {
+	if w.ScrollDownCmd != "" {
+		if cmd, err := shlex.Split(w.ScrollDownCmd); err != nil {
 			w.errorf(err.Error())
 		} else {
-			w.volUpCmd = cmd
+			w.scrollDownCommand = cmd
 		}
 	}
-	if w.VolDownCmd != "" {
-		if cmd, err := shlex.Split(w.VolDownCmd); err != nil {
+	if w.ScrollUpCmd != "" {
+		if cmd, err := shlex.Split(w.ScrollUpCmd); err != nil {
 			w.errorf(err.Error())
 		} else {
-			w.volDownCmd = cmd
+			w.scrollUpCmd = cmd
 		}
 	}
-	if w.MuteToggleCmd != "" {
-		if cmd, err := shlex.Split(w.MuteToggleCmd); err != nil {
+	if w.RightClickCommand != "" {
+		if cmd, err := shlex.Split(w.RightClickCommand); err != nil {
 			w.errorf(err.Error())
 		} else {
-			w.muteToggleCmd = cmd
+			w.rigthClickCmd = cmd
 		}
 	}
-	if w.OnClickCmd != "" {
-		if cmd, err := shlex.Split(w.OnClickCmd); err != nil {
+	if w.LeftClickCommand != "" {
+		if cmd, err := shlex.Split(w.LeftClickCommand); err != nil {
 			w.errorf(err.Error())
 		} else {
-			w.onClickCmd = cmd
+			w.leftClickCmd = cmd
 		}
 	}
 }
-- 
2.45.2