XMonad.Actions.Prefix

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

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.

data PrefixArgument

Constructors

Raw Int

Numeric Int

None

Instances

Read PrefixArgument

Defined in XMonad.Actions.Prefix

Methods

readsPrec :: Int -> ReadS PrefixArgument

readList :: ReadS [PrefixArgument]

readPrec :: ReadPrec PrefixArgument

readListPrec :: ReadPrec [PrefixArgument]

Show PrefixArgument

Defined in XMonad.Actions.Prefix

Methods

showsPrec :: Int -> PrefixArgument -> ShowS

show :: PrefixArgument -> String

showList :: [PrefixArgument] -> ShowS

ExtensionClass PrefixArgument

Defined in XMonad.Actions.Prefix

Methods

initialValue :: PrefixArgument

extensionType :: PrefixArgument -> StateExtension

usePrefixArgument :: forall (l :: Type -> Type). LayoutClass l Window => String -> XConfig l -> XConfig l

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

See usage section.

useDefaultPrefixArgument :: forall (l :: Type -> Type). LayoutClass l Window => XConfig l -> XConfig l

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

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

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.

isPrefixRaw :: PrefixArgument -> Bool

Test if PrefixArgument is Raw or not.

isPrefixNumeric :: PrefixArgument -> Bool

Test if PrefixArgument is Numeric or not.

orIfPrefixed :: X a -> X a -> X a

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)

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