refining

modules/autostart.lua

@@ -1,10 +1,13 @@
 -- autostart module
+
 -- Libraries and Modules
 local awful = require("awful")
 local sfx = require("modules.sfx")
+
 -- -------------------------------------------------------------------------- --
 -- Autostart Applications
 
+-- Function to run a command once
 local function run_once(cmd)
   local findme = cmd
   local firstspace = cmd:find(" ")
@@ -15,6 +18,7 @@ local function run_once(cmd)
     string.format("pgrep -u $USER -x %s > /dev/null || (%s)", findme, cmd)
   )
 end
+
 -- -------------------------------------------------------------------------- --
 -- Add apps to autostart here via terminal commands in subshells (meaning ending with &)
 autostart_apps = {
@@ -25,6 +29,7 @@ autostart_apps = {
 }
 
 -- -------------------------------------------------------------------------- --
+-- Run the autostart applications
 for app = 1, #autostart_apps do
   run_once(autostart_apps[app])
 end

modules/battery.lua

@@ -1,4 +1,26 @@
 -- original author: Aire-One (https://github.com/Aire-One)
+
+-- This module provides a battery widget for the Awesome Window Manager.
+-- It uses the UPowerGlib library to interact with the system's power devices.
+-- The widget displays information about the battery, such as its charge level and remaining time.
+
+-- The battery_widget module exports the following functions:
+--   - list_devices(): Returns a table containing the paths of all connected power devices.
+--   - get_device(path): Returns the device instance corresponding to the given path.
+--   - get_BAT0_device_path(): Returns the default path for the BAT0 device.
+--   - to_clock(seconds): Converts the given number of seconds into a human-readable clock string.
+--   - new(args): Constructs a new battery widget with the specified arguments.
+
+-- Example usage:
+-- local battery_widget = require("battery_widget")
+-- local widget = battery_widget.new({ device_path = "/org/freedesktop/UPower/devices/battery_BAT0" })
+
+-- The battery widget emits the following signals:
+--   - upower::update(device): Triggered when the device's state is updated.
+
+-- Note: This code is based on the original work by Aire-One (https://github.com/Aire-One).
+-- It has been modified and adapted for use in the Awesome Window Manager.
+-- original author: Aire-One (https://github.com/Aire-One)
 local upower = require("lgi").require("UPowerGlib")
 local gtable = require("gears.table")
 local gtimer = require("gears.timer")

modules/dropdown.lua

@@ -1,9 +1,3 @@
---      _____                      __
---     |     \.----.-----.-----.--|  |.-----.--.--.--.-----.
---     |  --  |   _|  _  |  _  |  _  ||  _  |  |  |  |     |
---     |_____/|__| |_____|   __|_____||_____|________|__|__|
---                       |__|
---   +---------------------------------------------------------------+
 -- Drop-down applications manager for the awesome window manager
 -- Parameters:
 --   prog   - Program to run
@@ -15,8 +9,9 @@
 --   screen - Screen (optional)
 -- based largely off of attachdrop, just streamlined to my use case
 -- https://github.com/tumurzakov/attachdrop
---   +---------------------------------------------------------------+
--- Grab environment
+-- This module provides functionality for creating drop-down windows in the Awesome Window Manager.
+-- It allows attaching a window under the cursor to a specific program and toggling between hidden and visible states.
+
 local pairs = pairs
 local awful = require("awful")
 local setmetatable = setmetatable
@@ -27,39 +22,50 @@ local capi = {
 }
 
 local dropdown = {}
---   +---------------------------------------------------------------+
--- Attach window under cursor to prog
---
+
+-- Attaches a window under the cursor to the specified program.
+-- @param prog The program to attach the window to.
 function dropdown.attach(prog)
+  -- Create a table for the program if it doesn't exist
   if not dropdown[prog] then
     dropdown[prog] = {}
   end
 
-  screen = capi.mouse.screen
-  c = awful.mouse.client_under_pointer()
+  -- Get the current screen and client under the cursor
+  local screen = capi.mouse.screen
+  local c = awful.mouse.client_under_pointer()
+
+  -- Store the client under the program and screen
   dropdown[prog][screen] = c
 end
---   +---------------------------------------------------------------+
--- Create a new window for the drop-down application when it doesn't
--- exist, or toggle between hidden and visible states when it does
+
+-- Creates a new window for the drop-down application when it doesn't exist,
+-- or toggles between hidden and visible states when it does.
+-- @param prog The program to create the window for or toggle.
+-- @param vert (optional) The vertical position of the window ("top", "center", "bottom").
+-- @param horiz (optional) The horizontal position of the window ("left", "center", "right").
+-- @param width (optional) The width of the window (percentage of the screen width or absolute value).
+-- @param height (optional) The height of the window (percentage of the screen height or absolute value).
+-- @param sticky (optional) Whether the window should be sticky (always visible).
+-- @param screen (optional) The screen to create the window on.
 function dropdown.toggle(prog, vert, horiz, width, height, sticky, screen)
+  -- Set default values if not provided
   vert = vert or "top"
   horiz = horiz or "center"
   width = width or 1
   height = height or 0.25
   sticky = sticky or false
   screen = screen or capi.mouse.screen
 
-  -- Determine signal usage in this version of awesome
+  -- Determine signal usage in this version of Awesome
   local attach_signal = capi.client.connect_signal or capi.client.add_signal
-  local detach_signal = capi.client.disconnect_signal
-    or capi.client.remove_signal
+  local detach_signal = capi.client.disconnect_signal or capi.client.remove_signal
 
+  -- Create a table for the program if it doesn't exist
   if not dropdown[prog] then
     dropdown[prog] = {}
-    --   +---------------------------------------------------------------+
-    -- Add unmanage signal for scratchdrop programs
 
+    -- Add an "unmanage" signal to remove the client from the table when it is unmanaged
     attach_signal("unmanage", function(c)
       for scr, cl in pairs(dropdown[prog]) do
         if cl == c then
@@ -69,18 +75,15 @@ function dropdown.toggle(prog, vert, horiz, width, height, sticky, screen)
     end)
   end
 
+  -- If the window doesn't exist, create it
   if not dropdown[prog][screen] then
-    spawnw = function(c)
+    local spawnw = function(c)
       dropdown[prog][screen] = c
 
-      --   +---------------------------------------------------------------+
-      -- Scratchdrop clients are floaters
-      --
+      -- Set the client as a floater
       awful.client.floating.set(c, true)
 
-      --   +---------------------------------------------------------------+
-      -- Client geometry and placement
-      --
+      -- Calculate the window geometry and placement
       local screengeom = capi.screen[screen].workarea
 
       if width <= 1 then
@@ -90,6 +93,7 @@ function dropdown.toggle(prog, vert, horiz, width, height, sticky, screen)
         height = math.ceil(screengeom.height * height)
       end
 
+      local x, y
       if horiz == "left" then
         x = screengeom.x
       elseif horiz == "right" then
@@ -105,9 +109,8 @@ function dropdown.toggle(prog, vert, horiz, width, height, sticky, screen)
       else
         y = screengeom.y
       end
-      --   +---------------------------------------------------------------+
-      -- Client properties
 
+      -- Set the client's geometry and properties
       c:geometry({ x = x, y = y, width = width, height = height })
       c.ontop = true
       c.above = true
@@ -116,36 +119,29 @@ function dropdown.toggle(prog, vert, horiz, width, height, sticky, screen)
       capi.client.focus = c
       detach_signal("manage", spawnw)
     end
-    -- ------------------------------------------------- --
-    -- ------------------------------------------------- --
-    -- ------------------------------------------------- --
-    -- Add manage signal and spawn the program
 
+    -- Add a "manage" signal to create the window and spawn the program
     attach_signal("manage", spawnw)
-    awful.util.spawn_with_shell(prog, false) -- original without '_with_shell'
+    awful.util.spawn_with_shell(prog, false)
   else
-    -- Get a running client
+    -- Get the running client
+    local c = dropdown[prog][screen]
 
-    c = dropdown[prog][screen]
-
-    status, err = pcall(awful.client.movetotag, awful.tag.selected(screen), c)
+    -- Move the client to the current workspace
+    local status, err = pcall(awful.client.movetotag, awful.tag.selected(screen), c)
     if err then
       dropdown[prog][screen] = false
       return
     end
-    --  +---------------------------------------------------------------+
-    -- Switch the client to the current workspace
 
-    if c:isvisible() == false then
+    -- Switch the client to the current workspace if it's hidden
+    if not c:isvisible() then
       c.hidden = true
       awful.client.movetotag(awful.tag.selected(screen), c)
     end
-    --  +---------------------------------------------------------------+
-    -- Focus and raise if hidden
 
+    -- Focus and raise the client if it's hidden
     if c.hidden then
-      -- Make sure it is centered
-
       if vert == "center" then
         awful.placement.center_vertical(c)
       end
@@ -156,8 +152,7 @@ function dropdown.toggle(prog, vert, horiz, width, height, sticky, screen)
       c:raise()
       capi.client.focus = c
     else
-      -- Hide and detach tags if not
-
+      -- Hide and detach tags if the client is not hidden
       c.hidden = true
       local ctags = c:tags()
       for i, t in pairs(ctags) do

modules/icon_theme.lua

@@ -1,14 +1,6 @@
---  _______
--- |_     _|.----.-----.-----.
---  _|   |_ |  __|  _  |     |
--- |_______||____|_____|__|__|
---  _______ __
--- |_     _|  |--.-----.--------.-----.
---   |   | |     |  -__|        |  -__|
---   |___| |__|__|_____|__|__|__|_____|
--- -------------------------------------------------------------------------- --
--- shamelessly stolen from the bling library, awesome work they did with this
---
+-- This module provides functionality for retrieving icons based on various criteria such as process ID, icon name, and class.
+-- It utilizes the lgi library to interact with the Gtk.IconTheme and Gio.AppInfo modules.
+
 local lgi = require("lgi")
 local Gio = lgi.Gio
 local Gtk = lgi.require("Gtk", "3.0")
@@ -23,6 +15,7 @@ local name_lookup = {
     ["jetbrains-studio"] = "android-studio",
 }
 
+-- Retrieves the icon path based on the process ID of the client.
 local function get_icon_by_pid_command(self, client, apps)
     local pid = client.pid
     if pid ~= nil then
@@ -39,6 +32,7 @@ local function get_icon_by_pid_command(self, client, apps)
     end
 end
 
+-- Retrieves the icon path based on the icon name of the client.
 local function get_icon_by_icon_name(self, client, apps)
     local icon_name = client.icon_name and client.icon_name:lower() or nil
     if icon_name ~= nil then
@@ -51,6 +45,7 @@ local function get_icon_by_icon_name(self, client, apps)
     end
 end
 
+-- Retrieves the icon path based on the class of the client.
 local function get_icon_by_class(self, client, apps)
     if client.class ~= nil then
         local class = name_lookup[client.class] or client.class:lower()
@@ -78,6 +73,7 @@ local function get_icon_by_class(self, client, apps)
     end
 end
 
+-- Retrieves the icon path for the client based on various criteria.
 function icon_theme:get_client_icon_path(client)
     local apps = Gio.AppInfo.get_all()
 
@@ -93,6 +89,7 @@ function icon_theme:get_client_icon_path(client)
         })
 end
 
+-- Chooses an icon from the provided list of icon names.
 function icon_theme:choose_icon(icons_names)
     local icon_info = self.gtk_theme:choose_icon(icons_names, self.icon_size, 0)
     if icon_info then
@@ -105,6 +102,7 @@ function icon_theme:choose_icon(icons_names)
     return ""
 end
 
+-- Retrieves the icon path for the given GIcon object.
 function icon_theme:get_gicon_path(gicon)
     if gicon == nil then
         return ""
@@ -121,6 +119,7 @@ function icon_theme:get_gicon_path(gicon)
     return ""
 end
 
+-- Retrieves the icon path for the given icon name.
 function icon_theme:get_icon_path(icon_name)
     local icon_info = self.gtk_theme:lookup_icon(icon_name, self.icon_size, 0)
     if icon_info then
@@ -133,6 +132,7 @@ function icon_theme:get_icon_path(icon_name)
     return ""
 end
 
+-- Creates a new instance of the icon_theme module.
 local function new(theme_name, icon_size)
     local ret = gobject({})
     gtable.crush(ret, icon_theme, true)
@@ -150,6 +150,7 @@ local function new(theme_name, icon_size)
     return ret
 end
 
+-- Allows creating a new instance of the icon_theme module using the syntax `icon_theme()`.
 function icon_theme.mt:__call(...)
     return new(...)
 end

modules/screenshot.lua

@@ -1,7 +1,3 @@
---  _______                                     __           __
--- |     __|.----.----.-----.-----.-----.-----.|  |--.-----.|  |_
--- |__     ||  __|   _|  -__|  -__|     |__ --||     |  _  ||   _|
--- |_______||____|__| |_____|_____|__|__|_____||__|__|_____||____|
 -- -------------------------------------------------------------------------- --
 ---@diagnostic disable: undefined-global
 -- provides a means of taking and automatically handling the naming and saving of a screenshot]

modules/sfx.lua

@@ -10,7 +10,7 @@ function M.play()
   awful.spawn(
     "pacat --property=media.role=event "
       .. gfs.get_configuration_dir()
-      .. "themes/assets/sounds/confirm1.wav"
+      .. "themes/assets/sounds/notify2.wav"
   )
 end