awesome window manager config with persistent dynamic tagging
Lua Shell
Wei Peng
Latest commit 06b6357 Mar 29, 2018

README.md

Table of Contents generated with DocToc

awesome Window Manager configuration

Please use the branch that matches your Awesome version:

a screenshot of it in action

intro

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:

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 xcompmgr), 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).

setup

install on Linux

  • Install awesome with your preferred package manager. Example: sudo pacman -S awesome --needed --noconfirm on 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.

dependencies

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 (xscreensaver), network management (network-manager-applet), terminal (sakura), task manager (lxtask), and screen setup (arandr), etc..

On Arch Linux:

sudo pacman -S --needed --noconfirm feh dex xdg-utils screenfetch scrot xcompmgr kdeaccessibility wmname
sudo pacman -S --needed --noconfirm alsa-utils pavucontrol xorg-xbacklight xf86-input-synaptics cheese mpd mpc workrave
sudo pacman -S --needed --noconfirm xscreensaver networkmanager network-manager-applet mate-power-manager arandr xfce4-appfinder xfce4-screenshooter gnome-control-center lxtask
sudo pacman -S --needed --noconfirm pcmanfm gvfs udiskie lxsession lxappearance xarchiver
sudo pacman -S --needed --noconfirm sakura terminator conky gksu launchy
sudo pacman -S --needed --noconfirm gvim emacs firefox chromium putty remmina synergy
sudo pacman -S --needed --noconfirm fcitx-im fcitx-googlepinyin fcitx-configtool

miscellaneous

usage

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

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

window management

restart/quit/info

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
Modkeyf1 open help in browser
CtrlShiftEsc open task manager lxtask

layout

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

multiple screens/multi-head/RANDR

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 the other 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

misc

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 launch root terminal

persistent dynamic tagging

tag persistence

key combo function comment
ModkeyCtrlAltt toggle tag persistence tags persist across exit/restart by default

add/delete/rename

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

view

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

move

key combo function comment
ModkeyCtrlp move the current tag backward by 1 position
ModkeyCtrln move the current tag forward by 1 position

client management

operation

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, e.g., xcompmgr
Modkey] increase opacity by 10% need composite manager, e.g., xcompmgr
ModkeyShift[ disable composite manager
ModkeyShift] enable composite manager

change focus

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

swap order/select master

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

move/copy to tag

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

change space allocation in tile layout

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

misc

key combo function comment
ModkeyShift` toggle the visibility of current client's titlebar

app bindings

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

admin

key combo app my choice
ModkeyAltEnter root terminal gksudo sakura
Modkey` screen saver/locker xscreensaver
ModkeyHome screen saver/locker xscreensaver
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

everyday

key combo app my choice
ModkeyAltl file manager pcmanfm
Modkeye file manager pcmanfm; MSFT Windows key
ModkeyE file manager pcmanfm; MSFT Windows key
ModkeyEnter user terminal sakura
ModkeyAltp remote terminal putty
ModkeyAltr remote terminal remmina
Modkeyi primary editor gvim
ModkeyShifti secondary editor emacs
Modkeyb primary browser chromium
ModkeyShiftb secondary browser firefox
ModkeyAltv secondary browser virtualbox
ModkeyShift\ screen magnifier kmag
PrtSc screen shooter xfce4-screenshooter

the rest

tag list

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

task list

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

root window/"the desktop"

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

window/task/client title bar

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

customization

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.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"

todo

  • improve persistent dynamic tagging: preserve tag configuration (e.g., layout style and client positions)