Table of Contents generated with DocToc
- [awesome Window Manager configuration](#awesome-window-managerawesome-configuration)
awesome Window Manager configuration
Please use the branch that matches your Awesome version:
awesome is awesome. I use it on all Arch Linux desktop/laptop machines that I have control over (admittedly, it is not designed for handheld smartphones/tablets).
Me using it to demo Figurehead.
Search YouTube for "awesome wm" to see awesome in action.
Among my favorites features:
- keyboard driven workflow (again, see this in action on YouTube).
- customizable through the Lua programming language.
- one-key-combo switching between tiling and stacking window management styles.
- the ability to do dynamic tagging (meaning it is not enabled by the default configuration---at least up to v3.5.4 (Brown Paper Bag) released on 2 April 2014).
This repo holds my personal take of awesome's configuration. Hightlights:
- persistent dynamic tagging across (both regular and randr-induced) restarts.
- dynamic tagging means tags can be created/moved/renamed/deleted on the fly without touching the configuration.
- persistent means tags and the clients/programs associated with each tag is preserved across awesome restart.
- this is the feature I have desired for that is lacking in current default configuration.
- Emacs-inspired universal argument: Specify a numeric argument for, e.g., repetition or precise resizing. Idea/prototype credit: @AnthonyAaronHughWong in #3.
- confirmation before quit/restart to minimize data loss accidents.
- you have to type "yes" (case insensitive) before quitting/restarting.
- this minimizes the chance that you lose your work by accidents.
- keybindings for tuning transparency (using
picom), stay-on-top, sticky.- these features combined, along with tiling and floating layouts, allow you to type in one window while seeing the content of others.
- keybindings to my preferred applications.
- only cycle through the most sensible (IMHO) layouts.
- keybinding optimized for Arch Linux over Thinkpad W530 (my current workhorse).
- Install awesome with your preferred package manager. Example:
sudo pacman -S awesome --needed --noconfirmon Arch Linux. - Clone this repo to
$HOME/.config/awesome.
cd $HOME/.config && git clone https://github.com/pw4ever/awesome-wm-config.git awesome- Setup .xinitrc or Display Manager accordingly.
These dependencies are mostly derived from the application keybindings. Some are needed to enable basic features like theming (feh), Desktop Entry Specification-style autostart (dex), audio setup (alsa-utils), backlight (xorg-xbacklight), Webcam (cheese), music player (mpd and mpc), screen lock (xfce4-screensaver), network management (network-manager-applet), terminal (kitty), task manager (xfce4-taskmanager), and screen setup (arandr), etc..
Although not strictly dependencies, some of the packages are, in my opinion, nice to have.
On Arch Linux:
sudo pacman -S --needed --noconfirm feh dex xdg-utils screenfetch scrot picom wmname gnome-keyring seahorse
sudo pacman -S --needed --noconfirm xorg-xbacklight xf86-input-synaptics cheese workrave
sudo pacman -S --needed --noconfirm alsa-utils pulseaudio pulseaudio-alsa pulseaudio-alsa pulseaudio-bluetooth pavucontrol pulsemixer
sudo pacman -S --needed --noconfirm networkmanager network-manager-applet arandr
sudo pacman -S --needed --noconfirm pcmanfm gvfs udiskie xarchiver mc ranger
sudo pacman -S --needed --noconfirm kitty tmux polkit
sudo pacman -S --needed --noconfirm gvim neovim neovim-qt python-neovim emacs firefox chromium putty remmina goldendict
sudo pacman -S --needed --noconfirm fcitx-im fcitx-googlepinyin fcitx-configtool
sudo pacman -S --needed --noconfirm jdk-openjdk openjdk-doc
sudo pacman -S --needed --noconfirm nmap openssh aria2 wget the_silver_searcher
sudo pacman -S --needed --noconfirm ttf-bitstream-vera ttf-croscore ttf-dejavu ttf-droid ttf-roboto noto-fonts ttf-liberation ttf-ubuntu-font-family
sudo pacman -S --needed --noconfirm ttf-anonymous-pro ttf-freefont adobe-source-code-pro-fonts ttf-linux-libertine adobe-source-sans-pro-fonts
sudo pacman -S --needed --noconfirm adobe-source-han-sans-otc-fonts adobe-source-han-serif-otc-fonts
sudo pacman -S --needed --noconfirm xclip xsel clipmenu
sudo pacman -S --needed --noconfirm xfce4 xfce4-goodies
sudo pacman -S --needed --noconfirm mpd mpc ncmpcpp xfmpc
sudo aura -Ax --needed --noconfirm google-chrome
sudo aura -Ax --needed --noconfirm rstudio-desktop-bin
sudo aura -Ax --needed --noconfirm stardict-oald stardict-wordnet dict-wn dict-foldoc- populate your
$HOME/.config/autostartwith Desktop Entry Specification-style autostart files (optionally withOnlyShowIn=awesomeif you only want them to auto-start in awesome). - my autostart setup can be found here.
Take a look at the "rc.lua" configuration file ($HOME/.config/awesome/rc.lua; perhaps by pressing the keybinding Modkeyc which will open rc.lua with the primary editor---for me, Vim).
Most keybindings are prefixed with the Modkey. This config associates Modkey to X Window's Mod4. On many machines, this associates the Super_L (tip: use xmodmap in terminal emulator to verify/change this), which usually translate to the (intuitively) Windows key.
Some keybinding requires further input (e.g., rename a tag), which will grab the key focus from your application. The Esc key is used to cancel partial input.
Universal Argument (UniArg), inspired by the namesake Emacs feature, supplies a positive numeric argument to the following command. Depending on the context, it may supply a number of repetitions (search for uniarg:key_repeat in rc.lua) or a numeric argument (search for uniarg:key_numarg in rc.lua) such as percentage of volume adjustment or pixels to resize the client window. For example, with the UniArg being 3, "open terminal" operation (ModkeyEnter by default) will open 3 terminals.
Universal argument is activated when inputing a great-than-1 integer, and is deactivated when inputing a less-than-2 integer or a non-number. When universal argument is deactivated, the default behavior kicks in, which follows some heuristics to do sensible things such as the "extend client by 1/7 of the margin" and "shrink client by 1/11 of client width and leave client width at least 50 pixels" behavior for client window side expansion/shrinking documented below.
There are two modes of universal argument: Regular and persistent. Regular universal argument only applies to the next operation, while persistent universal argument applies to all following operations until changed or deactivated.
| key combo | function | comment |
|---|---|---|
| Modkeyu | prompt for universal argument | see above paragraphs for details |
| ModkeyShiftu | prompt for persistent universal argument | see above paragraphs for details |
| key combo | function | comment |
|---|---|---|
| ModkeyCtrlr | restart | "r" for restart; used for apply updated "rc.lua" config file |
| ModkeyCtrlShiftr | restart | "r" for restart; restart without confirming with user |
| ModkeyShiftq | quit | "q" for quit; exit the current Awesome session |
| ModkeyShiftCtrlq | forcibly quit | "q" for quit; quit without confirming with user |
| Modkey\ | system info popup | |
| ModkeyCtrl\ | clear all pending notifications | |
| ModkeyAlt\ | toggle between suspending/resuming notifications | |
| Modkeyf1 | open help in browser | |
| CtrlShiftEsc | open task manager | xfce4-taskmanager |
| key combo | function | comment |
|---|---|---|
| ModkeySpace | change to next layout | |
| ModkeyShiftSpace | change to prev layout |
| mouse action | function |
|---|---|
| left button | change to next layout |
| right button | change to prev layout |
| scroll up | change to prev layout |
| scroll down | change to next layout |
only the following layouts are enabled
| layout | comment |
|---|---|
| floating | allow window stacking; the default |
| tile | tiling with master on the left |
| fair | fair allocation of screen space |
| fullscreen | the focused client fullscreened |
| magnifier | the focused client centered but not fullscreened |
in the floating mode, the following mouse actions on client window are enabled
| mouse action | function |
|---|---|
| Modkeyleft button | move client |
| Modkeyright button | resize client |
| key combo | function | comment |
|---|---|---|
| ModkeyCtrlj | focus on the next screen | "j" is easy to reach |
| ModkeyCtrlk | focus on the prev screen | "k" is easy to reach |
| Modkeyo | send client to next screen by index | |
| ModkeyShifto | send client to previous screen by index | |
| ModkeyCtrlAltShiftRight | send tag to next right screen | |
| ModkeyCtrlAltShiftLeft | send tag to next left screen | |
| ModkeyCtrlAltShiftUp | send tag to next up screen | |
| ModkeyCtrlAltShiftDown | send tag to next down screen | |
| ModkeyCtrlo | send tag to next screen | |
| ModkeyCtrlShifto | send tag to prev screen | |
| ModkeyCtrlShift\ | select next display arrangement | https://awesomewm.org/recipes/xrandr/ |
| ModkeyCtrlAlt\ | XRandR config popup | https://github.com/k3rni/foggy |
| key combo | function | comment |
|---|---|---|
| Modkeyf2 | prompt a program to launch | inherited from awesome defaults |
| Modkeyr | prompt a program to launch | "r" for run |
| Modkeyf3 | toggle touchpad | depend on synclient from xf86-input-synaptics |
| Modkeyf4 | prompt Lua code to be eval-ed in awesome | inherited from awesome defaults |
| Modkeyc | edit "rc.lua" with the primary editor | "c" for configuration file |
| ModkeyShift/ | show main menu | |
| Modkeyx | show main menu | MSFT Windows key |
| ModkeyX | show main menu | MSFT Windows key |
| Modkey; | toggle task action menu | |
| ModkeyShift; | toggle tag action menu | |
| Modkey' | choose from clients on current tag | |
| ModkeyCtrl' | prompt to choose from clients on current tag | |
| ModkeyShift' | choose from all clients | |
| ModkeyShiftCtrl' | prompt to choose from all clients | |
| Modkey` | lock screen with screensaver | |
| ModkeyEnter | launch user terminal | |
| ModkeyAltEnter | attach/launch terminal multiplexer |
| key combo | function | comment |
|---|---|---|
| ModkeyCtrlAltt | toggle tag persistence | tags persist across exit/restart by default |
| key combo | function | comment |
|---|---|---|
| Modkeya | create a new tag after the current one and view it | "a" for add |
| ModkeyShifta | create a new tag before the current one and view it | "a" for add |
| ModkeyShiftd | delte the current tag if there is no client on it | "d" for delete |
| ModkeyShiftr | rename the current tag | "r" for rename |
| key combo | function | comment |
|---|---|---|
| Modkeyp | view previous tag | "p" for previous |
| Modkeyn | view next tag | "n" for next |
| Modkeyz | view last tag | |
| Modkeyg | prompted for a tag to view | with tag name completion with Tab |
| Modkey+[1-9,0] | view the first-ninth, tenth tag | prompt for "add a new tag" if not already existed |
| ModkeyCtrl+[1-9,0] | view also the first-ninth, tenth tag | prompt for "add a new tag" if not already existed |
| key combo | function | comment |
|---|---|---|
| ModkeyCtrlp | move the current tag backward by 1 position | |
| ModkeyCtrln | move the current tag forward by 1 position |
| key combo | function | comment |
|---|---|---|
| ModkeyShiftc | kill focused client | |
| Altf4 | kill focused client | MSFT Windows key |
| Modkeyf | toggle fullscreen status | hides statusbar |
| Modkeym | toggle maximized status | leaves statusbar visible |
| ModkeyLeft | move window to left half screen | leaves statusbar visible |
| ModkeyRight | move window to right half screen | leaves statusbar visible |
| ModkeyUp | move window to top half screen | leaves statusbar visible |
| ModkeyDown | move window to bottom half screen | leaves statusbar visible |
| ModkeyAltLeft | extend client to the left | by 1/7 of the margin |
| ModkeyAltRight | extend client to the right | by 1/7 of the margin |
| ModkeyAltUp | extend client to the top | by 1/7 of the margin |
| ModkeyAltDown | extend client to the bottom | by 1/7 of the margin |
| ModkeyAltShiftLeft | shrink client from right | by 1/11 of client width; leave client width at least 50 pixels |
| ModkeyAltShiftRight | shrink client from left | by 1/11 of client width; leave client width at least 50 pixels |
| ModkeyAltShiftUp | shrink client from bottom | by 1/11 of client height; leave client height at least 50 pixels |
| ModkeyAltShiftDown | shrink client from top | by 1/11 of client height; leave client height at least 50 pixels |
| ModkeyShiftm | minimize | minimized client need mouse click on tasklist to restore |
| ModkeyCtrlSpace | toggle floating status | |
| Modkeyt | toggle ontop status | |
| Modkeys | toggle sticky status | |
| Modkey, | toggle horizontal maximized status | |
| Modkey. | toggle vertical maximized status | |
| Modkey[ | decrease opacity by 10% | need composite manager |
| Modkey] | increase opacity by 10% | need composite manager |
| ModkeyShift[ | disable composite manager | |
| ModkeyShift] | enable composite manager |
| key combo | function | comment |
|---|---|---|
| Modkeyj | focus on the next client in current tag | "j" is easy to reach |
| ModkeyTab | focus on the next client in current tag | MSFT Windows key |
| Modkeyk | focus on the prev client in current tag | "k" is easy to reach |
| ModkeyShiftTab | focus on the prev client in current tag | MSFT Windows key |
| Modkeyy | jump to the urgent client | "y" next to "u" (taken by universal argument) for urgent |
| key combo | function | comment |
|---|---|---|
| ModkeyCtrlEnter | select current client as the master | master is featured on the screen |
| ModkeyShiftj | swap current client with the next one | "j" is easy to reach |
| ModkeyShiftk | swap current client with the prev one | "k" is easy to reach |
all these keys work on the single currently focused client
| key combo | function | comment |
|---|---|---|
| ModkeyShiftp | send the client to the previous tag | "p" for previous |
| ModkeyShiftn | send the client to the next tag | "n" for next |
| ModkeyShiftg | move the client to the named tag | with tag name completion by Tab |
| ModkeyCtrlShiftg | toggle the named tag for the client | with tag name completion by Tab |
| ModkeyShift1-9,0 | move the client to {first-ninth, tenth} tag | prompt for "add a new tag" if not already existed |
| ModkeyCtrlShift1-9,0 | toggle the {first-ninth, tenth} tag for the client | prompt for "add a new tag" if not already existed |
| key combo | function | comment |
|---|---|---|
| Modkey= | reset master width to 50% | "=" for equal partition of screen |
| Modkeyl | increase master width by 5% | "l" towards right on keyboard |
| Modkeyh | decrease master width by 5% | "h" towards left on keyboard |
| ModkeyShiftl | increase number of masters by 1 | "l" towards right on keyboard |
| ModkeyShifth | decrease number of masters by 1 | "h" towards left on keyboard |
| ModkeyCtrll | increase number of columns by 1 | "l" towards right on keyboard |
| ModkeyCtrlh | decrease number of columns by 1 | "h" towards left on keyboard |
| key combo | function | comment |
|---|---|---|
| ModkeyShift` | toggle the visibility of current client's titlebar |
shortcut keys are bound for most common apps; the keybinding is designed to be balanced between the left (pressing the Modkey) and the right hand (an additional easy to reach key).
| key combo | app | my choice |
|---|---|---|
| Modkey` | screen saver/locker | xfce4-screensaver |
| ModkeyCtrl` | display power off | xset dpms force off |
| ModkeyHome | screen saver/locker | xfce4-screensaver |
| ModkeyEnd | suspend | systemctl suspend |
| ModkeyAltHome | hibernate (will confirm) | systemctl hibernate |
| ModkeyAltEnd | hybrid sleep (will confirm) | systemctl hybrid-sleep |
| ModkeyInsert | reboot (will confirm) | systemctl reboot |
| ModkeyDelete | power off (will confirm) | systemctl poweroff |
| Modkey/ | GUI appfinder | xfce4-appfinder |
| key combo | app | my choice |
|---|---|---|
| ModkeyAltl | primary file manager | ranger |
| ModkeyAltShiftl | secondary file manager | pcmanfm |
| Modkeye | primary file manager | ranger; MSFT Windows key |
| ModkeyShifte | secondary file manager | pcmanfm |
| ModkeyEnter | terminal | kitty |
| ModkeyAltEnter | terminal multiplexer | tmux |
| ModkeyAltp | remote terminal | putty |
| ModkeyAltr | remote terminal | remmina |
| Modkeyi | primary editor | gvim |
| ModkeyShifti | secondary editor | emacs |
| Modkeyb | primary browser | chromium |
| ModkeyCtrlb | private primary browser | chromium --incognito |
| ModkeyShiftb | secondary browser | firefox |
| ModkeyShiftCtrlb | private secondary browser | firefox --private |
| Modkeyv | clipboard manager | clipmenu |
| ModkeyAltv | hypervisor | virtualbox |
| ModkeyAltm | MPD client | ncmpcpp |
| ModkeyShift\ | screen magnifier | kmag |
| PrtSc | screen shooter | xfce4-screenshooter |
| ModkeyPrtSc | screen recorder | teiler |
| ModkeyAltPrtSc | Xrandr app | arandr |
- currently optimized for Thinkpad W530 keyboard layout
- take a look at the config for details.
| mouse action | function |
|---|---|
| left button | view the tag |
| Modkeyleft button | move current client to the tag |
| middle button | toggle whether to view the tag |
| Modkeymiddle button | toggle the tag for current client |
| right button | show tag action menu |
| Modkeyright button | delete the tag if empty |
| scroll up | view the prev tag |
| scroll down | view the next tag |
| mouse action | function |
|---|---|
| left button | toggle task minimize status |
| middle button | choose from clients on current tag |
| Modkeymiddle button | choose from all clients |
| right button | show task action menu |
| scroll up | focus on prev task |
| scroll down | focus on next task |
| mouse action | function |
|---|---|
| left button | choose from all clients |
| middle button | show tag action menu |
| right button | show main menu |
| scroll up | view the prev tag |
| scroll down | view the next tag |
| mouse action | function |
|---|---|
| left button | move the window |
| right button | resize the window |
the five buttons on the upper right corner
| button (fromt left to right) | function |
|---|---|
| 1 | toggle floating status |
| 2 | toggle maximized status |
| 3 | toggle sticky/show-in-all-tags status |
| 4 | toggle always-on-top status |
| 5 | close window |
The items can be changed with awesome-client. Example:
customization.option.wallpaper_change_p=true -- enable random wallpaper choosing
customization.timer.change_wallpaper.timeout=7.5 -- choose a wallpaper every 7.5 seconds| value | type | meaning | default value |
|---|---|---|---|
customization.option.wallpaper_change_p |
boolean | random wallpaper choosing enabled? | true |
customization.option.launch_compmgr_p |
boolean | launch composite manager on startup? | false |
customization.timer.change_wallpaper.timeout |
number | randomly choose a wallpaper from the "wallpaper" directory after every this number of seconds | 15 |
customization.option.tag_persistent_p |
boolean | tag persistent across restart? false for clean slate |
true |
customization.option.low_battery_notification_p |
boolean | warn about low battery condition | true |
customization.widgets.bat.warning_threshold |
number | low battery notification threshold in percentage | 10 |
customization.widgets.bat.instance |
string | battery under monitor for low battery notification | "BAT0" |
- improve persistent dynamic tagging: preserve tag configuration (e.g., layout style and client positions)