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

Copyright | Clemens Fruhwirth <clemens@endorphin.org>
License | BSD-style (see LICENSE)
Maintainer | Clemens Fruhwirth <clemens@endorphin.org>
Stability | unstable
Portability | unportable
Safe Haskell | Safe-Inferred
Language | Haskell2010

XMonad.Actions.GridSelect

Contents

- Usage
  - Customizing
    - Using a common GSConfig
    - Custom keybindings
- Configuration
- Variations on `gridselect`
- Colorizers
- Navigation Mode assembly
- Built-in Navigation Mode
- Navigation Components
- Rearrangers
- Screenshots
- Types

Description

GridSelect displays items(e.g. the opened windows) in a 2D grid and lets the user select from it with the cursor/hjkl keys or the mouse.

Synopsis

- data GSConfig a = GSConfig {
  - gs_cellheight :: Integer
  - gs_cellwidth :: Integer
  - gs_cellpadding :: Integer
  - gs_colorizer :: a -> Bool -> X (String, String)
  - gs_font :: String
  - gs_navigate :: TwoD a (Maybe a)
  - gs_rearranger :: Rearranger a
  - gs_originFractX :: Double
  - gs_originFractY :: Double
  - gs_bordercolor :: String
  }
- def :: Default a => a
- type TwoDPosition = (Integer, Integer)
- buildDefaultGSConfig :: (a -> Bool -> X (String, String)) -> GSConfig a
- gridselect :: GSConfig a -> [(String, a)] -> X (Maybe a)
- gridselectWindow :: GSConfig Window -> X (Maybe Window)
- withSelectedWindow :: (Window -> X ()) -> GSConfig Window -> X ()
- bringSelected :: GSConfig Window -> X ()
- goToSelected :: GSConfig Window -> X ()
- gridselectWorkspace :: GSConfig WorkspaceId -> (WorkspaceId -> WindowSet -> WindowSet) -> X ()
- gridselectWorkspace' :: GSConfig WorkspaceId -> (WorkspaceId -> X ()) -> X ()
- spawnSelected :: GSConfig String -> [String] -> X ()
- runSelectedAction :: GSConfig (X ()) -> [(String, X ())] -> X ()
- class HasColorizer a where
  - defaultColorizer :: a -> Bool -> X (String, String)
- fromClassName :: Window -> Bool -> X (String, String)
- stringColorizer :: String -> Bool -> X (String, String)
- colorRangeFromClassName :: (Word8, Word8, Word8) -> (Word8, Word8, Word8) -> (Word8, Word8, Word8) -> (Word8, Word8, Word8) -> (Word8, Word8, Word8) -> Window -> Bool -> X (String, String)
- stringToRatio :: String -> Double
- data TwoD a b
- makeXEventhandler :: ((KeySym, String, KeyMask) -> TwoD a (Maybe a)) -> TwoD a (Maybe a)
- shadowWithKeymap :: Map (KeyMask, KeySym) a -> ((KeySym, String, KeyMask) -> a) -> (KeySym, String, KeyMask) -> a
- defaultNavigation :: TwoD a (Maybe a)
- substringSearch :: TwoD a (Maybe a) -> TwoD a (Maybe a)
- navNSearch :: TwoD a (Maybe a)
- setPos :: (Integer, Integer) -> TwoD a ()
- move :: (Integer, Integer) -> TwoD a ()
- moveNext :: TwoD a ()
- movePrev :: TwoD a ()
- select :: TwoD a (Maybe a)
- cancel :: TwoD a (Maybe a)
- transformSearchString :: (String -> String) -> TwoD a ()
- type Rearranger a = String -> [(String, a)] -> X [(String, a)]
- noRearranger :: Rearranger a
- searchStringRearrangerGenerator :: (String -> a) -> Rearranger a
- data TwoDState a

# Usage

You can use this module with the following in your `~/.xmonad/xmonad.hs`:

       import XMonad.Actions.GridSelect

Then add a keybinding, e.g.

       , ((modm, xK_g), goToSelected def)

This module also supports displaying arbitrary information in a grid and letting the user select from it. E.g. to spawn an application from a given list, you can use the following:

      , ((modm, xK_s), spawnSelected def ["xterm","gmplayer","gvim"])

## Customizing

### Using a common GSConfig

It is possible to bind a `gsconfig` at top-level in your configuration. Like so:

    -- the top of your config
    {-# LANGUAGE NoMonomorphismRestriction #-}
    import XMonad
    ...
    gsconfig1 = def { gs_cellheight = 30, gs_cellwidth = 100 }

An example where `buildDefaultGSConfig` is used instead of `def` in order to specify a custom colorizer is `gsconfig2` (found in XMonad.Actions.GridSelect):

    gsconfig2 colorizer = (buildDefaultGSConfig colorizer) { gs_cellheight = 30, gs_cellwidth = 100 }

    -- | A green monochrome colorizer based on window class
    greenColorizer = colorRangeFromClassName
                         black            -- lowest inactive bg
                         (0x70,0xFF,0x70) -- highest inactive bg
                         black            -- active bg
                         white            -- inactive fg
                         white            -- active fg
      where black = minBound
            white = maxBound

Then you can bind to:

        ,((modm, xK_g), goToSelected  $ gsconfig2 myWinColorizer)
        ,((modm, xK_p), spawnSelected $ spawnSelected defaultColorizer)

### Custom keybindings

You can build you own navigation mode and submodes by combining the exported action ingredients and assembling them using `makeXEventhandler` and `shadowWithKeymap`.

    myNavigation :: TwoD a (Maybe a)
    myNavigation = makeXEventhandler $ shadowWithKeymap navKeyMap navDefaultHandler
     where navKeyMap = M.fromList [
              ((0,xK_Escape), cancel)
             ,((0,xK_Return), select)
             ,((0,xK_slash) , substringSearch myNavigation)
             ,((0,xK_Left)  , move (-1,0)  >> myNavigation)
             ,((0,xK_h)     , move (-1,0)  >> myNavigation)
             ,((0,xK_Right) , move (1,0)   >> myNavigation)
             ,((0,xK_l)     , move (1,0)   >> myNavigation)
             ,((0,xK_Down)  , move (0,1)   >> myNavigation)
             ,((0,xK_j)     , move (0,1)   >> myNavigation)
             ,((0,xK_Up)    , move (0,-1)  >> myNavigation)
             ,((0,xK_y)     , move (-1,-1) >> myNavigation)
             ,((0,xK_i)     , move (1,-1)  >> myNavigation)
             ,((0,xK_n)     , move (-1,1)  >> myNavigation)
             ,((0,xK_m)     , move (1,-1)  >> myNavigation)
             ,((0,xK_space) , setPos (0,0) >> myNavigation)
             ]
           -- The navigation handler ignores unknown key symbols
           navDefaultHandler = const myNavigation

You can then define `gsconfig3` which may be used in exactly the same manner as `gsconfig1`:

    gsconfig3 = def
       { gs_cellheight = 30
       , gs_cellwidth = 100
       , gs_navigate = myNavigation
       }

# Configuration

data GSConfig a #

The `Default` instance gives a basic configuration for `gridselect`, with the colorizer chosen based on the type.

If you want to replace the `gs_colorizer` field, use `buildDefaultGSConfig` instead of `def` to avoid ambiguous type variables.

Constructors

GSConfig |
Fields gs_cellheight :: Integer gs_cellwidth :: Integer gs_cellpadding :: Integer gs_colorizer :: a -> Bool -> X (String, String) gs_font :: String gs_navigate :: TwoD a (Maybe a) gs_rearranger :: Rearranger a gs_originFractX :: Double gs_originFractY :: Double gs_bordercolor :: String

#### Instances

Instances details

HasColorizer a => Default (GSConfig a) # |
Instance details Defined in XMonad.Actions.GridSelect Methods def :: GSConfig a #

def :: Default a => a #

The default value for this type.

type TwoDPosition = (Integer, Integer) #

buildDefaultGSConfig :: (a -> Bool -> X (String, String)) -> GSConfig a #

Builds a default gs config from a colorizer function.

# Variations on `gridselect`

gridselect :: GSConfig a -> [(String, a)] -> X (Maybe a) #

Brings up a 2D grid of elements in the center of the screen, and one can select an element with cursors keys. The selected element is returned.

gridselectWindow :: GSConfig Window -> X (Maybe Window) #

Like `gridSelect` but with the current windows and their titles as elements

withSelectedWindow :: (Window -> X ()) -> GSConfig Window -> X () #

Brings up a 2D grid of windows in the center of the screen, and one can select a window with cursors keys. The selected window is then passed to a callback function.

bringSelected :: GSConfig Window -> X () #

Brings selected window to the current workspace.

goToSelected :: GSConfig Window -> X () #

Switches to selected window's workspace and focuses that window.

gridselectWorkspace :: GSConfig WorkspaceId -> (WorkspaceId -> WindowSet -> WindowSet) -> X () #

Select a workspace and view it using the given function (normally `view` or `greedyView`)

Another option is to shift the current window to the selected workspace:

    gridselectWorkspace (\ws -> W.greedyView ws . W.shift ws)

gridselectWorkspace' :: GSConfig WorkspaceId -> (WorkspaceId -> X ()) -> X () #

Select a workspace and run an arbitrary action on it.

spawnSelected :: GSConfig String -> [String] -> X () #

Select an application to spawn from a given list

runSelectedAction :: GSConfig (X ()) -> [(String, X ())] -> X () #

Select an action and run it in the X monad

# Colorizers

class HasColorizer a where #

That is `fromClassName` if you are selecting a `Window`, or `defaultColorizer` if you are selecting a `String`. The catch-all instance `HasColorizer a` uses the `focusedBorderColor` and `normalBorderColor` colors.

Methods

defaultColorizer :: a -> Bool -> X (String, String) #

#### Instances

Instances details

HasColorizer Window # |
Instance details Defined in XMonad.Actions.GridSelect Methods defaultColorizer :: Window -> Bool -> X (String, String) #
HasColorizer String # |
Instance details Defined in XMonad.Actions.GridSelect Methods defaultColorizer :: String -> Bool -> X (String, String) #
HasColorizer a # |
Instance details Defined in XMonad.Actions.GridSelect Methods defaultColorizer :: a -> Bool -> X (String, String) #

fromClassName :: Window -> Bool -> X (String, String) #

Colorize a window depending on it's className.

stringColorizer :: String -> Bool -> X (String, String) #

Default colorizer for Strings

colorRangeFromClassName #

Arguments

:: (Word8, Word8, Word8) | Beginning of the color range
-> (Word8, Word8, Word8) | End of the color range
-> (Word8, Word8, Word8) | Background of the active window
-> (Word8, Word8, Word8) | Inactive text color
-> (Word8, Word8, Word8) | Active text color
-> Window |
-> Bool |
-> X (String, String) |

A colorizer that picks a color inside a range, and depending on the window's class.

stringToRatio :: String -> Double #

Generates a Double from a string, trying to achieve a random distribution. We create a random seed from the hash of all characters in the string, and use it to generate a ratio between 0 and 1

# Navigation Mode assembly

data TwoD a b #

#### Instances

Instances details

Applicative (TwoD a) # |
Instance details Defined in XMonad.Actions.GridSelect Methods pure :: a0 -> TwoD a a0 # (<*>) :: TwoD a (a0 -> b) -> TwoD a a0 -> TwoD a b # liftA2 :: (a0 -> b -> c) -> TwoD a a0 -> TwoD a b -> TwoD a c # (*>) :: TwoD a a0 -> TwoD a b -> TwoD a b # (<*) :: TwoD a a0 -> TwoD a b -> TwoD a a0 #
Functor (TwoD a) # |
Instance details Defined in XMonad.Actions.GridSelect Methods fmap :: (a0 -> b) -> TwoD a a0 -> TwoD a b # (<$) :: a0 -> TwoD a b -> TwoD a a0 #
Monad (TwoD a) # |
Instance details Defined in XMonad.Actions.GridSelect Methods (>>=) :: TwoD a a0 -> (a0 -> TwoD a b) -> TwoD a b # (>>) :: TwoD a a0 -> TwoD a b -> TwoD a b return :: a0 -> TwoD a a0 #
MonadState (TwoDState a) (TwoD a) # |
Instance details Defined in XMonad.Actions.GridSelect Methods get :: TwoD a (TwoDState a) # put :: TwoDState a -> TwoD a () # state :: (TwoDState a -> (a0, TwoDState a)) -> TwoD a a0 #

makeXEventhandler :: ((KeySym, String, KeyMask) -> TwoD a (Maybe a)) -> TwoD a (Maybe a) #

Embeds a key handler into the X event handler that dispatches key events to the key handler, while non-key event go to the standard handler.

shadowWithKeymap :: Map (KeyMask, KeySym) a -> ((KeySym, String, KeyMask) -> a) -> (KeySym, String, KeyMask) -> a #

When the map contains (KeySym,KeyMask) tuple for the given event, the associated action in the map associated shadows the default key handler

# Built-in Navigation Mode

defaultNavigation :: TwoD a (Maybe a) #

By default gridselect used the defaultNavigation action, which binds left,right,up,down and vi-style h,l,j,k navigation. Return quits gridselect, returning the selected element, while Escape cancels the selection. Slash enters the substring search mode. In substring search mode, every string-associated keystroke is added to a search string, which narrows down the object selection. Substring search mode comes back to regular navigation via Return, while Escape cancels the search. If you want that navigation style, add `defaultNavigation` as `gs_navigate` to your `GSConfig` object. This is done by `buildDefaultGSConfig` automatically.

substringSearch :: TwoD a (Maybe a) -> TwoD a (Maybe a) #

Navigation submode used for substring search. It returns to the first argument navigation style when the user hits Return.

navNSearch :: TwoD a (Maybe a) #

This navigation style combines navigation and search into one mode at the cost of losing vi style navigation. With this style, there is no substring search submode, but every typed character is added to the substring search.

# Navigation Components

setPos :: (Integer, Integer) -> TwoD a () #

Sets the absolute position of the cursor.

move :: (Integer, Integer) -> TwoD a () #

Moves the cursor by the offsets specified

moveNext :: TwoD a () #

movePrev :: TwoD a () #

select :: TwoD a (Maybe a) #

Closes gridselect returning the element under the cursor

cancel :: TwoD a (Maybe a) #

Closes gridselect returning no element.

transformSearchString :: (String -> String) -> TwoD a () #

Apply a transformation function the current search string

# Rearrangers

Rearrangers allow for arbitrary post-filter rearranging of the grid elements.

For example, to be able to switch to a new dynamic workspace by typing in its name, you can use the following keybinding action:

    import XMonad.Actions.DynamicWorkspaces (addWorkspace)

    gridselectWorkspace' def
                             { gs_navigate   = navNSearch
                             , gs_rearranger = searchStringRearrangerGenerator id
                             }
                         addWorkspace

type Rearranger a = String -> [(String, a)] -> X [(String, a)] #

A function taking the search string and a list of elements, and returning a potentially rearranged list of elements.

noRearranger :: Rearranger a #

A rearranger that leaves the elements unmodified.

searchStringRearrangerGenerator :: (String -> a) -> Rearranger a #

A generator for rearrangers that append a single element based on the search string, if doing so would not be redundant (empty string or value already present).

# Screenshots

Selecting a workspace:

Selecting a window by title:

# Types

data TwoDState a #

#### Instances

Instances details

MonadState (TwoDState a) (TwoD a) # |
Instance details Defined in XMonad.Actions.GridSelect Methods get :: TwoD a (TwoDState a) # put :: TwoDState a -> TwoD a () # state :: (TwoDState a -> (a0, TwoDState a)) -> TwoD a a0 #