README.md

Table of Contents generated with DocToc

• [awesome Window Manager configuration](#awesome-window-managerawesome-configuration)
  • intro
  • setup
    • install on Linux
    • dependencies and nice-to-haves
    • miscellaneous
  • usage
    • universal argument
    • window management
      • restart/quit/info
      • layout
      • multiple screens/multi-head/RANDR
      • misc
    • persistent dynamic tagging
      • tag persistence
      • add/delete/rename
      • view
      • move
    • client management
      • operation
      • change focus
      • swap order/select master
      • move/copy to tag
      • change space allocation in tile layout
      • misc
    • app bindings
      • admin
      • everyday
      • the rest
    • tag list
    • task list
    • root window/"the desktop"
    • window/task/client title bar
  • customization
  • todo

awesome Window Manager configuration

This is my fork of pw4ever's fantastic Awesome WM config. All credit for the original configuration goes to them.

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:

• 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.
    • apparently, I am not the only one who desire this
  • 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).

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/syndr/awesome-wm-config.git awesome

• Setup .xinitrc or Display Manager accordingly.

dependencies and nice-to-haves

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

miscellaneous

• populate your $HOME/.config/autostart with Desktop Entry Specification-style autostart files (optionally with OnlyShowIn=awesome if you only want them to auto-start in awesome).
• my autostart setup can be found here.

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
ModkeyCtrl\	clear all pending notifications
ModkeyAlt\	toggle between suspending/resuming notifications
Modkeyf1	open help in browser
CtrlShiftEsc	open task manager	xfce4-taskmanager

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

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	attach/launch terminal multiplexer

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
Modkey]	increase opacity by 10%	need composite manager
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
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

everyday

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

the rest

• currently optimized for Thinkpad W530 keyboard layout
• take a look at the config for details.

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

todo

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