A collection of StumpWM modules

Documentation on modules can be found on our wiki.

Submitting a module

Right now we have an open door policy for modules. If you want it in, just submit a PR adding the module to this repo. Follow the directory structure already laid out below. Right before you’re ready to make the final PR commit, run the script ’update-readme.sh’ to have your module (and its description) added to the appropriate category. The script uses the ”:description” tag in the .asd file. The script is pretty dumb, so if your description spans multiple lines, it probably won’t show up correctly. Keep it short and sweet.

How to write a module

General guidelines

Create your own package and optionally import the stumpwm

package. Don’t use the stumpwm package. If you need a symbol exported, open an issue.

Use asdf.
Document exported symbols and commands.
Stay organized! Put things in neat little directories. A Distribution might want to package your module.

A pseudo-tutorial

The path of least resistance is to use `quickproject` and its helper functions. Specifically (get quicklisp):

(ql:quickload "quickproject")
(quickproject:make-project #p"~/path/to/new-module" :depends-on '(stumpwm) :name "swm-new-module")

Then in ~/path/to/new-module/ you will have:

-rw-rw-r--  1 dave dave   68 Apr  6 19:38 package.lisp
-rw-rw-r--  1 dave dave   53 Mar 16  2014 README.txt
-rw-rw-r--  1 dave dave  271 Mar 16  2014 swm-new-module.asd
-rw-rw-r--  1 dave dave 1.8K Apr  6 17:51 swm-new-module.lisp

The files that are important for you are package.lisp and swm-new-module.asd. They contain the asdf metadata that describes your project.

An example asd file looks like:

(asdf:defsystem #:swm-new-module
  :serial t
  :description "Describe swm-new-module here"
  :author "Guy Steele"
  :license "GPLv3"
  :depends-on (#:stumpwm)
  :components ((:file "package")
               (:file "swm-emacs"))) ; any other files you make go here

A package.lisp looks like:

(defpackage #:swm-new-module
  (:use #:cl :stumpwm))

From here you can commence hacking. When you’re ready, advertise it to the world!

More docs here.

Loading a module

Loading a module can usually be done in your ~/.stumpwmrc for a module module-name using:

(load-module "module-name")

Please see README.org files for each module for further details. Missing module dependencies, can be installed with:

(ql:quickload "notify")

Third Party Modules

Advertise your module here, open a PR and include a org-mode link!

stumpwm-weather: Displays weather in the modeline
stumpwm-dmenu: StumpWM dmenu integration
stumpwm-pamixer: Pulseaudio volume and microphone control module
stumpwm-acpi-backlight: ACPI backlight control module for StumpWM
stumpwm-mullvad: StumpWM mullvad cli integration

Current Modules

(click for its respective README/docs)

Media

amixer: Manipulate the volume using amixer
stump-radio: Minimalistic mplayer-based radio for StumpWM.
stump-volume-control: Minimalistic amixer-based volume control for StumpWM.
stumpwm-sndioctl: Interface to OpenBSD’s sndioctl from StumpWM.

Minor Modes

mpd: Displays information about the music player daemon (MPD).
notifications: A notification library that sends notifications to the modeline via stumpish or from stumpwm itself.

Modeline

battery-portable: Add battery information to the modeline in a portable way.
bitcoin: Display bitcoin price on StumpWM modeline.
clim-mode-line: A modeline written in CLIM
cpu: Add cpu info to the modeline.
disk: Display filesystem information in the modeline
hidden: Add hidden window info to the modeline.
hostname: Put hostname in the StumpWM modeline
maildir: Display maildir information in the modeline (%M conflicts with mem).
mem: Display memory in the modeline, %M conflicts with maildir.
net: Displays information about the current network connection.
stumptray: System Tray for stumpwm.
ticker: Display ticker price on StumpWM modeline.
wifi: Display information about your wifi.

Utilities

alert-me: Alert me that an event is coming
app-menu: A simple application menu for launching shell commands
beckon: Beckon the mouse to the current window
binwarp: Keyboard-driven divide-and-conquer mouse control mode.
browse: Open the default web browser portably
clipboard-history: Simple clipboard history module for StumpWM
command-history: Save and load the stumpwm::*input-history* to a file
desktop-entry: desktop-entry
end-session: Provides commands to stumpwm that allow the user to shutdown, restart, and logoff through the stumpwm UI
globalwindows: Manipulate all windows in the current X session
gnu-pw-mgr: Reconstruct passwords with gnu-pw-mgr
swm-golden-ratio: Resize the currently focused frame to the golden ratio
kbd-layouts: Keyboard layout switcher for StumpWM
logitech-g15-keysyms: Describe logitech-g15-keysyms here
lookup: Dictionary/search engine lookup module for StumpWM.
notify: DBus-based notification server part
numpad-layouts: A module for handling different keyboards numpad layouts
pass: Integrate ‘pass’ with StumpWM
passwd: A simple password utility based on ironclad.
perwindowlayout: Change the keyboard layout per window.
pinentry: Integrate GnuPG Agent with StumpWM
swm-pomodoro: Pretty basic Pomodoro-tracker for StumpWM.
productivity: Lock StumpWM down so you have to get work done.
qubes: Integration to Qubes OS (https://www.qubes-os.org)
screenshot: Takes screenshots and stores them as png files
searchengines: Allows searching text using prompt or clipboard contents with various search engines
shell-command-history: Save and load the stumpwm::*input-shell-history* to a file
spatial-groups: Spatial Groups navigation for StumpWM
stump-backlight: Native backlight control from StumpWM
stump-lock: Screen locker in StumpWM
stump-nm: StumpWM integration with NetworkManager
surfraw: Integrates surfraw with stumpwm.
swm-clim-message: Display StumpWM messages and menus through CLIM
swm-emacs: A set of utilities for launching the beast.
swm-gaps: Pretty (useless) gaps for StumpWM
swm-ssh: A simple menu selector for ssh to a remote host for stumpwm that parses your ssh config to get available hosts
ttf-fonts: A pure lisp implementation of TTF font rendering.
undocumented: Look for stuff that should probably be in the manual that isn’t
urgentwindows: Allows focusing application windows that need user attention
wacom: Map StumpWM frames to Wacom tablets using `xsetwacom`.
windowtags: Add metadata to windows to manipulate them en mass.
winner-mode: Emacs’ winner-mode for StumpWM

stumpwm/stumpwm-contrib

stumpwm

Reviews

Repository Details