* 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 * Third Party Modules Advertise your module here, open a PR and include a org-mode link! - [[https://github.com/njkli/stumpwm-weather/blob/master/readme.org][stumpwm-weather]] :: Displays weather in the modeline - [[https://codeberg.org/sasanidas/stumpwm-dmenu][stumpwm-dmenu]] :: StumpWM [[https://tools.suckless.org/dmenu/][dmenu]] integration - [[https://github.com/Junker/stumpwm-pamixer][stumpwm-pamixer]] :: Pulseaudio volume and microphone control module - [[https://github.com/Junker/stumpwm-acpi-backlight][stumpwm-acpi-backlight]] :: ACPI backlight control module for StumpWM - [[https://codeberg.org/sasanidas/stumpwm-mullvad][stumpwm-mullvad]] :: StumpWM [[https://mullvad.net/en/][mullvad]] cli integration * Current Modules (click for its respective README/docs) # 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/fml/README.md][swm-frame-mode-line]] :: Mode line per frame - [[./minor-mode/grabbable-modifier-keys/README.md][grabbable-modifier-keys]] :: Allow StumpWM users to grab modifier keys and bind them - [[./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/sdl-fonts/README.md][sdl-fonts]] :: SDL-based TTF font rendering for StumpWM. - [[./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/swm-ykman/README.org][swm-ykman]] :: Yubikey OATH TOTP manager for StumpWM - [[./util/swm-tmux/README.org][swm-tmux]] :: Tmux session manager for StumpWM - [[./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 - [[./util/xinput-toggle/README.org][xinput-toggle]] :: Toggle (on/off) devices such as the touchpad, mouse, etc.