From 4df10bd05a3db59823f62d422392547ff2b7ebd8 Mon Sep 17 00:00:00 2001 From: Gokul Swami Date: Sat, 13 Feb 2021 15:57:52 -0800 Subject: [PATCH 1/7] Init docs to test, in regard of #20 --- docs/.nojekyll | 0 docs/README.md | 256 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.html | 22 +++++ 3 files changed, 278 insertions(+) create mode 100644 docs/.nojekyll create mode 100644 docs/README.md create mode 100644 docs/index.html diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..23c4e51 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,256 @@ +#
🌟 Bling - Utilities for the AwesomeWM 🌟
+ +## ❓ Why + +AwesomeWM is literally that - an awesome window manager. + +It's unique selling point has always been the widget system allowing for fancy buttons, sliders, bars, dashboards and everything you can imagine. But that feature might also be a curse. Most modules focus on the widget side of things which left the actual window managing part of awesomeWM a little underdeveloped compared to for example xmonad even though it's probably just as powerfull in that regard. + +This module is trying to fix exactly that: Adding new layouts and modules that - while making use of the widget system - don't focus on it but on new window managing features. + +## 🧭 Installation and configuration +- `git clone` this repo into your `~/.config/awesome` folder +- Put ``local bling = require("bling")`` somewhere in your ``rc.lua`` (remember to put it under ``beautiful.init...``) + +##### 📎 Layouts + +Choose layouts from the list below and add them to to your `awful.layouts` list in your `rc.lua`. + +Everyone of them supports multiple master clients and master width factor making them as easily useable as the default layouts. +```Lua +bling.layout.mstab +bling.layout.centered +bling.layout.vertical +bling.layout.horizontal +``` + +##### 😋 Window swallowing + +To activate and deactivate window swallowing there are the following functions. If you want to activate it, just call the `start` function once in your `rc.lua`. +```lua +bling.module.window_swallowing.start() -- activates window swallowing +bling.module.window_swallowing.stop() -- deactivates window swallowing +bling.module.window_swallowing.toggle() -- toggles window swallowing +``` + +##### 🏬 Tiled Wallpaper + +The function to set an automatically created tiled wallpaper can be called the follwing way (you don't need to set every option in the table of the last argument since there are reasonable defaults): +```lua +awful.screen.connect_for_each_screen(function(s) -- that way the wallpaper is applied to every screen + bling.module.tiled_wallpaper("x", s, { -- call the actual function ("x" is the string that will be tiled) + fg = "#ff0000", -- define the foreground color + bg = "#00ffff", -- define the background color + offset_y = 25, -- set a y offset + offset_x = 25, -- set a x offset + font = "Hack", -- set the font (without the size) + font_size = 14, -- set the font size + padding = 100, -- set padding (default is 100) + zickzack = true -- rectangular pattern or criss cross + }) +end) +``` + +##### 🎇 Wallpaper easy setup + +This is a simple-to-use, extensible, declarative wallpaper manager. + +###### Practical examples + +```lua +-- A default Awesome wallpaper +bling.module.wallpaper.setup() + +-- A slideshow with pictures from different sources changing every 30 minutes +bling.module.wallpaper.setup { + wallpaper = {"/images/my_dog.jpg", "/images/my_cat.jpg"}, + change_timer = 1800 +} + +-- A random wallpaper with images from multiple folders +bling.module.wallpaper.setup { + set_function = bling.module.wallpaper.setters.random + wallpaper = {"/path/to/a/folder", "/path/to/another/folder"}, + change_timer = 631, -- prime numbers are better for timers + position = "fit", + background = "#424242" +} + +-- wallpapers based on a schedule, like awesome-glorious-widgets dynamic wallpaper +-- https://github.com/manilarome/awesome-glorious-widgets/tree/master/dynamic-wallpaper +bling.module.wallpaper.setup { + set_function = wallpaper.setters.simple_schedule, + wallpaper = { + ["06:22:00"] = "morning-wallpaper.jpg", + ["12:00:00"] = "noon-wallpaper.jpg", + ["17:58:00"] = "night-wallpaper.jpg", + ["24:00:00"] = "midnight-wallpaper.jpg", + }, + position = "maximized", +} + +-- random wallpapers, from different folder depending on time of the day +bling.module.wallpaper.setup { + set_function = bling.module.wallpaper.setters.simple_schedule, + wallpaper = { + ["09:00:00"] = "~/Pictures/safe_for_work", + ["18:00:00"] = "~/Pictures/personal", + }, + schedule_set_function = bling.module.wallpaper.setters.random + position = "maximized", + recursive = false, + change_timer = 600 +} +``` +###### Details + +The setup function will do 2 things: call the set-function when awesome requests a wallpaper, and manage a timer to call `set_function` periodically. + +Its argument is a args table that is passed to ohter functions (setters and wallpaper functions), so you define everything with setup. + +The `set_function` is a function called every times a wallpaper is needed. + +The module provides some setters: + +* `bling.module.wallpaper.setters.awesome_wallpaper`: beautiful.theme_assets.wallpaper with defaults from beautiful. +* `bling.module.wallpaper.setters.simple`: slideshow from the `wallpaper` argument. +* `bling.module.wallpaper.setters.random`: same as simple but in a random way. +* `bling.module.wallpaper.setters.simple_schedule`: takes a table of `["HH:MM:SS"] = wallpaper` arguments, where wallpaper is the `wallpaper` argument used by `schedule_set_function`. + +A wallpaper is one of the following elements: + +* a color +* an image +* a folder containing images +* a function that sets a wallpaper +* everything gears.wallpaper functions can manage (cairo surface, cairo pattern string) +* a list containing any of the elements above +```lua +-- This is a valid wallpaper definition +bling.module.wallpaper.setup { + wallpaper = { -- a list + "black", "#112233", -- colors + "wall1.jpg", "wall2.png", -- files + "/path/to/wallpapers", -- folders + -- cairo patterns + "radial:600,50,100:105,550,900:0,#2200ff:0.5,#00ff00:1,#101010", + -- or functions that set a wallpaper + function(args) bling.module.tiled_wallpaper("\\o/", args.screen) end, + bling.module.wallpaper.setters.awesome_wallpaper, + }, + change_timer = 10, +} +``` +The provided setters `simple` and `random` will use 2 internal functions that you can use to write your own setter: + +* `bling.module.wallpaper.prepare_list`: return a list of wallpapers directly usable by `apply` (for now, it just explores folders) +* `bling.module.wallpaper.apply`: a wrapper for gears.wallpaper functions, using the args table of setup + +Here are the defaults: +```lua +-- Default parameters +bling.module.wallpaper.setup { + screen = nil, -- the screen to apply the wallpaper, as seen in gears.wallpaper functions + change_timer = nil, -- the timer in seconds. If set, call the set_function every change_timer seconds + set_function = nil, -- the setter function + + -- parameters used by bling.module.wallpaper.prepare_list + wallpaper = nil, -- the wallpaper object, see simple or simple_schedule documentation + image_formats = {"jpg", "jpeg", "png", "bmp"}, -- when searching in folder, consider these files only + recursive = true, -- when searching in folder, search also in subfolders + + -- parameters used by bling.module.wallpaper.apply + position = nil, -- use a function of gears.wallpaper when applicable ("centered", "fit", "maximized", "tiled") + background = beautiful.bg_normal or "black", -- see gears.wallpaper functions + ignore_aspect = false, -- see gears.wallpaper.maximized + offset = {x = 0, y = 0}, -- see gears.wallpaper functions + scale = 1, -- see gears.wallpaper.centered + + -- parameters that only apply to bling.module.wallpaper.setter.awesome (as a setter or as a wallpaper function) + colors = { -- see beautiful.theme_assets.wallpaper + bg = beautiful.bg_color, -- the actual default is this color but darkened or lightned + fg = beautiful.fg_color, + alt_fg = beautiful.fg_focus + } +} +``` + +Check documentation in [module/wallpaper.lua](module/wallpaper.lua) for more details. + + +##### 🔦 Flash Focus + +There are two ways you can use this module. You can just enable it by calling the `enable()` function: +```lua +bling.module.flash_focus.enable() +``` +This connects to the focus signal of a client, which means that the flash focus will activate however you focus the client. + +The other way is to call the function itself like this: `bling.module.flash_focus.flashfocus(someclient)`. This allows you to just activate on certain keybinds: +```lua +awful.key({modkey}, "Up", + function() + awful.client.focus.bydirection("up") + bling.module.flash_focus.flashfocus(client.focus) + end, {description = "focus up", group = "client"}) +``` + +##### 📑 Tabbing + +You should bind these functions to keys in oder to use the tabbed module effectively: +```lua +bling.module.tabbed.pick() -- picks a client with your cursor to add to the tabbing group +bling.module.tabbed.pop() -- removes the focused client from the tabbing group +bling.module.tabbed.iter() -- iterates through the currently focused tabbing group +bling.module.tabbed.pick_with_dmenu() -- picks a client with a dmenu application (defaults to rofi, other options can be set with a string parameter like "dmenu") +``` + + +### 🌈 Theme variables +You will find a list of all theme variables that are used in bling and comments on what they do in the `theme-var-template.lua` file - ready for you to copy them into your `theme.lua`. Theme variables are not only used to change the appearance of some features but also to adjust the functionality of some modules. So it is worth it to take a look at them. + +## 😲 Preview + +### Tabbing +![](https://imgur.com/08AlNhQ.png) + +screenshot by [javacafe](https://github.com/JavaCafe01) + +### Mstab (dynamic tabbing layout) +![](https://imgur.com/HZRgApE.png) + +screenshot by [javacafe](https://github.com/JavaCafe01) + +### Centered +![](https://media.discordapp.net/attachments/769673106842845194/780095998239834142/unknown.png) + +screenshot by [branwright](https://github.com/branwright1) + +### Tiled Wallpaper +![](https://media.discordapp.net/attachments/702548913999314964/773887721294135296/tiled-wallpapers.png?width=1920&height=1080) + +screenshots by me + +### Flash Focus +![](https://imgur.com/5txYrlV.gif) + +gif by [javacafe](https://github.com/JavaCafe01) + +### Wind swallowing +![](https://media.discordapp.net/attachments/635625813143978012/769180910683684864/20-10-23-14-40-32.gif) + +gif by me :) + +## TODO +- [ ] Add external sources management for the wallpaper module (URLs, RSS feeds, NASA picture of the day, ...) +- [ ] Scratchpad module +- [x] Some more documentation on the tabbed module +- [x] Add a cool alternative tabbar style +- [x] Add another cool tabbar style (we need more styles) +- [x] Make the mstab layout compatible with vertical tabbars (left and right) +- [x] Add option to mstab layout to not shrink windows down when they are in the tabbed pane and unfocused (for example for people using transparent terminals) +- [x] Keyboard based option to add windows to a tabbing object + +All naming credit goes to javacafe. + +Contributions are welcomed 💛 diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..04dd4a7 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,22 @@ + + + + + Document + + + + + + +
+ + + + + From 56b72f89f91735de83d983fae07b503d3f99884e Mon Sep 17 00:00:00 2001 From: Gokul Swami Date: Tue, 16 Feb 2021 02:47:43 -0800 Subject: [PATCH 2/7] Finished docs! --- docs/README.md | 259 +++-------------------------------------- docs/_sidebar.md | 16 +++ docs/index.html | 9 +- docs/layouts/layout.md | 44 +++++++ docs/module/flash.md | 27 +++++ docs/module/swal.md | 21 ++++ docs/module/tabbed.md | 40 +++++++ docs/module/twall.md | 23 ++++ docs/module/wall.md | 127 ++++++++++++++++++++ docs/signals/pctl.md | 57 +++++++++ docs/theme.md | 54 +++++++++ 11 files changed, 429 insertions(+), 248 deletions(-) create mode 100644 docs/_sidebar.md create mode 100644 docs/layouts/layout.md create mode 100644 docs/module/flash.md create mode 100644 docs/module/swal.md create mode 100644 docs/module/tabbed.md create mode 100644 docs/module/twall.md create mode 100644 docs/module/wall.md create mode 100644 docs/signals/pctl.md create mode 100644 docs/theme.md diff --git a/docs/README.md b/docs/README.md index 23c4e51..c90f27c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,256 +1,25 @@ -#
🌟 Bling - Utilities for the AwesomeWM 🌟
+#
🌟 Bling - Utilities for AwesomeWM 🌟
-## ❓ Why +## Why -AwesomeWM is literally that - an awesome window manager. +[AwesomeWM](https://awesomewm.org/) is literally what it stands for, an awesome window manager. -It's unique selling point has always been the widget system allowing for fancy buttons, sliders, bars, dashboards and everything you can imagine. But that feature might also be a curse. Most modules focus on the widget side of things which left the actual window managing part of awesomeWM a little underdeveloped compared to for example xmonad even though it's probably just as powerfull in that regard. +Its unique selling point has always been the widget system, which allows for fancy buttons, sliders, bars, dashboards and anything you can imagine. But that feature can be a curse. Most modules focus on the widget side of things which leave the actual window managing part of AwesomeWM underdeveloped compared to, for example, [xmonad](https://xmonad.org/) even though it's probably just as powerfull in that area. -This module is trying to fix exactly that: Adding new layouts and modules that - while making use of the widget system - don't focus on it but on new window managing features. +This project focuses on that problem - adding new layouts and modules that make use of the widget system, but primarily focus on the new window managing features. -## 🧭 Installation and configuration -- `git clone` this repo into your `~/.config/awesome` folder -- Put ``local bling = require("bling")`` somewhere in your ``rc.lua`` (remember to put it under ``beautiful.init...``) - -##### 📎 Layouts - -Choose layouts from the list below and add them to to your `awful.layouts` list in your `rc.lua`. - -Everyone of them supports multiple master clients and master width factor making them as easily useable as the default layouts. -```Lua -bling.layout.mstab -bling.layout.centered -bling.layout.vertical -bling.layout.horizontal -``` - -##### 😋 Window swallowing - -To activate and deactivate window swallowing there are the following functions. If you want to activate it, just call the `start` function once in your `rc.lua`. -```lua -bling.module.window_swallowing.start() -- activates window swallowing -bling.module.window_swallowing.stop() -- deactivates window swallowing -bling.module.window_swallowing.toggle() -- toggles window swallowing -``` - -##### 🏬 Tiled Wallpaper - -The function to set an automatically created tiled wallpaper can be called the follwing way (you don't need to set every option in the table of the last argument since there are reasonable defaults): -```lua -awful.screen.connect_for_each_screen(function(s) -- that way the wallpaper is applied to every screen - bling.module.tiled_wallpaper("x", s, { -- call the actual function ("x" is the string that will be tiled) - fg = "#ff0000", -- define the foreground color - bg = "#00ffff", -- define the background color - offset_y = 25, -- set a y offset - offset_x = 25, -- set a x offset - font = "Hack", -- set the font (without the size) - font_size = 14, -- set the font size - padding = 100, -- set padding (default is 100) - zickzack = true -- rectangular pattern or criss cross - }) -end) -``` - -##### 🎇 Wallpaper easy setup - -This is a simple-to-use, extensible, declarative wallpaper manager. - -###### Practical examples +## Installation +- clone this repo into your `~/.config/awesome` folder + - `git clone https://github.com/Nooo37/bling.git ~/.config/awesome/bling` +- require the module in your `rc.lua`, and make sure it's under the beautiful module initialization ```lua --- A default Awesome wallpaper -bling.module.wallpaper.setup() +-- other imports --- A slideshow with pictures from different sources changing every 30 minutes -bling.module.wallpaper.setup { - wallpaper = {"/images/my_dog.jpg", "/images/my_cat.jpg"}, - change_timer = 1800 -} +local beautiful = require("beautiful") --- A random wallpaper with images from multiple folders -bling.module.wallpaper.setup { - set_function = bling.module.wallpaper.setters.random - wallpaper = {"/path/to/a/folder", "/path/to/another/folder"}, - change_timer = 631, -- prime numbers are better for timers - position = "fit", - background = "#424242" -} +-- other configuration stuff here --- wallpapers based on a schedule, like awesome-glorious-widgets dynamic wallpaper --- https://github.com/manilarome/awesome-glorious-widgets/tree/master/dynamic-wallpaper -bling.module.wallpaper.setup { - set_function = wallpaper.setters.simple_schedule, - wallpaper = { - ["06:22:00"] = "morning-wallpaper.jpg", - ["12:00:00"] = "noon-wallpaper.jpg", - ["17:58:00"] = "night-wallpaper.jpg", - ["24:00:00"] = "midnight-wallpaper.jpg", - }, - position = "maximized", -} - --- random wallpapers, from different folder depending on time of the day -bling.module.wallpaper.setup { - set_function = bling.module.wallpaper.setters.simple_schedule, - wallpaper = { - ["09:00:00"] = "~/Pictures/safe_for_work", - ["18:00:00"] = "~/Pictures/personal", - }, - schedule_set_function = bling.module.wallpaper.setters.random - position = "maximized", - recursive = false, - change_timer = 600 -} +beautiful.init("some_theme.lua") +local bling = require("bling") ``` -###### Details - -The setup function will do 2 things: call the set-function when awesome requests a wallpaper, and manage a timer to call `set_function` periodically. - -Its argument is a args table that is passed to ohter functions (setters and wallpaper functions), so you define everything with setup. - -The `set_function` is a function called every times a wallpaper is needed. - -The module provides some setters: - -* `bling.module.wallpaper.setters.awesome_wallpaper`: beautiful.theme_assets.wallpaper with defaults from beautiful. -* `bling.module.wallpaper.setters.simple`: slideshow from the `wallpaper` argument. -* `bling.module.wallpaper.setters.random`: same as simple but in a random way. -* `bling.module.wallpaper.setters.simple_schedule`: takes a table of `["HH:MM:SS"] = wallpaper` arguments, where wallpaper is the `wallpaper` argument used by `schedule_set_function`. - -A wallpaper is one of the following elements: - -* a color -* an image -* a folder containing images -* a function that sets a wallpaper -* everything gears.wallpaper functions can manage (cairo surface, cairo pattern string) -* a list containing any of the elements above -```lua --- This is a valid wallpaper definition -bling.module.wallpaper.setup { - wallpaper = { -- a list - "black", "#112233", -- colors - "wall1.jpg", "wall2.png", -- files - "/path/to/wallpapers", -- folders - -- cairo patterns - "radial:600,50,100:105,550,900:0,#2200ff:0.5,#00ff00:1,#101010", - -- or functions that set a wallpaper - function(args) bling.module.tiled_wallpaper("\\o/", args.screen) end, - bling.module.wallpaper.setters.awesome_wallpaper, - }, - change_timer = 10, -} -``` -The provided setters `simple` and `random` will use 2 internal functions that you can use to write your own setter: - -* `bling.module.wallpaper.prepare_list`: return a list of wallpapers directly usable by `apply` (for now, it just explores folders) -* `bling.module.wallpaper.apply`: a wrapper for gears.wallpaper functions, using the args table of setup - -Here are the defaults: -```lua --- Default parameters -bling.module.wallpaper.setup { - screen = nil, -- the screen to apply the wallpaper, as seen in gears.wallpaper functions - change_timer = nil, -- the timer in seconds. If set, call the set_function every change_timer seconds - set_function = nil, -- the setter function - - -- parameters used by bling.module.wallpaper.prepare_list - wallpaper = nil, -- the wallpaper object, see simple or simple_schedule documentation - image_formats = {"jpg", "jpeg", "png", "bmp"}, -- when searching in folder, consider these files only - recursive = true, -- when searching in folder, search also in subfolders - - -- parameters used by bling.module.wallpaper.apply - position = nil, -- use a function of gears.wallpaper when applicable ("centered", "fit", "maximized", "tiled") - background = beautiful.bg_normal or "black", -- see gears.wallpaper functions - ignore_aspect = false, -- see gears.wallpaper.maximized - offset = {x = 0, y = 0}, -- see gears.wallpaper functions - scale = 1, -- see gears.wallpaper.centered - - -- parameters that only apply to bling.module.wallpaper.setter.awesome (as a setter or as a wallpaper function) - colors = { -- see beautiful.theme_assets.wallpaper - bg = beautiful.bg_color, -- the actual default is this color but darkened or lightned - fg = beautiful.fg_color, - alt_fg = beautiful.fg_focus - } -} -``` - -Check documentation in [module/wallpaper.lua](module/wallpaper.lua) for more details. - - -##### 🔦 Flash Focus - -There are two ways you can use this module. You can just enable it by calling the `enable()` function: -```lua -bling.module.flash_focus.enable() -``` -This connects to the focus signal of a client, which means that the flash focus will activate however you focus the client. - -The other way is to call the function itself like this: `bling.module.flash_focus.flashfocus(someclient)`. This allows you to just activate on certain keybinds: -```lua -awful.key({modkey}, "Up", - function() - awful.client.focus.bydirection("up") - bling.module.flash_focus.flashfocus(client.focus) - end, {description = "focus up", group = "client"}) -``` - -##### 📑 Tabbing - -You should bind these functions to keys in oder to use the tabbed module effectively: -```lua -bling.module.tabbed.pick() -- picks a client with your cursor to add to the tabbing group -bling.module.tabbed.pop() -- removes the focused client from the tabbing group -bling.module.tabbed.iter() -- iterates through the currently focused tabbing group -bling.module.tabbed.pick_with_dmenu() -- picks a client with a dmenu application (defaults to rofi, other options can be set with a string parameter like "dmenu") -``` - - -### 🌈 Theme variables -You will find a list of all theme variables that are used in bling and comments on what they do in the `theme-var-template.lua` file - ready for you to copy them into your `theme.lua`. Theme variables are not only used to change the appearance of some features but also to adjust the functionality of some modules. So it is worth it to take a look at them. - -## 😲 Preview - -### Tabbing -![](https://imgur.com/08AlNhQ.png) - -screenshot by [javacafe](https://github.com/JavaCafe01) - -### Mstab (dynamic tabbing layout) -![](https://imgur.com/HZRgApE.png) - -screenshot by [javacafe](https://github.com/JavaCafe01) - -### Centered -![](https://media.discordapp.net/attachments/769673106842845194/780095998239834142/unknown.png) - -screenshot by [branwright](https://github.com/branwright1) - -### Tiled Wallpaper -![](https://media.discordapp.net/attachments/702548913999314964/773887721294135296/tiled-wallpapers.png?width=1920&height=1080) - -screenshots by me - -### Flash Focus -![](https://imgur.com/5txYrlV.gif) - -gif by [javacafe](https://github.com/JavaCafe01) - -### Wind swallowing -![](https://media.discordapp.net/attachments/635625813143978012/769180910683684864/20-10-23-14-40-32.gif) - -gif by me :) - -## TODO -- [ ] Add external sources management for the wallpaper module (URLs, RSS feeds, NASA picture of the day, ...) -- [ ] Scratchpad module -- [x] Some more documentation on the tabbed module -- [x] Add a cool alternative tabbar style -- [x] Add another cool tabbar style (we need more styles) -- [x] Make the mstab layout compatible with vertical tabbars (left and right) -- [x] Add option to mstab layout to not shrink windows down when they are in the tabbed pane and unfocused (for example for people using transparent terminals) -- [x] Keyboard based option to add windows to a tabbing object - -All naming credit goes to javacafe. - -Contributions are welcomed 💛 diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 0000000..c2d87f1 --- /dev/null +++ b/docs/_sidebar.md @@ -0,0 +1,16 @@ +- [Home](/) + +- [Layouts](layouts/layout.md) + +- Modules + - [Flash Focus](module/flash.md) + - [Tabbed](module/tabbed.md) + - [Tiled Wallpaper](module/twall.md) + - [Wallpaper Easy Setup](module/wall.md) + - [Window Swallowing](module/swal.md) + +- Signals + - [Playerctl](signals/pctl.md) + +- Extra + - [Theme Variable Template](theme.md) diff --git a/docs/index.html b/docs/index.html index 04dd4a7..2c0472e 100644 --- a/docs/index.html +++ b/docs/index.html @@ -6,17 +6,20 @@ - +
+ diff --git a/docs/layouts/layout.md b/docs/layouts/layout.md new file mode 100644 index 0000000..97c8ab6 --- /dev/null +++ b/docs/layouts/layout.md @@ -0,0 +1,44 @@ +## 📎 Layouts + +Choose layouts from the list below and add them to to your `awful.layouts` list in your `rc.lua`. + +Everyone of them supports multiple master clients and master width factor making them easy to use. + +The mstab layout uses the tab theme from the tabbed module. + +```Lua +bling.layout.mstab +bling.layout.centered +bling.layout.vertical +bling.layout.horizontal +``` + +### Theme Variables +```lua +-- mstab +theme.mstab_bar_ontop = false -- whether you want to allow the bar to be ontop of clients +theme.mstab_dont_resize_slaves = false -- whether the tabbed stack windows should be smaller than the + -- currently focused stack window (set it to true if you use + -- transparent terminals. False if you use shadows on solid ones +theme.mstab_bar_padding = "default" -- how much padding there should be between clients and your tabbar + -- by default it will adjust based on your useless gaps. + -- If you want a custom value. Set it to the number of pixels (int) +theme.mstab_border_radius = 0 -- border radius of the tabbar +theme.mstab_bar_height = 40 -- height of the tabbar +theme.mstab_tabbar_position = "top" -- position of the tabbar (mstab currently does not support left,right) +theme.mstab_tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern") + -- defaults to the tabbar_style so only change if you want a + -- different style for mstab and tabbed +``` + +### Previews + +#### Mstab (dynamic tabbing layout) +![](https://imgur.com/HZRgApE.png) + +*screenshot by [javacafe](https://github.com/JavaCafe01)* + +#### Centered +![](https://media.discordapp.net/attachments/769673106842845194/780095998239834142/unknown.png) + +*screenshot by [branwright](https://github.com/branwright1)* diff --git a/docs/module/flash.md b/docs/module/flash.md new file mode 100644 index 0000000..da80d4b --- /dev/null +++ b/docs/module/flash.md @@ -0,0 +1,27 @@ +## 🔦 Flash Focus + +Flash focus does an opacity animation effect on a client when it is focused. +![](https://imgur.com/5txYrlV.gif) +*gif by [JavaCafe01](https://github.com/JavaCafe01)* + +### Usage + +There are two ways in which you can use this module. You can enable it by calling the `enable()` function: +```lua +bling.module.flash_focus.enable() +``` +This connects to the focus signal of a client, which means that the flash focus will activate however you focus the client. + +The other way is to call the function itself like this: `bling.module.flash_focus.flashfocus(someclient)`. This allows you to activate on certain keybinds like so: +```lua +awful.key({modkey}, "Up", + function() + awful.client.focus.bydirection("up") + bling.module.flash_focus.flashfocus(client.focus) + end, {description = "focus up", group = "client"}) +``` +### Theme Variables +```lua +theme.flash_focus_start_opacity = 0.6 -- the starting opacity +theme.flash_focus_step = 0.01 -- the step of animation +``` diff --git a/docs/module/swal.md b/docs/module/swal.md new file mode 100644 index 0000000..3b06a6f --- /dev/null +++ b/docs/module/swal.md @@ -0,0 +1,21 @@ +## 😋 Window Swallowing + +Can your window manager swallow? It probably can... +![](https://media.discordapp.net/attachments/635625813143978012/769180910683684864/20-10-23-14-40-32.gif) + +*gif by [Nooo37](https://github.com/Nooo37)* + +### Usage + +To activate and deactivate window swallowing here are the following functions. If you want to activate it, just call the `start` function once in your `rc.lua`. +```lua +bling.module.window_swallowing.start() -- activates window swallowing +bling.module.window_swallowing.stop() -- deactivates window swallowing +bling.module.window_swallowing.toggle() -- toggles window swallowing +``` + +### Theme Variables +```lua +theme.dont_swallow_classname_list = {"firefox", "Gimp"} -- list of class names that should not be swallowed +theme.dont_swallow_filter_activated = true -- whether the filter above should be active +``` diff --git a/docs/module/tabbed.md b/docs/module/tabbed.md new file mode 100644 index 0000000..a5d8166 --- /dev/null +++ b/docs/module/tabbed.md @@ -0,0 +1,40 @@ +## 📑 Tabbed + +Tabbed implements a tab container. There are also different themes for the tabs. This is the modern theme: +![](https://imgur.com/omowmIQ.png) + +*screenshot by [javacafe](https://github.com/JavaCafe01)* + +### Usage + +You should bind these functions to keys in order to use the tabbed module effectively: +```lua +bling.module.tabbed.pick() -- picks a client with your cursor to add to the tabbing group +bling.module.tabbed.pop() -- removes the focused client from the tabbing group +bling.module.tabbed.iter() -- iterates through the currently focused tabbing group +bling.module.tabbed.pick_with_dmenu() -- picks a client with a dmenu application (defaults to rofi, other options can be set with a string parameter like "dmenu") +``` + +### Theme Variables + +```lua +-- For tabbed only +theme.tabbed_spawn_in_tab = false -- whether a new client should spawn into the focused tabbing container + +-- For tabbar in general +theme.tabbar_ontop = false +theme.tabbar_radius = 0 -- border radius of the tabbar +theme.tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern") +theme.tabbar_font = "Sans 11" -- font of the tabbar +theme.tabbar_size = 40 -- size of the tabbar +theme.tabbar_position = "top" -- position of the tabbar +theme.tabbar_bg_normal = "#000000" -- background color of the focused client on the tabbar +theme.tabbar_fg_normal = "#ffffff" -- foreground color of the focused client on the tabbar +theme.tabbar_bg_focus = "#1A2026" -- background color of unfocused clients on the tabbar +theme.tabbar_fg_focus = "#ff0000" -- foreground color of unfocused clients on the tabbar + +-- the following variables are currently only for the "modern" tabbar style +theme.tabbar_color_close = "#f9929b" -- chnges the color of the close button +theme.tabbar_color_min = "#fbdf90" -- chnges the color of the minimize button +theme.tabbar_color_float = "#ccaced" -- chnges the color of the float button +``` diff --git a/docs/module/twall.md b/docs/module/twall.md new file mode 100644 index 0000000..eedcc6d --- /dev/null +++ b/docs/module/twall.md @@ -0,0 +1,23 @@ +## 🏬 Tiled Wallpaper + +![](https://media.discordapp.net/attachments/702548913999314964/773887721294135296/tiled-wallpapers.png?width=1920&height=1080) + +*screenshots by [Nooo37](https://github.com/Nooo37)* + +### Usage + +The function to set an automatically created tiled wallpaper can be called the following way (you don't need to set every option in the table): +```lua +awful.screen.connect_for_each_screen(function(s) -- that way the wallpaper is applied to every screen + bling.module.tiled_wallpaper("x", s, { -- call the actual function ("x" is the string that will be tiled) + fg = "#ff0000", -- define the foreground color + bg = "#00ffff", -- define the background color + offset_y = 25, -- set a y offset + offset_x = 25, -- set a x offset + font = "Hack", -- set the font (without the size) + font_size = 14, -- set the font size + padding = 100, -- set padding (default is 100) + zickzack = true -- rectangular pattern or criss cross + }) +end) +``` diff --git a/docs/module/wall.md b/docs/module/wall.md new file mode 100644 index 0000000..12a5e4d --- /dev/null +++ b/docs/module/wall.md @@ -0,0 +1,127 @@ +## 🎇 Wallpaper Easy Setup + +This is a simple-to-use, extensible, declarative wallpaper manager. + +### Practical Examples + +```lua +-- A default Awesome wallpaper +bling.module.wallpaper.setup() + +-- A slideshow with pictures from different sources changing every 30 minutes +bling.module.wallpaper.setup { + wallpaper = {"/images/my_dog.jpg", "/images/my_cat.jpg"}, + change_timer = 1800 +} + +-- A random wallpaper with images from multiple folders +bling.module.wallpaper.setup { + set_function = bling.module.wallpaper.setters.random + wallpaper = {"/path/to/a/folder", "/path/to/another/folder"}, + change_timer = 631, -- prime numbers are better for timers + position = "fit", + background = "#424242" +} + +-- wallpapers based on a schedule, like awesome-glorious-widgets dynamic wallpaper +-- https://github.com/manilarome/awesome-glorious-widgets/tree/master/dynamic-wallpaper +bling.module.wallpaper.setup { + set_function = wallpaper.setters.simple_schedule, + wallpaper = { + ["06:22:00"] = "morning-wallpaper.jpg", + ["12:00:00"] = "noon-wallpaper.jpg", + ["17:58:00"] = "night-wallpaper.jpg", + ["24:00:00"] = "midnight-wallpaper.jpg", + }, + position = "maximized", +} + +-- random wallpapers, from different folder depending on time of the day +bling.module.wallpaper.setup { + set_function = bling.module.wallpaper.setters.simple_schedule, + wallpaper = { + ["09:00:00"] = "~/Pictures/safe_for_work", + ["18:00:00"] = "~/Pictures/personal", + }, + schedule_set_function = bling.module.wallpaper.setters.random + position = "maximized", + recursive = false, + change_timer = 600 +} +``` +### Details + +The setup function will do 2 things: call the set-function when awesome requests a wallpaper, and manage a timer to call `set_function` periodically. + +Its argument is a args table that is passed to ohter functions (setters and wallpaper functions), so you define everything with setup. + +The `set_function` is a function called every times a wallpaper is needed. + +The module provides some setters: + +* `bling.module.wallpaper.setters.awesome_wallpaper`: beautiful.theme_assets.wallpaper with defaults from beautiful. +* `bling.module.wallpaper.setters.simple`: slideshow from the `wallpaper` argument. +* `bling.module.wallpaper.setters.random`: same as simple but in a random way. +* `bling.module.wallpaper.setters.simple_schedule`: takes a table of `["HH:MM:SS"] = wallpaper` arguments, where wallpaper is the `wallpaper` argument used by `schedule_set_function`. + +A wallpaper is one of the following elements: + +* a color +* an image +* a folder containing images +* a function that sets a wallpaper +* everything gears.wallpaper functions can manage (cairo surface, cairo pattern string) +* a list containing any of the elements above + +```lua +-- This is a valid wallpaper definition +bling.module.wallpaper.setup { + wallpaper = { -- a list + "black", "#112233", -- colors + "wall1.jpg", "wall2.png", -- files + "/path/to/wallpapers", -- folders + -- cairo patterns + "radial:600,50,100:105,550,900:0,#2200ff:0.5,#00ff00:1,#101010", + -- or functions that set a wallpaper + function(args) bling.module.tiled_wallpaper("\\o/", args.screen) end, + bling.module.wallpaper.setters.awesome_wallpaper, + }, + change_timer = 10, +} +``` +The provided setters `simple` and `random` will use 2 internal functions that you can use to write your own setter: + +* `bling.module.wallpaper.prepare_list`: return a list of wallpapers directly usable by `apply` (for now, it just explores folders) +* `bling.module.wallpaper.apply`: a wrapper for gears.wallpaper functions, using the args table of setup + +Here are the defaults: + +```lua +-- Default parameters +bling.module.wallpaper.setup { + screen = nil, -- the screen to apply the wallpaper, as seen in gears.wallpaper functions + change_timer = nil, -- the timer in seconds. If set, call the set_function every change_timer seconds + set_function = nil, -- the setter function + + -- parameters used by bling.module.wallpaper.prepare_list + wallpaper = nil, -- the wallpaper object, see simple or simple_schedule documentation + image_formats = {"jpg", "jpeg", "png", "bmp"}, -- when searching in folder, consider these files only + recursive = true, -- when searching in folder, search also in subfolders + + -- parameters used by bling.module.wallpaper.apply + position = nil, -- use a function of gears.wallpaper when applicable ("centered", "fit", "maximized", "tiled") + background = beautiful.bg_normal or "black", -- see gears.wallpaper functions + ignore_aspect = false, -- see gears.wallpaper.maximized + offset = {x = 0, y = 0}, -- see gears.wallpaper functions + scale = 1, -- see gears.wallpaper.centered + + -- parameters that only apply to bling.module.wallpaper.setter.awesome (as a setter or as a wallpaper function) + colors = { -- see beautiful.theme_assets.wallpaper + bg = beautiful.bg_color, -- the actual default is this color but darkened or lightned + fg = beautiful.fg_color, + alt_fg = beautiful.fg_focus + } +} +``` + +Check documentation in [module/wallpaper.lua](module/wallpaper.lua) for more details. diff --git a/docs/signals/pctl.md b/docs/signals/pctl.md new file mode 100644 index 0000000..833a6ea --- /dev/null +++ b/docs/signals/pctl.md @@ -0,0 +1,57 @@ +## 🎵 Playerctl + +This is a signal module in which you can connect to certain bling signals to grab playerctl info. Currently, this is what it supports: + +- Song title and artist +- Album art (the path this module downloaded the art to) +- If playing or not +- Position +- Song length + +This module relies on `playerctl` and `curl`. If you have this module disabled, you won't need those programs. With this module, you can create a widget like below without worrying about the backend. + +![](https://user-images.githubusercontent.com/33443763/107377569-fa807900-6a9f-11eb-93c1-174c58eb7bf1.png) + +*screenshot by [javacafe](https://github.com/JavaCafe01)* + +### Usage + +To enable: `bling.signal.playerctl.enable()` + +Here are the signals available: + +```lua +-- bling::playerctl::status -- first line is the signal +-- playing (boolean) -- indented lines are function parameters +-- bling::playerctl::album +-- album_art (string) +-- bling::playerctl::title_artist +-- title (string) +-- artist (string) +-- bling::playerctl::position +-- interval_sec (number) +-- length_sec (number) +``` + +### 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: +```lua +local art = wibox.widget { + image = "default_image.png", + resize = true, + forced_height = dpi(80), + forced_width = dpi(80), + widget = wibox.widget.imagebox +} + +awesome.connect_signal("bling::playerctl::album", function(path) + art:set_image(gears.surface.load_uncached(path)) +end) +``` +Thats all! You don't even have to worry about updating the imagebox, the signals will handle that for you. + +### Theme Variables +```lua +theme.playerctl_position_update_interval = 1 -- the update interval for fetching the position from playerctl +``` diff --git a/docs/theme.md b/docs/theme.md new file mode 100644 index 0000000..5814a2e --- /dev/null +++ b/docs/theme.md @@ -0,0 +1,54 @@ +```lua +--[[ Bling theme variables template +This file has all theme variables of the bling module. +Every variable has a small comment on what it does. +You might just want to copy that whole part into your theme.lua and start adjusting from there. +--]] + + +-- window swallowing +theme.dont_swallow_classname_list = {"firefox", "Gimp"} -- list of class names that should not be swallowed +theme.dont_swallow_filter_activated = true -- whether the filter above should be active + +-- flash focus +theme.flash_focus_start_opacity = 0.6 -- the starting opacity +theme.flash_focus_step = 0.01 -- the step of animation + +-- playerctl signal +theme.playerctl_position_update_interval = 1 -- the update interval for fetching the position from playerctl + +-- tabbed +theme.tabbed_spawn_in_tab = false -- whether a new client should spawn into the focused tabbing container + +-- tabbar general +theme.tabbar_ontop = false +theme.tabbar_radius = 0 -- border radius of the tabbar +theme.tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern") +theme.tabbar_font = "Sans 11" -- font of the tabbar +theme.tabbar_size = 40 -- size of the tabbar +theme.tabbar_position = "top" -- position of the tabbar +theme.tabbar_bg_normal = "#000000" -- background color of the focused client on the tabbar +theme.tabbar_fg_normal = "#ffffff" -- foreground color of the focused client on the tabbar +theme.tabbar_bg_focus = "#1A2026" -- background color of unfocused clients on the tabbar +theme.tabbar_fg_focus = "#ff0000" -- foreground color of unfocused clients on the tabbar + +-- mstab +theme.mstab_bar_ontop = false -- whether you want to allow the bar to be ontop of clients +theme.mstab_dont_resize_slaves = false -- whether the tabbed stack windows should be smaller than the + -- currently focused stack window (set it to true if you use + -- transparent terminals. False if you use shadows on solid ones +theme.mstab_bar_padding = "default" -- how much padding there should be between clients and your tabbar + -- by default it will adjust based on your useless gaps. + -- If you want a custom value. Set it to the number of pixels (int) +theme.mstab_border_radius = 0 -- border radius of the tabbar +theme.mstab_bar_height = 40 -- height of the tabbar +theme.mstab_tabbar_position = "top" -- position of the tabbar (mstab currently does not support left,right) +theme.mstab_tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern") + -- defaults to the tabbar_style so only change if you want a + -- different style for mstab and tabbed + +-- the following variables are currently only for the "modern" tabbar style +theme.tabbar_color_close = "#f9929b" -- chnges the color of the close button +theme.tabbar_color_min = "#fbdf90" -- chnges the color of the minimize button +theme.tabbar_color_float = "#ccaced" -- chnges the color of the float button +``` From dd0012364eb7d03e648b16ddf137d42f1758cf42 Mon Sep 17 00:00:00 2001 From: Gokul Swami Date: Tue, 16 Feb 2021 17:25:34 -0800 Subject: [PATCH 3/7] Updated docs --- docs/signals/pctl.md | 40 ++++++++++++++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 6 deletions(-) diff --git a/docs/signals/pctl.md b/docs/signals/pctl.md index 833a6ea..b0cde19 100644 --- a/docs/signals/pctl.md +++ b/docs/signals/pctl.md @@ -23,11 +23,10 @@ Here are the signals available: ```lua -- bling::playerctl::status -- first line is the signal -- playing (boolean) -- indented lines are function parameters --- bling::playerctl::album --- album_art (string) --- bling::playerctl::title_artist +-- bling::playerctl::title_artist_album -- title (string) -- artist (string) +-- album_path (string) -- bling::playerctl::position -- interval_sec (number) -- length_sec (number) @@ -45,11 +44,40 @@ local art = wibox.widget { widget = wibox.widget.imagebox } -awesome.connect_signal("bling::playerctl::album", function(path) - art:set_image(gears.surface.load_uncached(path)) +local title_widget = wibox.widget { + markup = 'Nothing Playing', + align = 'center', + valign = 'center', + widget = wibox.widget.textbox +} + +local artist_widget = wibox.widget { + markup = 'Nothing Playing', + align = 'center', + valign = 'center', + widget = wibox.widget.textbox +} + +-- Get Song Info +awesome.connect_signal("bling::playerctl::title_artist_album", + function(title, artist, art_path) + -- Set art widget + art:set_image(gears.surface.load_uncached(art_path)) + + local my_title = "No Title" + local my_artist = "No Artist" + + if title then + my_title = title + my_artist = artist + end + + -- Set title and artist widgets + title_widget:set_markup_silently(my_title) + artist_widget:set_markup_silently(my_artist) end) ``` -Thats all! You don't even have to worry about updating the imagebox, the signals will handle that for you. +Thats all! You don't even have to worry about updating the widgets, the signals will handle that for you. ### Theme Variables ```lua From 1df54094526592eb02aeabb7a925f79b6da118bd Mon Sep 17 00:00:00 2001 From: Gokul Swami Date: Tue, 16 Feb 2021 17:59:41 -0800 Subject: [PATCH 4/7] Update docs --- docs/_sidebar.md | 2 +- docs/{README.md => home.md} | 9 ++++++++ docs/index.html | 46 +++++++++++++++++++------------------ 3 files changed, 34 insertions(+), 23 deletions(-) rename docs/{README.md => home.md} (82%) diff --git a/docs/_sidebar.md b/docs/_sidebar.md index c2d87f1..4a0615c 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,4 +1,4 @@ -- [Home](/) +- [Home](home.md) - [Layouts](layouts/layout.md) diff --git a/docs/README.md b/docs/home.md similarity index 82% rename from docs/README.md rename to docs/home.md index c90f27c..d5eed80 100644 --- a/docs/README.md +++ b/docs/home.md @@ -23,3 +23,12 @@ local beautiful = require("beautiful") beautiful.init("some_theme.lua") local bling = require("bling") ``` + +## Contributors +A special thanks to all our contributors... + + + + + +Made with [contributors-img](https://contrib.rocks). diff --git a/docs/index.html b/docs/index.html index 2c0472e..7f0cae4 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,25 +1,27 @@ - - - Document - - - - - - -
- - - - - + + + Bling Docs + + + + + + +
+ + + + + From c5392f4fbf8faf116f83edab0342878032899bef Mon Sep 17 00:00:00 2001 From: Gokul Swami Date: Tue, 16 Feb 2021 21:46:57 -0800 Subject: [PATCH 5/7] Docs update --- docs/signals/pctl.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/signals/pctl.md b/docs/signals/pctl.md index b0cde19..b06d69c 100644 --- a/docs/signals/pctl.md +++ b/docs/signals/pctl.md @@ -64,21 +64,24 @@ awesome.connect_signal("bling::playerctl::title_artist_album", -- Set art widget art:set_image(gears.surface.load_uncached(art_path)) - local my_title = "No Title" - local my_artist = "No Artist" - - if title then - my_title = title - my_artist = artist - end - -- Set title and artist widgets - title_widget:set_markup_silently(my_title) - artist_widget:set_markup_silently(my_artist) + title_widget:set_markup_silently(title) + artist_widget:set_markup_silently(artist) end) ``` Thats all! You don't even have to worry about updating the widgets, the signals will handle that for you. +Here's another example in which you get a notification with the album art, title, and artist whenever the song changes. + +```lua +local naughty = require("naughty") + +awesome.connect_signal("bling::playerctl::title_artist_album", + function(title, artist, art_path) + naughty.notify({title = title, text = artist, image = art_path}) +end) +``` + ### Theme Variables ```lua theme.playerctl_position_update_interval = 1 -- the update interval for fetching the position from playerctl From 0a5c842167905e01f1208a16047e8b70132d4052 Mon Sep 17 00:00:00 2001 From: Gokul Swami Date: Tue, 16 Feb 2021 21:59:45 -0800 Subject: [PATCH 6/7] change loc for images for docs --- docs/README.md | 256 +++++++++++++++++++++++++++++++++++++++++ docs/_sidebar.md | 16 --- docs/home.md | 34 ------ docs/index.html | 43 +++---- docs/layouts/layout.md | 44 ------- docs/module/flash.md | 27 ----- docs/module/swal.md | 21 ---- docs/module/tabbed.md | 40 ------- docs/module/twall.md | 23 ---- docs/module/wall.md | 127 -------------------- docs/signals/pctl.md | 88 -------------- docs/theme.md | 54 --------- 12 files changed, 275 insertions(+), 498 deletions(-) create mode 100644 docs/README.md delete mode 100644 docs/_sidebar.md delete mode 100644 docs/home.md delete mode 100644 docs/layouts/layout.md delete mode 100644 docs/module/flash.md delete mode 100644 docs/module/swal.md delete mode 100644 docs/module/tabbed.md delete mode 100644 docs/module/twall.md delete mode 100644 docs/module/wall.md delete mode 100644 docs/signals/pctl.md delete mode 100644 docs/theme.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..23c4e51 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,256 @@ +#
🌟 Bling - Utilities for the AwesomeWM 🌟
+ +## ❓ Why + +AwesomeWM is literally that - an awesome window manager. + +It's unique selling point has always been the widget system allowing for fancy buttons, sliders, bars, dashboards and everything you can imagine. But that feature might also be a curse. Most modules focus on the widget side of things which left the actual window managing part of awesomeWM a little underdeveloped compared to for example xmonad even though it's probably just as powerfull in that regard. + +This module is trying to fix exactly that: Adding new layouts and modules that - while making use of the widget system - don't focus on it but on new window managing features. + +## 🧭 Installation and configuration +- `git clone` this repo into your `~/.config/awesome` folder +- Put ``local bling = require("bling")`` somewhere in your ``rc.lua`` (remember to put it under ``beautiful.init...``) + +##### 📎 Layouts + +Choose layouts from the list below and add them to to your `awful.layouts` list in your `rc.lua`. + +Everyone of them supports multiple master clients and master width factor making them as easily useable as the default layouts. +```Lua +bling.layout.mstab +bling.layout.centered +bling.layout.vertical +bling.layout.horizontal +``` + +##### 😋 Window swallowing + +To activate and deactivate window swallowing there are the following functions. If you want to activate it, just call the `start` function once in your `rc.lua`. +```lua +bling.module.window_swallowing.start() -- activates window swallowing +bling.module.window_swallowing.stop() -- deactivates window swallowing +bling.module.window_swallowing.toggle() -- toggles window swallowing +``` + +##### 🏬 Tiled Wallpaper + +The function to set an automatically created tiled wallpaper can be called the follwing way (you don't need to set every option in the table of the last argument since there are reasonable defaults): +```lua +awful.screen.connect_for_each_screen(function(s) -- that way the wallpaper is applied to every screen + bling.module.tiled_wallpaper("x", s, { -- call the actual function ("x" is the string that will be tiled) + fg = "#ff0000", -- define the foreground color + bg = "#00ffff", -- define the background color + offset_y = 25, -- set a y offset + offset_x = 25, -- set a x offset + font = "Hack", -- set the font (without the size) + font_size = 14, -- set the font size + padding = 100, -- set padding (default is 100) + zickzack = true -- rectangular pattern or criss cross + }) +end) +``` + +##### 🎇 Wallpaper easy setup + +This is a simple-to-use, extensible, declarative wallpaper manager. + +###### Practical examples + +```lua +-- A default Awesome wallpaper +bling.module.wallpaper.setup() + +-- A slideshow with pictures from different sources changing every 30 minutes +bling.module.wallpaper.setup { + wallpaper = {"/images/my_dog.jpg", "/images/my_cat.jpg"}, + change_timer = 1800 +} + +-- A random wallpaper with images from multiple folders +bling.module.wallpaper.setup { + set_function = bling.module.wallpaper.setters.random + wallpaper = {"/path/to/a/folder", "/path/to/another/folder"}, + change_timer = 631, -- prime numbers are better for timers + position = "fit", + background = "#424242" +} + +-- wallpapers based on a schedule, like awesome-glorious-widgets dynamic wallpaper +-- https://github.com/manilarome/awesome-glorious-widgets/tree/master/dynamic-wallpaper +bling.module.wallpaper.setup { + set_function = wallpaper.setters.simple_schedule, + wallpaper = { + ["06:22:00"] = "morning-wallpaper.jpg", + ["12:00:00"] = "noon-wallpaper.jpg", + ["17:58:00"] = "night-wallpaper.jpg", + ["24:00:00"] = "midnight-wallpaper.jpg", + }, + position = "maximized", +} + +-- random wallpapers, from different folder depending on time of the day +bling.module.wallpaper.setup { + set_function = bling.module.wallpaper.setters.simple_schedule, + wallpaper = { + ["09:00:00"] = "~/Pictures/safe_for_work", + ["18:00:00"] = "~/Pictures/personal", + }, + schedule_set_function = bling.module.wallpaper.setters.random + position = "maximized", + recursive = false, + change_timer = 600 +} +``` +###### Details + +The setup function will do 2 things: call the set-function when awesome requests a wallpaper, and manage a timer to call `set_function` periodically. + +Its argument is a args table that is passed to ohter functions (setters and wallpaper functions), so you define everything with setup. + +The `set_function` is a function called every times a wallpaper is needed. + +The module provides some setters: + +* `bling.module.wallpaper.setters.awesome_wallpaper`: beautiful.theme_assets.wallpaper with defaults from beautiful. +* `bling.module.wallpaper.setters.simple`: slideshow from the `wallpaper` argument. +* `bling.module.wallpaper.setters.random`: same as simple but in a random way. +* `bling.module.wallpaper.setters.simple_schedule`: takes a table of `["HH:MM:SS"] = wallpaper` arguments, where wallpaper is the `wallpaper` argument used by `schedule_set_function`. + +A wallpaper is one of the following elements: + +* a color +* an image +* a folder containing images +* a function that sets a wallpaper +* everything gears.wallpaper functions can manage (cairo surface, cairo pattern string) +* a list containing any of the elements above +```lua +-- This is a valid wallpaper definition +bling.module.wallpaper.setup { + wallpaper = { -- a list + "black", "#112233", -- colors + "wall1.jpg", "wall2.png", -- files + "/path/to/wallpapers", -- folders + -- cairo patterns + "radial:600,50,100:105,550,900:0,#2200ff:0.5,#00ff00:1,#101010", + -- or functions that set a wallpaper + function(args) bling.module.tiled_wallpaper("\\o/", args.screen) end, + bling.module.wallpaper.setters.awesome_wallpaper, + }, + change_timer = 10, +} +``` +The provided setters `simple` and `random` will use 2 internal functions that you can use to write your own setter: + +* `bling.module.wallpaper.prepare_list`: return a list of wallpapers directly usable by `apply` (for now, it just explores folders) +* `bling.module.wallpaper.apply`: a wrapper for gears.wallpaper functions, using the args table of setup + +Here are the defaults: +```lua +-- Default parameters +bling.module.wallpaper.setup { + screen = nil, -- the screen to apply the wallpaper, as seen in gears.wallpaper functions + change_timer = nil, -- the timer in seconds. If set, call the set_function every change_timer seconds + set_function = nil, -- the setter function + + -- parameters used by bling.module.wallpaper.prepare_list + wallpaper = nil, -- the wallpaper object, see simple or simple_schedule documentation + image_formats = {"jpg", "jpeg", "png", "bmp"}, -- when searching in folder, consider these files only + recursive = true, -- when searching in folder, search also in subfolders + + -- parameters used by bling.module.wallpaper.apply + position = nil, -- use a function of gears.wallpaper when applicable ("centered", "fit", "maximized", "tiled") + background = beautiful.bg_normal or "black", -- see gears.wallpaper functions + ignore_aspect = false, -- see gears.wallpaper.maximized + offset = {x = 0, y = 0}, -- see gears.wallpaper functions + scale = 1, -- see gears.wallpaper.centered + + -- parameters that only apply to bling.module.wallpaper.setter.awesome (as a setter or as a wallpaper function) + colors = { -- see beautiful.theme_assets.wallpaper + bg = beautiful.bg_color, -- the actual default is this color but darkened or lightned + fg = beautiful.fg_color, + alt_fg = beautiful.fg_focus + } +} +``` + +Check documentation in [module/wallpaper.lua](module/wallpaper.lua) for more details. + + +##### 🔦 Flash Focus + +There are two ways you can use this module. You can just enable it by calling the `enable()` function: +```lua +bling.module.flash_focus.enable() +``` +This connects to the focus signal of a client, which means that the flash focus will activate however you focus the client. + +The other way is to call the function itself like this: `bling.module.flash_focus.flashfocus(someclient)`. This allows you to just activate on certain keybinds: +```lua +awful.key({modkey}, "Up", + function() + awful.client.focus.bydirection("up") + bling.module.flash_focus.flashfocus(client.focus) + end, {description = "focus up", group = "client"}) +``` + +##### 📑 Tabbing + +You should bind these functions to keys in oder to use the tabbed module effectively: +```lua +bling.module.tabbed.pick() -- picks a client with your cursor to add to the tabbing group +bling.module.tabbed.pop() -- removes the focused client from the tabbing group +bling.module.tabbed.iter() -- iterates through the currently focused tabbing group +bling.module.tabbed.pick_with_dmenu() -- picks a client with a dmenu application (defaults to rofi, other options can be set with a string parameter like "dmenu") +``` + + +### 🌈 Theme variables +You will find a list of all theme variables that are used in bling and comments on what they do in the `theme-var-template.lua` file - ready for you to copy them into your `theme.lua`. Theme variables are not only used to change the appearance of some features but also to adjust the functionality of some modules. So it is worth it to take a look at them. + +## 😲 Preview + +### Tabbing +![](https://imgur.com/08AlNhQ.png) + +screenshot by [javacafe](https://github.com/JavaCafe01) + +### Mstab (dynamic tabbing layout) +![](https://imgur.com/HZRgApE.png) + +screenshot by [javacafe](https://github.com/JavaCafe01) + +### Centered +![](https://media.discordapp.net/attachments/769673106842845194/780095998239834142/unknown.png) + +screenshot by [branwright](https://github.com/branwright1) + +### Tiled Wallpaper +![](https://media.discordapp.net/attachments/702548913999314964/773887721294135296/tiled-wallpapers.png?width=1920&height=1080) + +screenshots by me + +### Flash Focus +![](https://imgur.com/5txYrlV.gif) + +gif by [javacafe](https://github.com/JavaCafe01) + +### Wind swallowing +![](https://media.discordapp.net/attachments/635625813143978012/769180910683684864/20-10-23-14-40-32.gif) + +gif by me :) + +## TODO +- [ ] Add external sources management for the wallpaper module (URLs, RSS feeds, NASA picture of the day, ...) +- [ ] Scratchpad module +- [x] Some more documentation on the tabbed module +- [x] Add a cool alternative tabbar style +- [x] Add another cool tabbar style (we need more styles) +- [x] Make the mstab layout compatible with vertical tabbars (left and right) +- [x] Add option to mstab layout to not shrink windows down when they are in the tabbed pane and unfocused (for example for people using transparent terminals) +- [x] Keyboard based option to add windows to a tabbing object + +All naming credit goes to javacafe. + +Contributions are welcomed 💛 diff --git a/docs/_sidebar.md b/docs/_sidebar.md deleted file mode 100644 index 4a0615c..0000000 --- a/docs/_sidebar.md +++ /dev/null @@ -1,16 +0,0 @@ -- [Home](home.md) - -- [Layouts](layouts/layout.md) - -- Modules - - [Flash Focus](module/flash.md) - - [Tabbed](module/tabbed.md) - - [Tiled Wallpaper](module/twall.md) - - [Wallpaper Easy Setup](module/wall.md) - - [Window Swallowing](module/swal.md) - -- Signals - - [Playerctl](signals/pctl.md) - -- Extra - - [Theme Variable Template](theme.md) diff --git a/docs/home.md b/docs/home.md deleted file mode 100644 index d5eed80..0000000 --- a/docs/home.md +++ /dev/null @@ -1,34 +0,0 @@ -#
🌟 Bling - Utilities for AwesomeWM 🌟
- -## Why - -[AwesomeWM](https://awesomewm.org/) is literally what it stands for, an awesome window manager. - -Its unique selling point has always been the widget system, which allows for fancy buttons, sliders, bars, dashboards and anything you can imagine. But that feature can be a curse. Most modules focus on the widget side of things which leave the actual window managing part of AwesomeWM underdeveloped compared to, for example, [xmonad](https://xmonad.org/) even though it's probably just as powerfull in that area. - -This project focuses on that problem - adding new layouts and modules that make use of the widget system, but primarily focus on the new window managing features. - -## Installation -- clone this repo into your `~/.config/awesome` folder - - `git clone https://github.com/Nooo37/bling.git ~/.config/awesome/bling` -- require the module in your `rc.lua`, and make sure it's under the beautiful module initialization - -```lua --- other imports - -local beautiful = require("beautiful") - --- other configuration stuff here - -beautiful.init("some_theme.lua") -local bling = require("bling") -``` - -## Contributors -A special thanks to all our contributors... - - - - - -Made with [contributors-img](https://contrib.rocks). diff --git a/docs/index.html b/docs/index.html index 7f0cae4..04dd4a7 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,27 +1,22 @@ - - - Bling Docs - - - - - - -
- - - - - + + + Document + + + + + + +
+ + + + diff --git a/docs/layouts/layout.md b/docs/layouts/layout.md deleted file mode 100644 index 97c8ab6..0000000 --- a/docs/layouts/layout.md +++ /dev/null @@ -1,44 +0,0 @@ -## 📎 Layouts - -Choose layouts from the list below and add them to to your `awful.layouts` list in your `rc.lua`. - -Everyone of them supports multiple master clients and master width factor making them easy to use. - -The mstab layout uses the tab theme from the tabbed module. - -```Lua -bling.layout.mstab -bling.layout.centered -bling.layout.vertical -bling.layout.horizontal -``` - -### Theme Variables -```lua --- mstab -theme.mstab_bar_ontop = false -- whether you want to allow the bar to be ontop of clients -theme.mstab_dont_resize_slaves = false -- whether the tabbed stack windows should be smaller than the - -- currently focused stack window (set it to true if you use - -- transparent terminals. False if you use shadows on solid ones -theme.mstab_bar_padding = "default" -- how much padding there should be between clients and your tabbar - -- by default it will adjust based on your useless gaps. - -- If you want a custom value. Set it to the number of pixels (int) -theme.mstab_border_radius = 0 -- border radius of the tabbar -theme.mstab_bar_height = 40 -- height of the tabbar -theme.mstab_tabbar_position = "top" -- position of the tabbar (mstab currently does not support left,right) -theme.mstab_tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern") - -- defaults to the tabbar_style so only change if you want a - -- different style for mstab and tabbed -``` - -### Previews - -#### Mstab (dynamic tabbing layout) -![](https://imgur.com/HZRgApE.png) - -*screenshot by [javacafe](https://github.com/JavaCafe01)* - -#### Centered -![](https://media.discordapp.net/attachments/769673106842845194/780095998239834142/unknown.png) - -*screenshot by [branwright](https://github.com/branwright1)* diff --git a/docs/module/flash.md b/docs/module/flash.md deleted file mode 100644 index da80d4b..0000000 --- a/docs/module/flash.md +++ /dev/null @@ -1,27 +0,0 @@ -## 🔦 Flash Focus - -Flash focus does an opacity animation effect on a client when it is focused. -![](https://imgur.com/5txYrlV.gif) -*gif by [JavaCafe01](https://github.com/JavaCafe01)* - -### Usage - -There are two ways in which you can use this module. You can enable it by calling the `enable()` function: -```lua -bling.module.flash_focus.enable() -``` -This connects to the focus signal of a client, which means that the flash focus will activate however you focus the client. - -The other way is to call the function itself like this: `bling.module.flash_focus.flashfocus(someclient)`. This allows you to activate on certain keybinds like so: -```lua -awful.key({modkey}, "Up", - function() - awful.client.focus.bydirection("up") - bling.module.flash_focus.flashfocus(client.focus) - end, {description = "focus up", group = "client"}) -``` -### Theme Variables -```lua -theme.flash_focus_start_opacity = 0.6 -- the starting opacity -theme.flash_focus_step = 0.01 -- the step of animation -``` diff --git a/docs/module/swal.md b/docs/module/swal.md deleted file mode 100644 index 3b06a6f..0000000 --- a/docs/module/swal.md +++ /dev/null @@ -1,21 +0,0 @@ -## 😋 Window Swallowing - -Can your window manager swallow? It probably can... -![](https://media.discordapp.net/attachments/635625813143978012/769180910683684864/20-10-23-14-40-32.gif) - -*gif by [Nooo37](https://github.com/Nooo37)* - -### Usage - -To activate and deactivate window swallowing here are the following functions. If you want to activate it, just call the `start` function once in your `rc.lua`. -```lua -bling.module.window_swallowing.start() -- activates window swallowing -bling.module.window_swallowing.stop() -- deactivates window swallowing -bling.module.window_swallowing.toggle() -- toggles window swallowing -``` - -### Theme Variables -```lua -theme.dont_swallow_classname_list = {"firefox", "Gimp"} -- list of class names that should not be swallowed -theme.dont_swallow_filter_activated = true -- whether the filter above should be active -``` diff --git a/docs/module/tabbed.md b/docs/module/tabbed.md deleted file mode 100644 index a5d8166..0000000 --- a/docs/module/tabbed.md +++ /dev/null @@ -1,40 +0,0 @@ -## 📑 Tabbed - -Tabbed implements a tab container. There are also different themes for the tabs. This is the modern theme: -![](https://imgur.com/omowmIQ.png) - -*screenshot by [javacafe](https://github.com/JavaCafe01)* - -### Usage - -You should bind these functions to keys in order to use the tabbed module effectively: -```lua -bling.module.tabbed.pick() -- picks a client with your cursor to add to the tabbing group -bling.module.tabbed.pop() -- removes the focused client from the tabbing group -bling.module.tabbed.iter() -- iterates through the currently focused tabbing group -bling.module.tabbed.pick_with_dmenu() -- picks a client with a dmenu application (defaults to rofi, other options can be set with a string parameter like "dmenu") -``` - -### Theme Variables - -```lua --- For tabbed only -theme.tabbed_spawn_in_tab = false -- whether a new client should spawn into the focused tabbing container - --- For tabbar in general -theme.tabbar_ontop = false -theme.tabbar_radius = 0 -- border radius of the tabbar -theme.tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern") -theme.tabbar_font = "Sans 11" -- font of the tabbar -theme.tabbar_size = 40 -- size of the tabbar -theme.tabbar_position = "top" -- position of the tabbar -theme.tabbar_bg_normal = "#000000" -- background color of the focused client on the tabbar -theme.tabbar_fg_normal = "#ffffff" -- foreground color of the focused client on the tabbar -theme.tabbar_bg_focus = "#1A2026" -- background color of unfocused clients on the tabbar -theme.tabbar_fg_focus = "#ff0000" -- foreground color of unfocused clients on the tabbar - --- the following variables are currently only for the "modern" tabbar style -theme.tabbar_color_close = "#f9929b" -- chnges the color of the close button -theme.tabbar_color_min = "#fbdf90" -- chnges the color of the minimize button -theme.tabbar_color_float = "#ccaced" -- chnges the color of the float button -``` diff --git a/docs/module/twall.md b/docs/module/twall.md deleted file mode 100644 index eedcc6d..0000000 --- a/docs/module/twall.md +++ /dev/null @@ -1,23 +0,0 @@ -## 🏬 Tiled Wallpaper - -![](https://media.discordapp.net/attachments/702548913999314964/773887721294135296/tiled-wallpapers.png?width=1920&height=1080) - -*screenshots by [Nooo37](https://github.com/Nooo37)* - -### Usage - -The function to set an automatically created tiled wallpaper can be called the following way (you don't need to set every option in the table): -```lua -awful.screen.connect_for_each_screen(function(s) -- that way the wallpaper is applied to every screen - bling.module.tiled_wallpaper("x", s, { -- call the actual function ("x" is the string that will be tiled) - fg = "#ff0000", -- define the foreground color - bg = "#00ffff", -- define the background color - offset_y = 25, -- set a y offset - offset_x = 25, -- set a x offset - font = "Hack", -- set the font (without the size) - font_size = 14, -- set the font size - padding = 100, -- set padding (default is 100) - zickzack = true -- rectangular pattern or criss cross - }) -end) -``` diff --git a/docs/module/wall.md b/docs/module/wall.md deleted file mode 100644 index 12a5e4d..0000000 --- a/docs/module/wall.md +++ /dev/null @@ -1,127 +0,0 @@ -## 🎇 Wallpaper Easy Setup - -This is a simple-to-use, extensible, declarative wallpaper manager. - -### Practical Examples - -```lua --- A default Awesome wallpaper -bling.module.wallpaper.setup() - --- A slideshow with pictures from different sources changing every 30 minutes -bling.module.wallpaper.setup { - wallpaper = {"/images/my_dog.jpg", "/images/my_cat.jpg"}, - change_timer = 1800 -} - --- A random wallpaper with images from multiple folders -bling.module.wallpaper.setup { - set_function = bling.module.wallpaper.setters.random - wallpaper = {"/path/to/a/folder", "/path/to/another/folder"}, - change_timer = 631, -- prime numbers are better for timers - position = "fit", - background = "#424242" -} - --- wallpapers based on a schedule, like awesome-glorious-widgets dynamic wallpaper --- https://github.com/manilarome/awesome-glorious-widgets/tree/master/dynamic-wallpaper -bling.module.wallpaper.setup { - set_function = wallpaper.setters.simple_schedule, - wallpaper = { - ["06:22:00"] = "morning-wallpaper.jpg", - ["12:00:00"] = "noon-wallpaper.jpg", - ["17:58:00"] = "night-wallpaper.jpg", - ["24:00:00"] = "midnight-wallpaper.jpg", - }, - position = "maximized", -} - --- random wallpapers, from different folder depending on time of the day -bling.module.wallpaper.setup { - set_function = bling.module.wallpaper.setters.simple_schedule, - wallpaper = { - ["09:00:00"] = "~/Pictures/safe_for_work", - ["18:00:00"] = "~/Pictures/personal", - }, - schedule_set_function = bling.module.wallpaper.setters.random - position = "maximized", - recursive = false, - change_timer = 600 -} -``` -### Details - -The setup function will do 2 things: call the set-function when awesome requests a wallpaper, and manage a timer to call `set_function` periodically. - -Its argument is a args table that is passed to ohter functions (setters and wallpaper functions), so you define everything with setup. - -The `set_function` is a function called every times a wallpaper is needed. - -The module provides some setters: - -* `bling.module.wallpaper.setters.awesome_wallpaper`: beautiful.theme_assets.wallpaper with defaults from beautiful. -* `bling.module.wallpaper.setters.simple`: slideshow from the `wallpaper` argument. -* `bling.module.wallpaper.setters.random`: same as simple but in a random way. -* `bling.module.wallpaper.setters.simple_schedule`: takes a table of `["HH:MM:SS"] = wallpaper` arguments, where wallpaper is the `wallpaper` argument used by `schedule_set_function`. - -A wallpaper is one of the following elements: - -* a color -* an image -* a folder containing images -* a function that sets a wallpaper -* everything gears.wallpaper functions can manage (cairo surface, cairo pattern string) -* a list containing any of the elements above - -```lua --- This is a valid wallpaper definition -bling.module.wallpaper.setup { - wallpaper = { -- a list - "black", "#112233", -- colors - "wall1.jpg", "wall2.png", -- files - "/path/to/wallpapers", -- folders - -- cairo patterns - "radial:600,50,100:105,550,900:0,#2200ff:0.5,#00ff00:1,#101010", - -- or functions that set a wallpaper - function(args) bling.module.tiled_wallpaper("\\o/", args.screen) end, - bling.module.wallpaper.setters.awesome_wallpaper, - }, - change_timer = 10, -} -``` -The provided setters `simple` and `random` will use 2 internal functions that you can use to write your own setter: - -* `bling.module.wallpaper.prepare_list`: return a list of wallpapers directly usable by `apply` (for now, it just explores folders) -* `bling.module.wallpaper.apply`: a wrapper for gears.wallpaper functions, using the args table of setup - -Here are the defaults: - -```lua --- Default parameters -bling.module.wallpaper.setup { - screen = nil, -- the screen to apply the wallpaper, as seen in gears.wallpaper functions - change_timer = nil, -- the timer in seconds. If set, call the set_function every change_timer seconds - set_function = nil, -- the setter function - - -- parameters used by bling.module.wallpaper.prepare_list - wallpaper = nil, -- the wallpaper object, see simple or simple_schedule documentation - image_formats = {"jpg", "jpeg", "png", "bmp"}, -- when searching in folder, consider these files only - recursive = true, -- when searching in folder, search also in subfolders - - -- parameters used by bling.module.wallpaper.apply - position = nil, -- use a function of gears.wallpaper when applicable ("centered", "fit", "maximized", "tiled") - background = beautiful.bg_normal or "black", -- see gears.wallpaper functions - ignore_aspect = false, -- see gears.wallpaper.maximized - offset = {x = 0, y = 0}, -- see gears.wallpaper functions - scale = 1, -- see gears.wallpaper.centered - - -- parameters that only apply to bling.module.wallpaper.setter.awesome (as a setter or as a wallpaper function) - colors = { -- see beautiful.theme_assets.wallpaper - bg = beautiful.bg_color, -- the actual default is this color but darkened or lightned - fg = beautiful.fg_color, - alt_fg = beautiful.fg_focus - } -} -``` - -Check documentation in [module/wallpaper.lua](module/wallpaper.lua) for more details. diff --git a/docs/signals/pctl.md b/docs/signals/pctl.md deleted file mode 100644 index b06d69c..0000000 --- a/docs/signals/pctl.md +++ /dev/null @@ -1,88 +0,0 @@ -## 🎵 Playerctl - -This is a signal module in which you can connect to certain bling signals to grab playerctl info. Currently, this is what it supports: - -- Song title and artist -- Album art (the path this module downloaded the art to) -- If playing or not -- Position -- Song length - -This module relies on `playerctl` and `curl`. If you have this module disabled, you won't need those programs. With this module, you can create a widget like below without worrying about the backend. - -![](https://user-images.githubusercontent.com/33443763/107377569-fa807900-6a9f-11eb-93c1-174c58eb7bf1.png) - -*screenshot by [javacafe](https://github.com/JavaCafe01)* - -### Usage - -To enable: `bling.signal.playerctl.enable()` - -Here are the signals available: - -```lua --- bling::playerctl::status -- first line is the signal --- playing (boolean) -- indented lines are function parameters --- bling::playerctl::title_artist_album --- title (string) --- artist (string) --- album_path (string) --- bling::playerctl::position --- interval_sec (number) --- length_sec (number) -``` - -### 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: -```lua -local art = wibox.widget { - image = "default_image.png", - resize = true, - forced_height = dpi(80), - forced_width = dpi(80), - widget = wibox.widget.imagebox -} - -local title_widget = wibox.widget { - markup = 'Nothing Playing', - align = 'center', - valign = 'center', - widget = wibox.widget.textbox -} - -local artist_widget = wibox.widget { - markup = 'Nothing Playing', - align = 'center', - valign = 'center', - widget = wibox.widget.textbox -} - --- Get Song Info -awesome.connect_signal("bling::playerctl::title_artist_album", - function(title, artist, art_path) - -- Set art widget - art:set_image(gears.surface.load_uncached(art_path)) - - -- Set title and artist widgets - title_widget:set_markup_silently(title) - artist_widget:set_markup_silently(artist) -end) -``` -Thats all! You don't even have to worry about updating the widgets, the signals will handle that for you. - -Here's another example in which you get a notification with the album art, title, and artist whenever the song changes. - -```lua -local naughty = require("naughty") - -awesome.connect_signal("bling::playerctl::title_artist_album", - function(title, artist, art_path) - naughty.notify({title = title, text = artist, image = art_path}) -end) -``` - -### Theme Variables -```lua -theme.playerctl_position_update_interval = 1 -- the update interval for fetching the position from playerctl -``` diff --git a/docs/theme.md b/docs/theme.md deleted file mode 100644 index 5814a2e..0000000 --- a/docs/theme.md +++ /dev/null @@ -1,54 +0,0 @@ -```lua ---[[ Bling theme variables template -This file has all theme variables of the bling module. -Every variable has a small comment on what it does. -You might just want to copy that whole part into your theme.lua and start adjusting from there. ---]] - - --- window swallowing -theme.dont_swallow_classname_list = {"firefox", "Gimp"} -- list of class names that should not be swallowed -theme.dont_swallow_filter_activated = true -- whether the filter above should be active - --- flash focus -theme.flash_focus_start_opacity = 0.6 -- the starting opacity -theme.flash_focus_step = 0.01 -- the step of animation - --- playerctl signal -theme.playerctl_position_update_interval = 1 -- the update interval for fetching the position from playerctl - --- tabbed -theme.tabbed_spawn_in_tab = false -- whether a new client should spawn into the focused tabbing container - --- tabbar general -theme.tabbar_ontop = false -theme.tabbar_radius = 0 -- border radius of the tabbar -theme.tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern") -theme.tabbar_font = "Sans 11" -- font of the tabbar -theme.tabbar_size = 40 -- size of the tabbar -theme.tabbar_position = "top" -- position of the tabbar -theme.tabbar_bg_normal = "#000000" -- background color of the focused client on the tabbar -theme.tabbar_fg_normal = "#ffffff" -- foreground color of the focused client on the tabbar -theme.tabbar_bg_focus = "#1A2026" -- background color of unfocused clients on the tabbar -theme.tabbar_fg_focus = "#ff0000" -- foreground color of unfocused clients on the tabbar - --- mstab -theme.mstab_bar_ontop = false -- whether you want to allow the bar to be ontop of clients -theme.mstab_dont_resize_slaves = false -- whether the tabbed stack windows should be smaller than the - -- currently focused stack window (set it to true if you use - -- transparent terminals. False if you use shadows on solid ones -theme.mstab_bar_padding = "default" -- how much padding there should be between clients and your tabbar - -- by default it will adjust based on your useless gaps. - -- If you want a custom value. Set it to the number of pixels (int) -theme.mstab_border_radius = 0 -- border radius of the tabbar -theme.mstab_bar_height = 40 -- height of the tabbar -theme.mstab_tabbar_position = "top" -- position of the tabbar (mstab currently does not support left,right) -theme.mstab_tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern") - -- defaults to the tabbar_style so only change if you want a - -- different style for mstab and tabbed - --- the following variables are currently only for the "modern" tabbar style -theme.tabbar_color_close = "#f9929b" -- chnges the color of the close button -theme.tabbar_color_min = "#fbdf90" -- chnges the color of the minimize button -theme.tabbar_color_float = "#ccaced" -- chnges the color of the float button -``` From e1a5657b42f8a1160220827a98dcee18a64e3d4d Mon Sep 17 00:00:00 2001 From: Gokul Swami Date: Tue, 16 Feb 2021 22:01:29 -0800 Subject: [PATCH 7/7] i messed up my prev commit --- docs/README.md | 256 ----------------------------------------- docs/_sidebar.md | 16 +++ docs/home.md | 34 ++++++ docs/index.html | 43 ++++--- docs/layouts/layout.md | 44 +++++++ docs/module/flash.md | 33 ++++++ docs/module/swal.md | 24 ++++ docs/module/tabbed.md | 45 ++++++++ docs/module/twall.md | 25 ++++ docs/module/wall.md | 127 ++++++++++++++++++++ docs/signals/pctl.md | 88 ++++++++++++++ docs/theme.md | 54 +++++++++ 12 files changed, 514 insertions(+), 275 deletions(-) delete mode 100644 docs/README.md create mode 100644 docs/_sidebar.md create mode 100644 docs/home.md create mode 100644 docs/layouts/layout.md create mode 100644 docs/module/flash.md create mode 100644 docs/module/swal.md create mode 100644 docs/module/tabbed.md create mode 100644 docs/module/twall.md create mode 100644 docs/module/wall.md create mode 100644 docs/signals/pctl.md create mode 100644 docs/theme.md diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 23c4e51..0000000 --- a/docs/README.md +++ /dev/null @@ -1,256 +0,0 @@ -#
🌟 Bling - Utilities for the AwesomeWM 🌟
- -## ❓ Why - -AwesomeWM is literally that - an awesome window manager. - -It's unique selling point has always been the widget system allowing for fancy buttons, sliders, bars, dashboards and everything you can imagine. But that feature might also be a curse. Most modules focus on the widget side of things which left the actual window managing part of awesomeWM a little underdeveloped compared to for example xmonad even though it's probably just as powerfull in that regard. - -This module is trying to fix exactly that: Adding new layouts and modules that - while making use of the widget system - don't focus on it but on new window managing features. - -## 🧭 Installation and configuration -- `git clone` this repo into your `~/.config/awesome` folder -- Put ``local bling = require("bling")`` somewhere in your ``rc.lua`` (remember to put it under ``beautiful.init...``) - -##### 📎 Layouts - -Choose layouts from the list below and add them to to your `awful.layouts` list in your `rc.lua`. - -Everyone of them supports multiple master clients and master width factor making them as easily useable as the default layouts. -```Lua -bling.layout.mstab -bling.layout.centered -bling.layout.vertical -bling.layout.horizontal -``` - -##### 😋 Window swallowing - -To activate and deactivate window swallowing there are the following functions. If you want to activate it, just call the `start` function once in your `rc.lua`. -```lua -bling.module.window_swallowing.start() -- activates window swallowing -bling.module.window_swallowing.stop() -- deactivates window swallowing -bling.module.window_swallowing.toggle() -- toggles window swallowing -``` - -##### 🏬 Tiled Wallpaper - -The function to set an automatically created tiled wallpaper can be called the follwing way (you don't need to set every option in the table of the last argument since there are reasonable defaults): -```lua -awful.screen.connect_for_each_screen(function(s) -- that way the wallpaper is applied to every screen - bling.module.tiled_wallpaper("x", s, { -- call the actual function ("x" is the string that will be tiled) - fg = "#ff0000", -- define the foreground color - bg = "#00ffff", -- define the background color - offset_y = 25, -- set a y offset - offset_x = 25, -- set a x offset - font = "Hack", -- set the font (without the size) - font_size = 14, -- set the font size - padding = 100, -- set padding (default is 100) - zickzack = true -- rectangular pattern or criss cross - }) -end) -``` - -##### 🎇 Wallpaper easy setup - -This is a simple-to-use, extensible, declarative wallpaper manager. - -###### Practical examples - -```lua --- A default Awesome wallpaper -bling.module.wallpaper.setup() - --- A slideshow with pictures from different sources changing every 30 minutes -bling.module.wallpaper.setup { - wallpaper = {"/images/my_dog.jpg", "/images/my_cat.jpg"}, - change_timer = 1800 -} - --- A random wallpaper with images from multiple folders -bling.module.wallpaper.setup { - set_function = bling.module.wallpaper.setters.random - wallpaper = {"/path/to/a/folder", "/path/to/another/folder"}, - change_timer = 631, -- prime numbers are better for timers - position = "fit", - background = "#424242" -} - --- wallpapers based on a schedule, like awesome-glorious-widgets dynamic wallpaper --- https://github.com/manilarome/awesome-glorious-widgets/tree/master/dynamic-wallpaper -bling.module.wallpaper.setup { - set_function = wallpaper.setters.simple_schedule, - wallpaper = { - ["06:22:00"] = "morning-wallpaper.jpg", - ["12:00:00"] = "noon-wallpaper.jpg", - ["17:58:00"] = "night-wallpaper.jpg", - ["24:00:00"] = "midnight-wallpaper.jpg", - }, - position = "maximized", -} - --- random wallpapers, from different folder depending on time of the day -bling.module.wallpaper.setup { - set_function = bling.module.wallpaper.setters.simple_schedule, - wallpaper = { - ["09:00:00"] = "~/Pictures/safe_for_work", - ["18:00:00"] = "~/Pictures/personal", - }, - schedule_set_function = bling.module.wallpaper.setters.random - position = "maximized", - recursive = false, - change_timer = 600 -} -``` -###### Details - -The setup function will do 2 things: call the set-function when awesome requests a wallpaper, and manage a timer to call `set_function` periodically. - -Its argument is a args table that is passed to ohter functions (setters and wallpaper functions), so you define everything with setup. - -The `set_function` is a function called every times a wallpaper is needed. - -The module provides some setters: - -* `bling.module.wallpaper.setters.awesome_wallpaper`: beautiful.theme_assets.wallpaper with defaults from beautiful. -* `bling.module.wallpaper.setters.simple`: slideshow from the `wallpaper` argument. -* `bling.module.wallpaper.setters.random`: same as simple but in a random way. -* `bling.module.wallpaper.setters.simple_schedule`: takes a table of `["HH:MM:SS"] = wallpaper` arguments, where wallpaper is the `wallpaper` argument used by `schedule_set_function`. - -A wallpaper is one of the following elements: - -* a color -* an image -* a folder containing images -* a function that sets a wallpaper -* everything gears.wallpaper functions can manage (cairo surface, cairo pattern string) -* a list containing any of the elements above -```lua --- This is a valid wallpaper definition -bling.module.wallpaper.setup { - wallpaper = { -- a list - "black", "#112233", -- colors - "wall1.jpg", "wall2.png", -- files - "/path/to/wallpapers", -- folders - -- cairo patterns - "radial:600,50,100:105,550,900:0,#2200ff:0.5,#00ff00:1,#101010", - -- or functions that set a wallpaper - function(args) bling.module.tiled_wallpaper("\\o/", args.screen) end, - bling.module.wallpaper.setters.awesome_wallpaper, - }, - change_timer = 10, -} -``` -The provided setters `simple` and `random` will use 2 internal functions that you can use to write your own setter: - -* `bling.module.wallpaper.prepare_list`: return a list of wallpapers directly usable by `apply` (for now, it just explores folders) -* `bling.module.wallpaper.apply`: a wrapper for gears.wallpaper functions, using the args table of setup - -Here are the defaults: -```lua --- Default parameters -bling.module.wallpaper.setup { - screen = nil, -- the screen to apply the wallpaper, as seen in gears.wallpaper functions - change_timer = nil, -- the timer in seconds. If set, call the set_function every change_timer seconds - set_function = nil, -- the setter function - - -- parameters used by bling.module.wallpaper.prepare_list - wallpaper = nil, -- the wallpaper object, see simple or simple_schedule documentation - image_formats = {"jpg", "jpeg", "png", "bmp"}, -- when searching in folder, consider these files only - recursive = true, -- when searching in folder, search also in subfolders - - -- parameters used by bling.module.wallpaper.apply - position = nil, -- use a function of gears.wallpaper when applicable ("centered", "fit", "maximized", "tiled") - background = beautiful.bg_normal or "black", -- see gears.wallpaper functions - ignore_aspect = false, -- see gears.wallpaper.maximized - offset = {x = 0, y = 0}, -- see gears.wallpaper functions - scale = 1, -- see gears.wallpaper.centered - - -- parameters that only apply to bling.module.wallpaper.setter.awesome (as a setter or as a wallpaper function) - colors = { -- see beautiful.theme_assets.wallpaper - bg = beautiful.bg_color, -- the actual default is this color but darkened or lightned - fg = beautiful.fg_color, - alt_fg = beautiful.fg_focus - } -} -``` - -Check documentation in [module/wallpaper.lua](module/wallpaper.lua) for more details. - - -##### 🔦 Flash Focus - -There are two ways you can use this module. You can just enable it by calling the `enable()` function: -```lua -bling.module.flash_focus.enable() -``` -This connects to the focus signal of a client, which means that the flash focus will activate however you focus the client. - -The other way is to call the function itself like this: `bling.module.flash_focus.flashfocus(someclient)`. This allows you to just activate on certain keybinds: -```lua -awful.key({modkey}, "Up", - function() - awful.client.focus.bydirection("up") - bling.module.flash_focus.flashfocus(client.focus) - end, {description = "focus up", group = "client"}) -``` - -##### 📑 Tabbing - -You should bind these functions to keys in oder to use the tabbed module effectively: -```lua -bling.module.tabbed.pick() -- picks a client with your cursor to add to the tabbing group -bling.module.tabbed.pop() -- removes the focused client from the tabbing group -bling.module.tabbed.iter() -- iterates through the currently focused tabbing group -bling.module.tabbed.pick_with_dmenu() -- picks a client with a dmenu application (defaults to rofi, other options can be set with a string parameter like "dmenu") -``` - - -### 🌈 Theme variables -You will find a list of all theme variables that are used in bling and comments on what they do in the `theme-var-template.lua` file - ready for you to copy them into your `theme.lua`. Theme variables are not only used to change the appearance of some features but also to adjust the functionality of some modules. So it is worth it to take a look at them. - -## 😲 Preview - -### Tabbing -![](https://imgur.com/08AlNhQ.png) - -screenshot by [javacafe](https://github.com/JavaCafe01) - -### Mstab (dynamic tabbing layout) -![](https://imgur.com/HZRgApE.png) - -screenshot by [javacafe](https://github.com/JavaCafe01) - -### Centered -![](https://media.discordapp.net/attachments/769673106842845194/780095998239834142/unknown.png) - -screenshot by [branwright](https://github.com/branwright1) - -### Tiled Wallpaper -![](https://media.discordapp.net/attachments/702548913999314964/773887721294135296/tiled-wallpapers.png?width=1920&height=1080) - -screenshots by me - -### Flash Focus -![](https://imgur.com/5txYrlV.gif) - -gif by [javacafe](https://github.com/JavaCafe01) - -### Wind swallowing -![](https://media.discordapp.net/attachments/635625813143978012/769180910683684864/20-10-23-14-40-32.gif) - -gif by me :) - -## TODO -- [ ] Add external sources management for the wallpaper module (URLs, RSS feeds, NASA picture of the day, ...) -- [ ] Scratchpad module -- [x] Some more documentation on the tabbed module -- [x] Add a cool alternative tabbar style -- [x] Add another cool tabbar style (we need more styles) -- [x] Make the mstab layout compatible with vertical tabbars (left and right) -- [x] Add option to mstab layout to not shrink windows down when they are in the tabbed pane and unfocused (for example for people using transparent terminals) -- [x] Keyboard based option to add windows to a tabbing object - -All naming credit goes to javacafe. - -Contributions are welcomed 💛 diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 0000000..4a0615c --- /dev/null +++ b/docs/_sidebar.md @@ -0,0 +1,16 @@ +- [Home](home.md) + +- [Layouts](layouts/layout.md) + +- Modules + - [Flash Focus](module/flash.md) + - [Tabbed](module/tabbed.md) + - [Tiled Wallpaper](module/twall.md) + - [Wallpaper Easy Setup](module/wall.md) + - [Window Swallowing](module/swal.md) + +- Signals + - [Playerctl](signals/pctl.md) + +- Extra + - [Theme Variable Template](theme.md) diff --git a/docs/home.md b/docs/home.md new file mode 100644 index 0000000..d5eed80 --- /dev/null +++ b/docs/home.md @@ -0,0 +1,34 @@ +#
🌟 Bling - Utilities for AwesomeWM 🌟
+ +## Why + +[AwesomeWM](https://awesomewm.org/) is literally what it stands for, an awesome window manager. + +Its unique selling point has always been the widget system, which allows for fancy buttons, sliders, bars, dashboards and anything you can imagine. But that feature can be a curse. Most modules focus on the widget side of things which leave the actual window managing part of AwesomeWM underdeveloped compared to, for example, [xmonad](https://xmonad.org/) even though it's probably just as powerfull in that area. + +This project focuses on that problem - adding new layouts and modules that make use of the widget system, but primarily focus on the new window managing features. + +## Installation +- clone this repo into your `~/.config/awesome` folder + - `git clone https://github.com/Nooo37/bling.git ~/.config/awesome/bling` +- require the module in your `rc.lua`, and make sure it's under the beautiful module initialization + +```lua +-- other imports + +local beautiful = require("beautiful") + +-- other configuration stuff here + +beautiful.init("some_theme.lua") +local bling = require("bling") +``` + +## Contributors +A special thanks to all our contributors... + + + + + +Made with [contributors-img](https://contrib.rocks). diff --git a/docs/index.html b/docs/index.html index 04dd4a7..7f0cae4 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,22 +1,27 @@ - - - Document - - - - - - -
- - - - + + + Bling Docs + + + + + + +
+ + + + + diff --git a/docs/layouts/layout.md b/docs/layouts/layout.md new file mode 100644 index 0000000..97c8ab6 --- /dev/null +++ b/docs/layouts/layout.md @@ -0,0 +1,44 @@ +## 📎 Layouts + +Choose layouts from the list below and add them to to your `awful.layouts` list in your `rc.lua`. + +Everyone of them supports multiple master clients and master width factor making them easy to use. + +The mstab layout uses the tab theme from the tabbed module. + +```Lua +bling.layout.mstab +bling.layout.centered +bling.layout.vertical +bling.layout.horizontal +``` + +### Theme Variables +```lua +-- mstab +theme.mstab_bar_ontop = false -- whether you want to allow the bar to be ontop of clients +theme.mstab_dont_resize_slaves = false -- whether the tabbed stack windows should be smaller than the + -- currently focused stack window (set it to true if you use + -- transparent terminals. False if you use shadows on solid ones +theme.mstab_bar_padding = "default" -- how much padding there should be between clients and your tabbar + -- by default it will adjust based on your useless gaps. + -- If you want a custom value. Set it to the number of pixels (int) +theme.mstab_border_radius = 0 -- border radius of the tabbar +theme.mstab_bar_height = 40 -- height of the tabbar +theme.mstab_tabbar_position = "top" -- position of the tabbar (mstab currently does not support left,right) +theme.mstab_tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern") + -- defaults to the tabbar_style so only change if you want a + -- different style for mstab and tabbed +``` + +### Previews + +#### Mstab (dynamic tabbing layout) +![](https://imgur.com/HZRgApE.png) + +*screenshot by [javacafe](https://github.com/JavaCafe01)* + +#### Centered +![](https://media.discordapp.net/attachments/769673106842845194/780095998239834142/unknown.png) + +*screenshot by [branwright](https://github.com/branwright1)* diff --git a/docs/module/flash.md b/docs/module/flash.md new file mode 100644 index 0000000..ed4fa42 --- /dev/null +++ b/docs/module/flash.md @@ -0,0 +1,33 @@ +## 🔦 Flash Focus + +Flash focus does an opacity animation effect on a client when it is focused. + + +### Usage + +There are two ways in which you can use this module. You can enable it by calling the `enable()` function: +```lua +bling.module.flash_focus.enable() +``` +This connects to the focus signal of a client, which means that the flash focus will activate however you focus the client. + +The other way is to call the function itself like this: `bling.module.flash_focus.flashfocus(someclient)`. This allows you to activate on certain keybinds like so: +```lua +awful.key({modkey}, "Up", + function() + awful.client.focus.bydirection("up") + bling.module.flash_focus.flashfocus(client.focus) + end, {description = "focus up", group = "client"}) +``` + +### Theme Variables +```lua +theme.flash_focus_start_opacity = 0.6 -- the starting opacity +theme.flash_focus_step = 0.01 -- the step of animation +``` + +### Preview + +![](https://imgur.com/5txYrlV.gif) + +*gif by [JavaCafe01](https://github.com/JavaCafe01)* diff --git a/docs/module/swal.md b/docs/module/swal.md new file mode 100644 index 0000000..ad40c0f --- /dev/null +++ b/docs/module/swal.md @@ -0,0 +1,24 @@ +## 😋 Window Swallowing + +Can your window manager swallow? It probably can... + +### Usage + +To activate and deactivate window swallowing here are the following functions. If you want to activate it, just call the `start` function once in your `rc.lua`. +```lua +bling.module.window_swallowing.start() -- activates window swallowing +bling.module.window_swallowing.stop() -- deactivates window swallowing +bling.module.window_swallowing.toggle() -- toggles window swallowing +``` + +### Theme Variables +```lua +theme.dont_swallow_classname_list = {"firefox", "Gimp"} -- list of class names that should not be swallowed +theme.dont_swallow_filter_activated = true -- whether the filter above should be active +``` + +### Preview + +![](https://media.discordapp.net/attachments/635625813143978012/769180910683684864/20-10-23-14-40-32.gif) + +*gif by [Nooo37](https://github.com/Nooo37)* diff --git a/docs/module/tabbed.md b/docs/module/tabbed.md new file mode 100644 index 0000000..1c82253 --- /dev/null +++ b/docs/module/tabbed.md @@ -0,0 +1,45 @@ +## 📑 Tabbed + +Tabbed implements a tab container. There are also different themes for the tabs. + +### Usage + +You should bind these functions to keys in order to use the tabbed module effectively: +```lua +bling.module.tabbed.pick() -- picks a client with your cursor to add to the tabbing group +bling.module.tabbed.pop() -- removes the focused client from the tabbing group +bling.module.tabbed.iter() -- iterates through the currently focused tabbing group +bling.module.tabbed.pick_with_dmenu() -- picks a client with a dmenu application (defaults to rofi, other options can be set with a string parameter like "dmenu") +``` + +### Theme Variables + +```lua +-- For tabbed only +theme.tabbed_spawn_in_tab = false -- whether a new client should spawn into the focused tabbing container + +-- For tabbar in general +theme.tabbar_ontop = false +theme.tabbar_radius = 0 -- border radius of the tabbar +theme.tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern") +theme.tabbar_font = "Sans 11" -- font of the tabbar +theme.tabbar_size = 40 -- size of the tabbar +theme.tabbar_position = "top" -- position of the tabbar +theme.tabbar_bg_normal = "#000000" -- background color of the focused client on the tabbar +theme.tabbar_fg_normal = "#ffffff" -- foreground color of the focused client on the tabbar +theme.tabbar_bg_focus = "#1A2026" -- background color of unfocused clients on the tabbar +theme.tabbar_fg_focus = "#ff0000" -- foreground color of unfocused clients on the tabbar + +-- the following variables are currently only for the "modern" tabbar style +theme.tabbar_color_close = "#f9929b" -- chnges the color of the close button +theme.tabbar_color_min = "#fbdf90" -- chnges the color of the minimize button +theme.tabbar_color_float = "#ccaced" -- chnges the color of the float button +``` + +### Preview + +Modern theme: + + + +*screenshot by [javacafe](https://github.com/JavaCafe01)* diff --git a/docs/module/twall.md b/docs/module/twall.md new file mode 100644 index 0000000..73ef4a3 --- /dev/null +++ b/docs/module/twall.md @@ -0,0 +1,25 @@ +## 🏬 Tiled Wallpaper + +### Usage + +The function to set an automatically created tiled wallpaper can be called the following way (you don't need to set every option in the table): +```lua +awful.screen.connect_for_each_screen(function(s) -- that way the wallpaper is applied to every screen + bling.module.tiled_wallpaper("x", s, { -- call the actual function ("x" is the string that will be tiled) + fg = "#ff0000", -- define the foreground color + bg = "#00ffff", -- define the background color + offset_y = 25, -- set a y offset + offset_x = 25, -- set a x offset + font = "Hack", -- set the font (without the size) + font_size = 14, -- set the font size + padding = 100, -- set padding (default is 100) + zickzack = true -- rectangular pattern or criss cross + }) +end) +``` + +### Preview + +![](https://media.discordapp.net/attachments/702548913999314964/773887721294135296/tiled-wallpapers.png?width=1920&height=1080) + +*screenshots by [Nooo37](https://github.com/Nooo37)* diff --git a/docs/module/wall.md b/docs/module/wall.md new file mode 100644 index 0000000..12a5e4d --- /dev/null +++ b/docs/module/wall.md @@ -0,0 +1,127 @@ +## 🎇 Wallpaper Easy Setup + +This is a simple-to-use, extensible, declarative wallpaper manager. + +### Practical Examples + +```lua +-- A default Awesome wallpaper +bling.module.wallpaper.setup() + +-- A slideshow with pictures from different sources changing every 30 minutes +bling.module.wallpaper.setup { + wallpaper = {"/images/my_dog.jpg", "/images/my_cat.jpg"}, + change_timer = 1800 +} + +-- A random wallpaper with images from multiple folders +bling.module.wallpaper.setup { + set_function = bling.module.wallpaper.setters.random + wallpaper = {"/path/to/a/folder", "/path/to/another/folder"}, + change_timer = 631, -- prime numbers are better for timers + position = "fit", + background = "#424242" +} + +-- wallpapers based on a schedule, like awesome-glorious-widgets dynamic wallpaper +-- https://github.com/manilarome/awesome-glorious-widgets/tree/master/dynamic-wallpaper +bling.module.wallpaper.setup { + set_function = wallpaper.setters.simple_schedule, + wallpaper = { + ["06:22:00"] = "morning-wallpaper.jpg", + ["12:00:00"] = "noon-wallpaper.jpg", + ["17:58:00"] = "night-wallpaper.jpg", + ["24:00:00"] = "midnight-wallpaper.jpg", + }, + position = "maximized", +} + +-- random wallpapers, from different folder depending on time of the day +bling.module.wallpaper.setup { + set_function = bling.module.wallpaper.setters.simple_schedule, + wallpaper = { + ["09:00:00"] = "~/Pictures/safe_for_work", + ["18:00:00"] = "~/Pictures/personal", + }, + schedule_set_function = bling.module.wallpaper.setters.random + position = "maximized", + recursive = false, + change_timer = 600 +} +``` +### Details + +The setup function will do 2 things: call the set-function when awesome requests a wallpaper, and manage a timer to call `set_function` periodically. + +Its argument is a args table that is passed to ohter functions (setters and wallpaper functions), so you define everything with setup. + +The `set_function` is a function called every times a wallpaper is needed. + +The module provides some setters: + +* `bling.module.wallpaper.setters.awesome_wallpaper`: beautiful.theme_assets.wallpaper with defaults from beautiful. +* `bling.module.wallpaper.setters.simple`: slideshow from the `wallpaper` argument. +* `bling.module.wallpaper.setters.random`: same as simple but in a random way. +* `bling.module.wallpaper.setters.simple_schedule`: takes a table of `["HH:MM:SS"] = wallpaper` arguments, where wallpaper is the `wallpaper` argument used by `schedule_set_function`. + +A wallpaper is one of the following elements: + +* a color +* an image +* a folder containing images +* a function that sets a wallpaper +* everything gears.wallpaper functions can manage (cairo surface, cairo pattern string) +* a list containing any of the elements above + +```lua +-- This is a valid wallpaper definition +bling.module.wallpaper.setup { + wallpaper = { -- a list + "black", "#112233", -- colors + "wall1.jpg", "wall2.png", -- files + "/path/to/wallpapers", -- folders + -- cairo patterns + "radial:600,50,100:105,550,900:0,#2200ff:0.5,#00ff00:1,#101010", + -- or functions that set a wallpaper + function(args) bling.module.tiled_wallpaper("\\o/", args.screen) end, + bling.module.wallpaper.setters.awesome_wallpaper, + }, + change_timer = 10, +} +``` +The provided setters `simple` and `random` will use 2 internal functions that you can use to write your own setter: + +* `bling.module.wallpaper.prepare_list`: return a list of wallpapers directly usable by `apply` (for now, it just explores folders) +* `bling.module.wallpaper.apply`: a wrapper for gears.wallpaper functions, using the args table of setup + +Here are the defaults: + +```lua +-- Default parameters +bling.module.wallpaper.setup { + screen = nil, -- the screen to apply the wallpaper, as seen in gears.wallpaper functions + change_timer = nil, -- the timer in seconds. If set, call the set_function every change_timer seconds + set_function = nil, -- the setter function + + -- parameters used by bling.module.wallpaper.prepare_list + wallpaper = nil, -- the wallpaper object, see simple or simple_schedule documentation + image_formats = {"jpg", "jpeg", "png", "bmp"}, -- when searching in folder, consider these files only + recursive = true, -- when searching in folder, search also in subfolders + + -- parameters used by bling.module.wallpaper.apply + position = nil, -- use a function of gears.wallpaper when applicable ("centered", "fit", "maximized", "tiled") + background = beautiful.bg_normal or "black", -- see gears.wallpaper functions + ignore_aspect = false, -- see gears.wallpaper.maximized + offset = {x = 0, y = 0}, -- see gears.wallpaper functions + scale = 1, -- see gears.wallpaper.centered + + -- parameters that only apply to bling.module.wallpaper.setter.awesome (as a setter or as a wallpaper function) + colors = { -- see beautiful.theme_assets.wallpaper + bg = beautiful.bg_color, -- the actual default is this color but darkened or lightned + fg = beautiful.fg_color, + alt_fg = beautiful.fg_focus + } +} +``` + +Check documentation in [module/wallpaper.lua](module/wallpaper.lua) for more details. diff --git a/docs/signals/pctl.md b/docs/signals/pctl.md new file mode 100644 index 0000000..b06d69c --- /dev/null +++ b/docs/signals/pctl.md @@ -0,0 +1,88 @@ +## 🎵 Playerctl + +This is a signal module in which you can connect to certain bling signals to grab playerctl info. Currently, this is what it supports: + +- Song title and artist +- Album art (the path this module downloaded the art to) +- If playing or not +- Position +- Song length + +This module relies on `playerctl` and `curl`. If you have this module disabled, you won't need those programs. With this module, you can create a widget like below without worrying about the backend. + +![](https://user-images.githubusercontent.com/33443763/107377569-fa807900-6a9f-11eb-93c1-174c58eb7bf1.png) + +*screenshot by [javacafe](https://github.com/JavaCafe01)* + +### Usage + +To enable: `bling.signal.playerctl.enable()` + +Here are the signals available: + +```lua +-- bling::playerctl::status -- first line is the signal +-- playing (boolean) -- indented lines are function parameters +-- bling::playerctl::title_artist_album +-- title (string) +-- artist (string) +-- album_path (string) +-- bling::playerctl::position +-- interval_sec (number) +-- length_sec (number) +``` + +### 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: +```lua +local art = wibox.widget { + image = "default_image.png", + resize = true, + forced_height = dpi(80), + forced_width = dpi(80), + widget = wibox.widget.imagebox +} + +local title_widget = wibox.widget { + markup = 'Nothing Playing', + align = 'center', + valign = 'center', + widget = wibox.widget.textbox +} + +local artist_widget = wibox.widget { + markup = 'Nothing Playing', + align = 'center', + valign = 'center', + widget = wibox.widget.textbox +} + +-- Get Song Info +awesome.connect_signal("bling::playerctl::title_artist_album", + function(title, artist, art_path) + -- Set art widget + art:set_image(gears.surface.load_uncached(art_path)) + + -- Set title and artist widgets + title_widget:set_markup_silently(title) + artist_widget:set_markup_silently(artist) +end) +``` +Thats all! You don't even have to worry about updating the widgets, the signals will handle that for you. + +Here's another example in which you get a notification with the album art, title, and artist whenever the song changes. + +```lua +local naughty = require("naughty") + +awesome.connect_signal("bling::playerctl::title_artist_album", + function(title, artist, art_path) + naughty.notify({title = title, text = artist, image = art_path}) +end) +``` + +### Theme Variables +```lua +theme.playerctl_position_update_interval = 1 -- the update interval for fetching the position from playerctl +``` diff --git a/docs/theme.md b/docs/theme.md new file mode 100644 index 0000000..5814a2e --- /dev/null +++ b/docs/theme.md @@ -0,0 +1,54 @@ +```lua +--[[ Bling theme variables template +This file has all theme variables of the bling module. +Every variable has a small comment on what it does. +You might just want to copy that whole part into your theme.lua and start adjusting from there. +--]] + + +-- window swallowing +theme.dont_swallow_classname_list = {"firefox", "Gimp"} -- list of class names that should not be swallowed +theme.dont_swallow_filter_activated = true -- whether the filter above should be active + +-- flash focus +theme.flash_focus_start_opacity = 0.6 -- the starting opacity +theme.flash_focus_step = 0.01 -- the step of animation + +-- playerctl signal +theme.playerctl_position_update_interval = 1 -- the update interval for fetching the position from playerctl + +-- tabbed +theme.tabbed_spawn_in_tab = false -- whether a new client should spawn into the focused tabbing container + +-- tabbar general +theme.tabbar_ontop = false +theme.tabbar_radius = 0 -- border radius of the tabbar +theme.tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern") +theme.tabbar_font = "Sans 11" -- font of the tabbar +theme.tabbar_size = 40 -- size of the tabbar +theme.tabbar_position = "top" -- position of the tabbar +theme.tabbar_bg_normal = "#000000" -- background color of the focused client on the tabbar +theme.tabbar_fg_normal = "#ffffff" -- foreground color of the focused client on the tabbar +theme.tabbar_bg_focus = "#1A2026" -- background color of unfocused clients on the tabbar +theme.tabbar_fg_focus = "#ff0000" -- foreground color of unfocused clients on the tabbar + +-- mstab +theme.mstab_bar_ontop = false -- whether you want to allow the bar to be ontop of clients +theme.mstab_dont_resize_slaves = false -- whether the tabbed stack windows should be smaller than the + -- currently focused stack window (set it to true if you use + -- transparent terminals. False if you use shadows on solid ones +theme.mstab_bar_padding = "default" -- how much padding there should be between clients and your tabbar + -- by default it will adjust based on your useless gaps. + -- If you want a custom value. Set it to the number of pixels (int) +theme.mstab_border_radius = 0 -- border radius of the tabbar +theme.mstab_bar_height = 40 -- height of the tabbar +theme.mstab_tabbar_position = "top" -- position of the tabbar (mstab currently does not support left,right) +theme.mstab_tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern") + -- defaults to the tabbar_style so only change if you want a + -- different style for mstab and tabbed + +-- the following variables are currently only for the "modern" tabbar style +theme.tabbar_color_close = "#f9929b" -- chnges the color of the close button +theme.tabbar_color_min = "#fbdf90" -- chnges the color of the minimize button +theme.tabbar_color_float = "#ccaced" -- chnges the color of the float button +```