xmonad-contrib-0.17.1: Community-maintained extensions for xmonad

Copyright | (c) Matus Goljer <matus.goljer@gmail.com>
License | BSD3-style (see LICENSE)
Maintainer | Matus Goljer <matus.goljer@gmail.com>
Stability | unstable
Portability | unportable
Safe Haskell | Safe-Inferred
Language | Haskell2010

XMonad.Actions.Prefix

Contents

- Usage
- Installation

Description

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

Synopsis

- data PrefixArgument
  - = Raw Int
  - | Numeric Int
  - | None
- usePrefixArgument :: LayoutClass l Window => String -> XConfig l -> XConfig l
- useDefaultPrefixArgument :: LayoutClass l Window => XConfig l -> XConfig l
- withPrefixArgument :: (PrefixArgument -> X ()) -> X ()
- isPrefixRaw :: PrefixArgument -> Bool
- isPrefixNumeric :: PrefixArgument -> Bool
- ppFormatPrefix :: X (Maybe String)

# 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

Instances details

Read PrefixArgument # |
Instance details Defined in XMonad.Actions.Prefix Methods readsPrec :: Int -> ReadS PrefixArgument # readList :: ReadS [PrefixArgument] # readPrec :: ReadPrec PrefixArgument readListPrec :: ReadPrec [PrefixArgument]
Show PrefixArgument # |
Instance details Defined in XMonad.Actions.Prefix Methods showsPrec :: Int -> PrefixArgument -> ShowS # show :: PrefixArgument -> String # showList :: [PrefixArgument] -> ShowS #
ExtensionClass PrefixArgument # |
Instance details Defined in XMonad.Actions.Prefix Methods initialValue :: PrefixArgument # extensionType :: PrefixArgument -> StateExtension #

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

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

See usage section.

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

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

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

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.

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