stumpwm.stumpwm-contrib/README.org

* 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/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
- [[./util/xinput-toggle/README.org][xinput-toggle]] :: Toggle (on/off) devices such as the touchpad, mouse, etc.