Merge pull request #21 from Nooo37/docs

Docs
This commit is contained in:
gokul swaminathan 2021-02-16 23:39:17 -08:00 committed by GitHub
commit 8338c0100c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 517 additions and 0 deletions

0
docs/.nojekyll Normal file
View File

16
docs/_sidebar.md Normal file
View File

@ -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)

34
docs/home.md Normal file
View File

@ -0,0 +1,34 @@
# <center> 🌟 Bling - Utilities for AwesomeWM 🌟 </center>
## 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...
<a href="https://github.com/Nooo37/bling/graphs/contributors">
<img src="https://contrib.rocks/image?repo=Nooo37/bling" />
</a>
Made with [contributors-img](https://contrib.rocks).

27
docs/index.html Normal file
View File

@ -0,0 +1,27 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Bling Docs</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="Description">
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
name: 'bling',
nameLink: '/',
repo: 'https://github.com/Nooo37/bling',
loadSidebar: true,
subMaxLevel: 3,
homepage: 'home.md'
}
</script>
<!-- Docsify v4 -->
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
<script src="//unpkg.com/prismjs/components/prism-lua.js"></script>
</body>
</html>

44
docs/layouts/layout.md Normal file
View File

@ -0,0 +1,44 @@
## 📎 Layouts <!-- {docsify-ignore} -->
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)*

33
docs/module/flash.md Normal file
View File

@ -0,0 +1,33 @@
## 🔦 Flash Focus <!-- {docsify-ignore} -->
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)*

24
docs/module/swal.md Normal file
View File

@ -0,0 +1,24 @@
## 😋 Window Swallowing <!-- {docsify-ignore} -->
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)*

45
docs/module/tabbed.md Normal file
View File

@ -0,0 +1,45 @@
## 📑 Tabbed <!-- {docsify-ignore} -->
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:
<img src="https://imgur.com/omowmIQ.png" width="600"/>
*screenshot by [javacafe](https://github.com/JavaCafe01)*

25
docs/module/twall.md Normal file
View File

@ -0,0 +1,25 @@
## 🏬 Tiled Wallpaper <!-- {docsify-ignore} -->
### 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)*

127
docs/module/wall.md Normal file
View File

@ -0,0 +1,127 @@
## 🎇 Wallpaper Easy Setup <!-- {docsify-ignore} -->
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.

88
docs/signals/pctl.md Normal file
View File

@ -0,0 +1,88 @@
## 🎵 Playerctl <!-- {docsify-ignore} -->
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
```

54
docs/theme.md Normal file
View File

@ -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
```