StumpWM Contrib

A collection of StumpWM modules

You can learn more about StumpWM modules consulting the documentation on our wiki.

Submitting a module

StumpWM has an open door policy for modules.

If you want to submit a new module, just send a PR adding the module to this repository.

Please, follow the directory structure already laid out below.

Just before you sending 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!

Current Modules

(click for its respective README/docs)

Media

amixer: Manipulate the volume using amixer

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.
cpu: Add cpu info to the modeline.
disk: Display filesystem information in 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.
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
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
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
surfraw: Integrates surfraw with stumpwm.
swm-emacs: A set of utilities for launching the beast.
swm-gaps: Pretty (useless) gaps for StumpWM
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
windowtags: Add metadata to windows to manipulate them en mass.
winner-mode: Emacs’ winner-mode for StumpWM

siawyoung/stumpwm-contrib