DOWNLOAD SOURCE: WASTE Window Manager [Version 0.3.0] [public domain]
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ WASTE Window Manager (wastewm) User Guide ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
WASTE is a lightweight X11 window manager with a built-in taskbar, a right-hand
sidebar of live widgets, nine workspaces, and a set of skins and accent colors. It
needs no desktop environment and no toolkit libraries. It uses only Xlib, plus
Xinerama if you have more than one monitor.
──────────────────────────────────────────────────────────────────────────────────────
Contents
1 Features
2 Dependencies
3 Installing dependencies
4 Building
5 Installing and starting WASTE
6 Using WASTE
7 The sidebar
8 Keyboard shortcuts
9 Configuration files
10 Command-line options
11 Troubleshooting
12 Platform support
──────────────────────────────────────────────────────────────────────────────────────
1. Features
Windows
• Titlebar with minimize, maximize and close buttons.
• Resize from any edge or corner.
• Double-click a titlebar to maximize.
• Shade (roll up) a window to just its titlebar.
• A per-window menu (right-click the titlebar).
• Half-screen snapping and fullscreen support.
• Alt-drag to move or resize from anywhere in a window.
• Hover focus: the window under the pointer receives typing, and a click raises it.
• Urgent windows blink in the taskbar.
Workspaces
• 9 workspaces in a 3x3 grid, with a pager in both the taskbar and the sidebar.
Taskbar
• Menu button, show-desktop button, window buttons, pager, sidebar toggle, system
tray and clock.
• One taskbar per monitor, with multi-monitor support through Xinerama.
Application menu
• Built automatically from installed .desktop files, grouped into categories.
System tray
• Tray icons from other programs are docked into the primary taskbar.
Themes
• 8 skins and 8 accent colors, which can be mixed freely.
• The desktop backdrop follows the accent.
• The theme can be locked.
Sidebar widgets
• Ticker, clock, system information, per-core CPU, processes, audio, network, disks,
calendar, weather, run box with launcher grid, and a scratch pad.
• Every widget can be folded, hidden or reordered.
Reliability
• If the WM crashes or hangs, it restarts itself and re-adopts your windows.
• "Restart WASTE" keeps all windows open.
──────────────────────────────────────────────────────────────────────────────────────
2. Dependencies
To build
• A C++17 compiler (GCC 7 or newer, or a recent Clang)
• Xlib development files (libX11)
• Xinerama development files (libXinerama). This is optional and only needed for
multi-monitor support.
To run
• An X server
• The standard X11 core bitmap fonts (the "misc" fonts, such as 6x13 and 7x13bold).
WASTE exits at startup if it cannot load any core font.
Optional runtime tools (widgets show "n/a" without them):
Feature Needs
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Weather widget curl or wget, plus network access
Audio widget pactl (PipeWire or PulseAudio) or amixer (ALSA)
Disks widget df with GNU options (-PkT)
Info launcher htop or top, and a terminal that supports -title and -e
Launcher buttons Any of the programs listed in section 7.9
──────────────────────────────────────────────────────────────────────────────────────
3. Installing dependencies
Package names vary between releases. If one is not found, search your package manager
for libx11, libxinerama and font-misc.
Debian, Ubuntu, Linux Mint
sudo apt install build-essential libx11-dev libxinerama-dev xfonts-base xterm
Arch Linux, Manjaro
sudo pacman -S base-devel libx11 libxinerama xorg-fonts-misc xterm
Fedora, RHEL, Rocky, AlmaLinux
sudo dnf install gcc-c++ libX11-devel libXinerama-devel xorg-x11-fonts-misc xterm
openSUSE
sudo zypper install gcc-c++ libX11-devel libXinerama-devel xorg-x11-fonts xterm
Void Linux
sudo xbps-install base-devel libX11-devel libXinerama-devel font-misc-misc xterm
Alpine Linux
sudo apk add build-base libx11-dev libxinerama-dev font-misc-misc xterm
Gentoo
sudo emerge x11-libs/libX11 x11-libs/libXinerama media-fonts/font-misc-misc
x11-terms/xterm
NetBSD
The compiler, X libraries, headers and fonts all ship with NetBSD. Make sure the X11
sets (xbase, xcomp, xfont) were installed. Optional extras come from pkgsrc:
pkgin install curl htop
FreeBSD (not tested)
pkg install gcc libX11 libXinerama font-misc-misc xterm
Headers and libraries are under /usr/local.
Optional runtime tools (Debian/Ubuntu example)
sudo apt install curl pulseaudio-utils alsa-utils htop
pulseaudio-utils provides pactl, which also works with PipeWire. alsa-utils provides
amixer.
──────────────────────────────────────────────────────────────────────────────────────
4. Building
Linux
g++ -std=c++17 -Wall -Wextra -pedantic -Wconversion -Wshadow wastewm.cpp -o wastewm -lX
-lXinerama
A plain build without the warning flags works too:
g++ -std=c++17 -O2 wastewm.cpp -o wastewm -lX11 -lXinerama
Without Xinerama (single-monitor only)
g++ -std=c++17 -O2 -DWASTEWM_NO_XINERAMA wastewm.cpp -o wastewm -lX11
NetBSD
X11 lives under /usr/X11R7, so add the include and library paths:
g++ -std=c++17 -O2 -I/usr/X11R7/include wastewm.cpp -o wastewm \
-L/usr/X11R7/lib -Wl,-R/usr/X11R7/lib -lX11 -lXinerama
Build options
Define Effect
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-DWASTEWM_NO_XINERAMA Build without multi-monitor support
-DWASTEWM_NO_BACKTRACE Build without crash-log backtraces. This is selected
automatically on systems without glibc.
──────────────────────────────────────────────────────────────────────────────────────
5. Installing and starting WASTE
Install the binary
sudo cp wastewm /usr/local/bin/
sudo chmod 755 /usr/local/bin/wastewm
You can also keep it in ~/bin and use that path below.
Start from the console with startx
Put this in ~/.xinitrc:
exec wastewm
Then run startx. To start programs along with the WM, launch them in the background
first:
xsetroot -cursor_name left_ptr &
exec wastewm
Start from a graphical login manager
Create /usr/share/xsessions/wastewm.desktop:
[Desktop Entry]
Name=WASTE
Comment=WASTE Window Manager
Exec=/usr/local/bin/wastewm
Type=Application
Choose "WASTE" from the session menu at login.
Try it safely in a window
Xephyr :2 -screen 1280x800 &
DISPLAY=:2 wastewm
──────────────────────────────────────────────────────────────────────────────────────
6. Using WASTE
6.1 Windows
Action How
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Move Drag the titlebar, or hold Alt and drag anywhere in the
window
Resize Drag any edge or corner, or hold Alt and right-drag
Maximize / restore Maximize button, or double-click the titlebar
Minimize Minimize button, or click the window's taskbar button
Close Close button, Alt+F4, or middle-click its taskbar button
Shade (roll up) Middle-click the titlebar, or Alt+F3
Window menu Right-click the titlebar
Cancel a move or resize Esc while dragging
The titlebar buttons are, from left to right: minimize, maximize, close.
Snapping: drag a window by its titlebar and release with the pointer at the top screen
edge to maximize. Release at the left or right edge to fill that half of the screen.
Focus: moving the pointer over a window gives it keyboard focus without raising it.
Clicking anywhere in a window raises and focuses it.
New windows: if a program asks for a position (for example xterm -geometry +100+100),
it is placed there. Otherwise windows cascade.
Window menu items: Restore, Minimize, Maximize, Shade / Unshade, Send to Next Desk,
Send to Prev Desk, Close.
6.2 Workspaces
There are nine workspaces, arranged 3x3.
• Click a cell in the pager (taskbar or sidebar), or use the keyboard shortcuts in
section 8.
• Scroll the mouse wheel over the desktop, taskbar or sidebar to move to the previous
or next workspace.
• Use the window menu to send a window to the next or previous workspace.
• A window whose urgency flag is set makes its workspace cell blink in the taskbar
pager.
6.3 The taskbar
From left to right:
• MENU: opens the application menu.
• Show-desktop button: minimizes all windows on the current workspace. Press it again
to bring back exactly those windows.
• Window buttons: click to focus. Clicking the focused window minimizes it, and
clicking a minimized window restores it. Middle-click closes the window.
• Sidebar toggle, pager, tray and clock on the right.
On multi-monitor systems each monitor has its own taskbar. The sidebar and system tray
live on the first monitor.
6.4 The application menu
Open it with the MENU button, Alt+F10, or a right-click on the empty desktop.
• Hover a category to open its submenu. Categories are Accessories, Development,
Games, Graphics, Internet, Multimedia, Office, System and Other, built from
.desktop files in /usr/share/applications and ~/.local/share/applications.
• Built-in submenus:
• Skins: choose a skin and toggle the theme lock.
• Accent color: choose an accent.
• Sidebar widgets: show or hide widgets, set ticker motion, lock the layout, and
reset the layout.
• Fixed entries: Terminal, Restart WASTE, Exit WASTE.
Restart WASTE restarts the window manager in place, and your windows stay open.
6.5 System tray
Programs that support the standard system tray protocol dock their icons into the
primary taskbar automatically.
6.6 Themes
A theme is a skin plus an accent color.
• Skins: INDUSTRIAL, CLASSIC, PHOSPHOR, COBALT, AQUA, CARBON, VAPOR, BLUEPRINT.
• Accents: AMBER, CYAN, STEEL, ACID, VIOLET, PINK, BLOOD, VOLT.
Change them from the sidebar's THEME panel (section 7.11) or from the application
menu. Choosing a skin also selects that skin's default accent, and you can pick a
different accent afterwards. The accent also sets the desktop backdrop color. Your
choice is saved.
The theme lock freezes the skin and accent so that no control can change them.
──────────────────────────────────────────────────────────────────────────────────────
7. The sidebar
The sidebar sits on the right edge of the first monitor. Maximized windows and snapped
windows leave room for it. Hide or show it with the taskbar toggle button or Super+B.
7.1 Arranging widgets
• Click the +/- box, or click a widget's caption, to fold or unfold it.
• Drag a caption up or down to reorder widgets. A line shows where it will drop.
• Right-click a caption to show only that widget. Right-click again to restore all of
them.
• Hide or show widgets from MENU > Sidebar widgets.
• Layout lock (padlock next to LAYOUT at the bottom) stops reordering.
• Reset layout in the Sidebar widgets menu restores the default order and visibility.
• If the unfolded widgets are taller than the sidebar, the stack scrolls. Use the
mouse wheel or the thin scrollbar at the right edge.
• Lists with their own scrollbar (processes, cores, disks, system info) scroll with
the wheel while the pointer is over them.
On the first run, if the widgets would not fit your screen, the least essential ones
start folded.
7.2 Ticker
A scrolling line showing the focused window's title, the date, load, memory use and
current workspace. Motion can be still, gentle or smooth (MENU > Sidebar widgets >
Ticker motion). The default is still, and the animated settings cost more CPU and
redraws.
7.3 Clock
An analog clock with a digital date and time line.
7.4 System
• Live CPU and memory meters.
• A scrollable information box showing host name, OS, model, kernel, architecture,
CPU, GPU driver, RAM, screen resolution, package count, shell, uptime, load, memory
and current theme.
7.5 CPU cores
One meter per core, with its load and (where the hardware reports it) temperature. The
meters show a peak-hold marker.
7.6 Processes
The top processes by CPU use, with their CPU percentage and memory.
7.7 Audio
• Drag the volume bar, or scroll the wheel over the widget (5% per step).
• Click MUTE to toggle mute.
• Uses pactl when available, otherwise amixer.
7.8 Network, Disks, Calendar and Weather
• Network: current download and upload rates with a short history graph.
• Disks: each mounted block device with used and total size and a usage meter.
• Calendar: use the arrows to change months, and click the month title to return to
the current month.
• Weather: shows the current temperature and conditions. Click set... to enter a
location such as Paris, or leave it blank (Use auto) to detect it automatically
from your connection. Press Enter to save or Esc to cancel. Data refreshes every 15
minutes in the background and never blocks the window manager.
7.9 Run & Launch
• Run field: click it (or press Super+R), type a command and press Enter. Press Esc
to cancel.
• Launcher grid: six buttons: Term, Web, Edit, Mail, Files and Info. At startup WASTE
picks the first installed program from each list:
Button Programs tried, in order
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Term xterm, urxvt, st, xfce4-terminal, lxterminal
Web firefox, chromium, google-chrome, epiphany, midori, dillo, surf
Edit gvim, emacs, gedit, mousepad, leafpad, xedit, nano
Mail thunderbird, evolution, claws-mail, sylpheed, mutt
Files thunar, pcmanfm, nautilus, dolphin, xfe, rox
Info opens a terminal running htop or top
A button with no installed program is dimmed. Terminal-only programs such as nano and
mutt run inside the Term program.
To set your own commands, click set... next to LAUNCH, click a row, type the exact
command, and press Enter to save it or Esc to cancel. Reset to defaults goes back to
automatic detection. Overrides are saved.
While the run field has the keyboard, ordinary typing goes to it and window-manager
shortcuts are suspended. Press Esc or click a window to return to normal.
7.10 Scratch pad
A small always-available notepad. Your text is saved automatically.
• Click to place the cursor. Drag to select. Double-click selects a word and
triple-click selects a line.
• Standard editing keys: arrows, Home/End, PageUp/PageDown, Shift to select,
Ctrl+arrows to move by word, Backspace/Delete (Ctrl for word).
• Ctrl+A select all, Ctrl+C copy, Ctrl+X cut, Ctrl+V paste, Ctrl+Z undo, Ctrl+Y or
Ctrl+Shift+Z redo.
• Selecting text makes it available to middle-click paste in other programs, and
middle-click pastes into the pad.
• Press Esc to leave the pad.
7.11 DESK and THEME (bottom row)
• DESK: the workspace pager.
• THEME: the left and right arrows change the skin and accent, and the padlock next
to THEME locks the theme. The LAYOUT padlock locks widget order.
──────────────────────────────────────────────────────────────────────────────────────
8. Keyboard shortcuts
"Super" is the Windows key.
Shortcut Action
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Alt+Tab, Super+Tab Cycle focus through windows on this workspace
Alt+F4 Close the focused window
Alt+F2, Super+Enter, Super+` Open a terminal
Alt+F3 Shade or unshade the focused window
Alt+F5 Maximize or restore the focused window
Alt+F10 Open or close the application menu
Ctrl+Alt+1 ... 9, Super+1 ... 9 Go to workspace 1 to 9
Ctrl+Alt+Left / Right Previous or next workspace
Super+R Focus the sidebar run field (shows the sidebar
if hidden)
Super+B Show or hide the sidebar
Super+F Toggle fullscreen
Super+Left / Right Snap to the left or right half. Press the same
key again to restore the previous size
Super+Up Maximize
Super+Down Restore if maximized, otherwise minimize
Esc Close an open menu, or cancel a move or resize
Mouse summary
Mouse action Result
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Right-click the desktop Application menu
Mouse wheel on desktop, taskbar or sidebar Previous or next workspace
Right-click a titlebar Window menu
Middle-click a titlebar Shade
Alt + left-drag in a window Move
Alt + right-drag in a window Resize
──────────────────────────────────────────────────────────────────────────────────────
9. Configuration files
Everything WASTE remembers is kept in ~/.config/wastewm/.
File Contents
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
theme Accent, skin and theme-lock state
layout Widget order, hidden widgets, layout lock, ticker motion
sections Which widgets are folded
launchers.conf Your launcher command overrides (Label=command, one per line)
weather.loc Weather location (empty means auto-detect)
weather.cache Last fetched weather line
scratch Scratch pad text
dpi Saved DPI value from --dpi
crash.log Crash and stall reports (see Troubleshooting)
You can edit these with a text editor while WASTE is stopped. Deleting a file resets
that setting.
──────────────────────────────────────────────────────────────────────────────────────
10. Command-line options
wastewm [options]
--version print the version and exit
--help print usage and exit
--debug verbose diagnostics on stderr
--legacy-draw draw through X server requests instead of the client-side canvas
--dpi=N set the Xft.dpi advertised to programs (48 to 400); saved for futur
runs
• DPI: by default WASTE sets Xft.dpi to 96 only if nothing else (for example
~/.Xresources via xrdb) has set it. On a HiDPI screen use --dpi=144 (or another
value) once, and it is remembered.
• --legacy-draw: the default drawing mode renders the taskbar and sidebar in memory
and sends one image to the X server per update. If it misbehaves on your graphics
setup, try --legacy-draw. You can also set WASTEWM_LEGACY_DRAW=1 in the
environment.
• Signals: kill -HUP <pid> restarts WASTE in place. kill -TERM <pid> shuts it down
cleanly and hands your windows back to the X server.
──────────────────────────────────────────────────────────────────────────────────────
11. Troubleshooting
"another window manager is already running" Only one window manager can run per
display. Stop the other one first.
"unable to load an X11 core font" Install the X11 misc bitmap fonts (section 3).
Widgets show "n/a" or are empty
• Weather: install curl or wget and check your network.
• Audio: install pactl or amixer.
• Processes, cores, network, disks, system information: these read Linux system files
(see section 12).
Text in some applications is the wrong size Set the DPI once with wastewm --dpi=N, or
set Xft.dpi in ~/.Xresources.
Lock-ups and crash recovery
• If WASTE crashes, it writes a report to ~/.config/wastewm/crash.log and restarts
itself, re-adopting your windows. After five rapid crashes in a row it stops
restarting.
• If its main loop stalls, it restarts itself. If it is instead stuck waiting for an
unresponsive X server, it only logs that fact and keeps waiting.
• If you report a bug, please include crash.log.
Tray icon does not appear Another program may already own the system tray. Only one
can.
──────────────────────────────────────────────────────────────────────────────────────
12. Platform support
• Linux: fully supported. All widgets work.
• NetBSD: builds and runs. The window manager features (windows, workspaces, taskbar,
menu, tray, themes, scratch pad, run box, launchers, calendar, clock, weather)
work. Widgets that read Linux-specific information (CPU/memory/process/network
statistics, system information, disks, and in part audio) may show "n/a" or empty
values. Crash reports on NetBSD do not include a backtrace.
• Other BSDs: not tested.