xmonad-contrib-0.18.0: Community-maintained extensions for xmonad
Copyright(c) Matus Goljer <matus.goljer@gmail.com>
LicenseBSD3-style (see LICENSE)
MaintainerMatus Goljer <matus.goljer@gmail.com>
Stabilityunstable
Portabilityunportable
Safe HaskellSafe-Inferred
LanguageHaskell2010

XMonad.Actions.Prefix

Description

A module that allows the user to use a prefix argument (raw or numeric).

Synopsis

Usage

This module implements Emacs-style prefix argument. The argument comes in two flavours, Raw and Numeric.

To initiate the "prefix mode" you hit the prefix keybinding (default C-u). This sets the Raw argument value to 1. Repeatedly hitting this key increments the raw value by 1. The Raw argument is usually used as a toggle, changing the behaviour of the function called in some way.

An example might be calling "mpc add" to add new song to the playlist, but with C-u we also clean up the playlist beforehand.

When in the "Raw mode", you can hit numeric keys 0..9 (with no modifier) to enter a "Numeric argument". Numeric argument represents a natural number. Hitting numeric keys in sequence produces the decimal number that would result from typing them. That is, the sequence C-u 4 2 sets the Numeric argument value to the number 42.

If you have a function which understands the prefix argument, for example:

   addMaybeClean :: PrefixArgument -> X ()
   addMaybeClean (Raw _) = spawn "mpc clear" >> spawn "mpc add <file>"
   addMaybeClean _ = spawn "mpc add <file>"

you can turn it into an X action with the function withPrefixArgument.

Binding it in your config

   ((modm, xK_a), withPrefixArgument addMaybeClean)

Hitting MOD-a will add the <file> to the playlist while C-u MOD-a will clear the playlist and then add the file.

You can of course use an anonymous action, like so:

   ((modm, xK_a), withPrefixArgument $ \prefix -> do
       case prefix of ...
   )

If the prefix key is followed by a binding which is unknown to XMonad, the prefix along with that binding is sent to the active window.

There is one caveat: when you use an application which has a nested C-u binding, for example C-c C-u in Emacs org-mode, you have to hit C-g (or any other non-recognized key really) to get out of the "xmonad grab" and let the C-c C-u be sent to the application.

Installation

The simplest way to enable this is to use useDefaultPrefixArgument

   xmonad $ useDefaultPrefixArgument $ def { .. }

The default prefix argument is C-u. If you want to customize the prefix argument, usePrefixArgument can be used:

   xmonad $ usePrefixArgument "M-u" $ def { .. }

where the key is entered in Emacs style (or XMonad.Util.EZConfig style) notation. The letter M stands for your chosen modifier. The function defaults to C-u if the argument could not be parsed.

usePrefixArgument :: LayoutClass l Window => String -> XConfig l -> XConfig l Source #

Set up Prefix. Defaults to C-u when given an invalid key.

See usage section.

useDefaultPrefixArgument :: LayoutClass l Window => XConfig l -> XConfig l Source #

Set Prefix up with default prefix key (C-u).

withPrefixArgument :: (PrefixArgument -> X a) -> X a Source #

Turn a prefix-aware X action into an X-action.

First, fetch the current prefix, then pass it as argument to the original function. You should use this to "run" your commands.

orIfPrefixed :: X a -> X a -> X a Source #

Execute the first action, unless any prefix argument is given, in which case the second action is chosen instead.

action1 `orIfPrefixed` action2

ppFormatPrefix :: X (Maybe String) Source #

Format the prefix using the Emacs convetion for use in a statusbar, like xmobar.

To add this formatted prefix to printer output, you can set it up like so

myPrinter :: PP
myPrinter = def { ppExtras = [ppFormatPrefix] }

And then add to your status bar using XMonad.Hooks.StatusBar:

mySB = statusBarProp "xmobar" myPrinter
main = xmonad $ withEasySB mySB defToggleStrutsKey def

Or, directly in your logHook configuration

logHook = dynamicLogWithPP myPrinter