From 718ac6da7a9a6a61b17bef63316ce6978adda318 Mon Sep 17 00:00:00 2001
From: gokul <33443763+JavaCafe01@users.noreply.github.com>
Date: Sun, 23 Jan 2022 16:06:44 -0800
Subject: [PATCH] Update Docs (#154)

Add in docs for the new playerctl PR.
---
 docs/signals/pctl.md | 51 +++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 46 insertions(+), 5 deletions(-)

diff --git a/docs/signals/pctl.md b/docs/signals/pctl.md
index 9dae973..d87d8a8 100644
--- a/docs/signals/pctl.md
+++ b/docs/signals/pctl.md
@@ -21,7 +21,10 @@ To enable: `playerctl = bling.signal.playerctl.lib/cli()`
 
 To disable: `playerctl:disable()`
 
-Playerctl_lib signals available:
+#### Playerctl_lib Signals
+
+**Note**: When connecting to signals with the new `playerctl` module, the object itself is always given to you as the first parameter.
+
 ```lua
 -- metadata
 --      title (string)
@@ -55,7 +58,8 @@ Playerctl_lib signals available:
 --      (No parameters)
 ```
 
-Playerctl_cli signals available:
+#### Playerctl_cli Signals
+
 ```LUA
 -- metadata
 --      title (string)
@@ -78,6 +82,31 @@ Playerctl_cli signals available:
 --      (No parameters)
 ```
 
+#### Playerctl Functions
+
+With this library we also give the user a way to interact with Playerctl, such as playing, pausing, seeking, etc.
+
+Here are the functions provided:
+
+```lua
+-- disable()
+-- pause(player)
+-- play(player)
+-- stop(player)
+-- play_pause(player)
+-- previous(player)
+-- next(player)
+-- set_loop_status(loop_status, player)
+-- cycle_loop_status(player)
+-- set_position(position, player)
+-- set_shuffle(shuffle, player)
+-- cycle_shuffle(player)
+-- set_volume(volume, player)
+-- get_manager()
+-- get_active_player()
+-- get_player_of_name(name)
+```
+
 ### Example Implementation
 
 Lets say we have an imagebox. If I wanted to set the imagebox to show the album art, all I have to do is this:
@@ -112,9 +141,9 @@ local artist_widget = wibox.widget {
 }
 
 -- Get Song Info
-playerctl = bling.signal.playerctl.lib()
+local playerctl = bling.signal.playerctl.lib()
 playerctl:connect_signal("metadata",
-                       function(title, artist, album_path, album, new, player_name)
+                       function(_, title, artist, album_path, album, new, player_name)
     -- Set art widget
     art:set_image(gears.surface.load_uncached(album_path))
 
@@ -130,15 +159,27 @@ Here's another example in which you get a notification with the album art, title
 
 ```lua
 local naughty = require("naughty")
+local playerctl = bling.signal.playerctl.lib()
 
 playerctl:connect_signal("metadata",
-                       function(title, artist, album_path, album, new, player_name)
+                       function(_, title, artist, album_path, album, new, player_name)
     if new == true then
         naughty.notify({title = title, text = artist, image = album_path})
     end
 end)
 ```
 
+We can also link a playerctl function to a button click!
+
+```lua
+local playerctl = bling.signal.playerctl.lib()
+button:buttons(gears.table.join(
+	awful.button({}, 1, function() 
+		playerctl:play_pause()
+	end)
+))
+```
+
 ### Theme Variables and Configuration
 By default, this module will output signals from the most recently active player. If you wish to customize the behavior furthur, the following configuration options are available depending on the selected backend. Here is a summary of the two backends and which configuration options they support.