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

Copyright | (c) 2018 L. S. Leary
License | BSD3-style (see LICENSE)
Maintainer | Yecine Megdiche <yecine.megdiche@gmail.com>
Stability | unstable
Portability | unportable
Safe Haskell | None
Language | Haskell2010

XMonad.Hooks.Modal

Contents

- Usage
- Provided Modes
- Logger

Description

This module implements modal keybindings for xmonad.

Synopsis

- modal :: forall (l :: Type -> Type). [Mode] -> XConfig l -> XConfig l
- modeWithExit :: String -> String -> (XConfig Layout -> Map (KeyMask, KeySym) (X ())) -> Mode
- mode :: String -> (XConfig Layout -> Map (KeyMask, KeySym) (X ())) -> Mode
- data Mode
- mkKeysEz :: [(String, X ())] -> XConfig Layout -> Map (ButtonMask, KeySym) (X ())
- setMode :: String -> X ()
- exitMode :: X ()
- noModModeLabel :: String
- noModMode :: Mode
- floatModeLabel :: String
- floatMode :: Int -> Mode
- overlayedFloatModeLabel :: String
- overlayedFloatMode :: Int -> Mode
- floatMap :: KeyMask -> KeyMask -> KeyMask -> Int -> Map (ButtonMask, KeySym) (X ())
- overlay :: String -> Mode -> Mode
- logMode :: Logger

# Usage

This module provides modal keybindings in xmonad. If you're not familiar with modal keybindings from Vim, you can think of modes as submaps from XMonad.Actions.Submap, but after each action you execute, you land back in the submap until you explicitly exit the submap. To use this module you should apply the `modal` function to the config, which will setup the list of modes (or rather, `XConfig Layout -> Mode`) you provide:

    import XMonad
    import XMonad.Hooks.Modal
    import XMonad.Util.EZConfig
    import qualified Data.Map as M

    main :: IO ()
    main =
      xmonad
        . modal [noModMode, floatMode 10, overlayedFloatMode 10, sayHelloMode]
        $ def
        `additionalKeysP` [ ("M-S-n", setMode noModModeLabel)
                          , ("M-S-r", setMode floatModeLabel)
                          , ("M-S-z", setMode overlayedFloatModeLabel)
                          , ("M-S-h", setMode "Hello")
                          ]

    sayHelloMode :: Mode
    sayHelloMode = mode "Hello" $ mkKeysEz
      [ ("h", xmessage "Hello, World!")
      , ("M-g", xmessage "Goodbye, World!")
      ]

Alternatively, one could have defined `sayHelloMode` as

    sayHelloMode :: Mode
    sayHelloMode = mode "Hello" $ \cfg ->
      M.fromList [ ((noModMask, xK_h), xmessage "Hello, World!")
                 , ((modMask cfg, xK_g), xmessage "Goodbye, World!")
                 ]

In short, a `Mode` has a label describing its purpose, as well as attached keybindings. These are of the form

- `[(String, X ())]`, or
- `XConfig Layout -> M.Map (ButtonMask, KeySym) (X ())`.

The former—accessible via `mkKeysEz`—is how specifying keys work with XMonad.Util.EZConfig, while the latter is more geared towards how defining keys works by default in xmonad. Note that, by default, modes are exited with the Escape key. If one wishes to customise this, the `modeWithExit` function should be used instead of `mode` when defining a new mode.

The label of the active mode can be logged with `logMode` to be displayed in a status bar, for example (For more information check XMonad.Util.Loggers). Some examples are included in the provided modes.

modal :: forall (l :: Type -> Type). [Mode] -> XConfig l -> XConfig l #

Adds the provided modes to the user's config, and sets up the bells and whistles needed for them to work.

modeWithExit :: String -> String -> (XConfig Layout -> Map (KeyMask, KeySym) (X ())) -> Mode #

Create a `Mode` from the given binding to `exitMode`, label and keybindings.

mode :: String -> (XConfig Layout -> Map (KeyMask, KeySym) (X ())) -> Mode #

Create a `Mode` from the given label and keybindings. Sets the `escape` key to `exitMode`.

data Mode #

The mode type. Use `mode` or `modeWithExit` to create modes.

mkKeysEz :: [(String, X ())] -> XConfig Layout -> Map (ButtonMask, KeySym) (X ()) #

From a list of XMonad.Util.EZConfig-style bindings, generate a key representation.

    >>> mkKeysEz [("h", xmessage "Hello, world!")]

setMode :: String -> X () #

Set the current `Mode` based on its label.

exitMode :: X () #

Exits the current mode.

# Provided Modes

noModModeLabel :: String #

noModMode :: Mode #

In this `Mode`, all keybindings are available without the need for pressing the modifier. Pressing `escape` exits the mode.

floatModeLabel :: String #

floatMode #

Arguments

:: Int | Step size
-> Mode |

A mode to control floating windows with `{hijk}`, `M-{hijk}` and `M-S-{hijk}` in order to respectively move, enlarge and shrink windows.

overlayedFloatModeLabel :: String #

overlayedFloatMode #

Arguments

:: Int | Step size
-> Mode |

Similar to `resizeMode`, but keeps the bindings of the original config active.

floatMap #

Arguments

:: KeyMask | Move mask
-> KeyMask | Enlarge mask
-> KeyMask | Shrink mask
-> Int | Step size
-> Map (ButtonMask, KeySym) (X ()) |

Generates the keybindings for `floatMode` and `overlayedFloatMode`.

overlay #

Arguments

:: String | Label for the new mode
-> Mode | Base mode
-> Mode |

Modifies a mode so that the keybindings are merged with those from the config instead of replacing them.

# Logger

logMode :: Logger #

A `Logger` to display the current mode.