- A collection of StumpWM modules
Documentation on modules can be found [[https://github.com/stumpwm/stumpwm/wiki/Modules][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, [[https://github.com/stumpwm/stumpwm/issues][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 [[http://www.quicklisp.org/beta/][quicklisp]]):
+BEGIN_SRC lisp
(ql:quickload "quickproject")
(quickproject:make-project #p"~/path/to/new-module" :depends-on '(stumpwm) :name "swm-new-module")
+END_SRC
Then in =~/path/to/new-module/= you will have:
+BEGIN_EXAMPLE
-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
+END_EXAMPLE
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:
+BEGIN_EXAMPLE
(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
+END_EXAMPLE
A =package.lisp= looks like:
+BEGIN_EXAMPLE
(defpackage #:swm-new-module
(:use #:cl :stumpwm))
+END_EXAMPLE
From here you can commence hacking. When you're ready, advertise it
to the world!
[[http://www.xach.com/lisp/quickproject/][More docs here]].
** Loading a module
Loading a module can usually be done in your =~/.stumpwmrc= for a module =module-name= using:
+begin_src lisp
(load-module "module-name")
+end_src
Please see =README.org= files for each module for further details. Missing module dependencies, can be installed with:
+begin_src lisp
(ql:quickload "notify")
+end_src
Don't edit anything below this line, the script will blow it away
--
** Media
- [[./media/amixer/README.org][amixer]] :: Manipulate the volume using amixer
- [[./media/stump-radio/README][stump-radio]] :: Minimalistic mplayer-based radio for StumpWM.
- [[./media/stump-volume-control/README][stump-volume-control]] :: Minimalistic amixer-based volume control for StumpWM.
- [[./media/stumpwm-mixer/README.md][stumpwm-mixer]] :: Interface to FreeBSD's built-in sound mixer
- [[./media/stumpwm-sndioctl/README.md][stumpwm-sndioctl]] :: Interface to OpenBSD's sndioctl from StumpWM.
** Minor Modes
- [[./minor-mode/mpd/README.org][mpd]] :: Displays information about the music player daemon (MPD).
- [[./minor-mode/notifications/README.org][notifications]] :: A notification library that sends notifications to the modeline via stumpish or from stumpwm itself.
** Modeline
- [[./modeline/battery-portable/README.org][battery-portable]] :: Add battery information to the modeline in a portable way.
- [[./modeline/bitcoin/README.org][bitcoin]] :: Display bitcoin price on StumpWM modeline.
- [[./modeline/clim-mode-line/README.org][clim-mode-line]] :: A modeline written in CLIM
- [[./modeline/cpu/README.org][cpu]] :: Add cpu info to the modeline.
- [[./modeline/disk/README.org][disk]] :: Display filesystem information in the modeline
- [[./modeline/hidden/README.org][hidden]] :: Add hidden window info to the modeline.
- [[./modeline/hostname/README.org][hostname]] :: Put hostname in the StumpWM modeline
- [[./modeline/maildir/README.org][maildir]] :: Display maildir information in the modeline (%M conflicts with mem).
- [[./modeline/mem/README.org][mem]] :: Display memory in the modeline, %M conflicts with maildir.
- [[./modeline/net/README.org][net]] :: Displays information about the current network connection.
- [[./modeline/pianobar/README.org][pianobar]] :: Display Pianobar's now playing info in modeline
- [[./modeline/stumptray/README.org][stumptray]] :: System Tray for stumpwm.
- [[./modeline/ticker/README.org][ticker]] :: Display ticker price on StumpWM modeline.
- [[./modeline/wifi/README.org][wifi]] :: Display information about your wifi.
** Utilities
- [[./util/alert-me/README.org][alert-me]] :: Alert me that an event is coming
- [[./util/app-menu/README.org][app-menu]] :: A simple application menu for launching shell commands
- [[./util/beckon/README.org][beckon]] :: Beckon the mouse to the current window
- [[./util/binwarp/README.org][binwarp]] :: Keyboard-driven divide-and-conquer mouse control mode.
- [[./util/browse/README.org][browse]] :: Open the default web browser portably
- [[./util/clipboard-history/README.org][clipboard-history]] :: Simple clipboard history module for StumpWM
- [[./util/command-history/README.org][command-history]] :: Save and load the stumpwm::input-history to a file
- [[./util/desktop-entry/README.org][desktop-entry]] :: desktop-entry
- [[./util/end-session/README.org][end-session]] :: Provides commands to stumpwm that allow the user to shutdown, restart, and logoff through the stumpwm UI
- [[./util/globalwindows/README.org][globalwindows]] :: Manipulate all windows in the current X session
- [[./util/gnu-pw-mgr/README.md][gnu-pw-mgr]] :: Reconstruct passwords with gnu-pw-mgr
- [[./util/golden-ratio/README.org][swm-golden-ratio]] :: Resize the currently focused frame to the golden ratio
- [[./util/kbd-layouts/README.org][kbd-layouts]] :: Keyboard layout switcher for StumpWM
- [[./util/logitech-g15-keysyms/README.org][logitech-g15-keysyms]] :: Describe logitech-g15-keysyms here
- [[./util/lookup/README.org][lookup]] :: Dictionary/search engine lookup module for StumpWM.
- [[./util/notify/README.org][notify]] :: DBus-based notification server part
- [[./util/numpad-layouts/README.org][numpad-layouts]] :: A module for handling different keyboards numpad layouts
- [[./util/pass/README.org][pass]] :: Integrate 'pass' with StumpWM
- [[./util/passwd/README.org][passwd]] :: A simple password utility based on ironclad.
- [[./util/perwindowlayout/README.org][perwindowlayout]] :: Change the keyboard layout per window.
- [[./util/pinentry/README.org][pinentry]] :: Integrate GnuPG Agent with StumpWM
- [[./util/pomodoro/README.org][swm-pomodoro]] :: Pretty basic Pomodoro-tracker for StumpWM.
- [[./util/productivity/README.org][productivity]] :: Lock StumpWM down so you have to get work done.
- [[./util/qubes/README.org][qubes]] :: Integration to Qubes OS (https://www.qubes-os.org)
- [[./util/screenshot/README.org][screenshot]] :: Takes screenshots and stores them as png files
- [[./util/searchengines/README.org][searchengines]] :: Allows searching text using prompt or clipboard contents with various search engines
- [[./util/shell-command-history/README.org][shell-command-history]] :: Save and load the stumpwm::input-shell-history to a file
- [[./util/spatial-groups/README][spatial-groups]] :: Spatial Groups navigation for StumpWM
- [[./util/stump-backlight/README.org][stump-backlight]] :: Native backlight control from StumpWM
- [[./util/stump-lock/README.org][stump-lock]] :: Screen locker in StumpWM
- [[./util/stump-nm/README.org][stump-nm]] :: StumpWM integration with NetworkManager
- [[./util/surfraw/README.org][surfraw]] :: Integrates surfraw with stumpwm.
- [[./util/swm-clim-message/README.org][swm-clim-message]] :: Display StumpWM messages and menus through CLIM
- [[./util/swm-emacs/README.txt][swm-emacs]] :: A set of utilities for launching the beast.
- [[./util/swm-gaps/README.org][swm-gaps]] :: Pretty (useless) gaps for StumpWM
- [[./util/swm-ssh/README.org][swm-ssh]] :: A simple menu selector for ssh to a remote host for stumpwm that parses your ssh config to get available hosts
- [[./util/ttf-fonts/README.txt][ttf-fonts]] :: A pure lisp implementation of TTF font rendering.
- [[./util/undocumented/README.org][undocumented]] :: Look for stuff that should probably be in the manual that isn't
- [[./util/urgentwindows/README.org][urgentwindows]] :: Allows focusing application windows that need user attention
- [[./util/wacom/README.org][wacom]] :: Map StumpWM frames to Wacom tablets using
xsetwacom.
- [[./util/windowtags/README.org][windowtags]] :: Add metadata to windows to manipulate them en mass.
- [[./util/winner-mode/README.org][winner-mode]] :: Emacs' winner-mode for StumpWM