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

Copyright | Devin Mullins <me@twifkak.com>
License | BSD3-style (see LICENSE)
Maintainer | Devin Mullins <me@twifkak.com>
Stability | unstable
Portability | unportable
Safe Haskell | None
Language | Haskell2010

XMonad.Hooks.UrgencyHook

Contents

- Usage
  - Pop up a temporary dzen
  - Highlight in existing dzen
  - Useful keybinding
- Troubleshooting
- Example: Setting up irssi + rxvt-unicode
  - Configuring irssi
  - Configuring screen
  - Configuring rxvt-unicode
  - Configuring xmonad
- Stuff for your config file:
- Stuff for developers:

Description

UrgencyHook lets you configure an action to occur when a window demands your attention. (In traditional WMs, this takes the form of "flashing" on your "taskbar." Blech.)

Synopsis

- withUrgencyHook :: forall (l :: Type -> Type) h. (LayoutClass l Window, UrgencyHook h) => h -> XConfig l -> XConfig l
- withUrgencyHookC :: forall (l :: Type -> Type) h. (LayoutClass l Window, UrgencyHook h) => h -> UrgencyConfig -> XConfig l -> XConfig l
- data UrgencyConfig = UrgencyConfig {
  - suppressWhen :: SuppressWhen
  - remindWhen :: RemindWhen
  }
- urgencyConfig :: UrgencyConfig
- data SuppressWhen
  - = Visible
  - | OnScreen
  - | Focused
  - | Never
- data RemindWhen
  - = Dont
  - | Repeatedly Int Interval
  - | Every Interval
- focusUrgent :: X ()
- clearUrgents :: X ()
- dzenUrgencyHook :: DzenUrgencyHook
- data DzenUrgencyHook = DzenUrgencyHook {
  - duration :: Int
  - args :: [String]
  }
- data NoUrgencyHook = NoUrgencyHook
- newtype BorderUrgencyHook = BorderUrgencyHook {
  - urgencyBorderColor :: String
  }
- data FocusHook = FocusHook
- filterUrgencyHook :: [WorkspaceId] -> Window -> X ()
- filterUrgencyHook' :: Query Bool -> Window -> X ()
- minutes :: Rational -> Rational
- seconds :: Rational -> Int
- askUrgent :: Window -> X ()
- doAskUrgent :: ManageHook
- readUrgents :: X [Window]
- withUrgents :: ([Window] -> X a) -> X a
- clearUrgents' :: [Window] -> X ()
- data StdoutUrgencyHook = StdoutUrgencyHook
- newtype SpawnUrgencyHook = SpawnUrgencyHook String
- class UrgencyHook h where
  - urgencyHook :: h -> Window -> X ()
- type Interval = Rational
- borderUrgencyHook :: String -> Window -> X ()
- focusHook :: Window -> X ()
- spawnUrgencyHook :: String -> Window -> X ()
- stdoutUrgencyHook :: Window -> X ()

# Usage

To wire this up, first add:

    import XMonad.Hooks.UrgencyHook

to your import list in your config file. Now, you have a decision to make: When a window deems itself urgent, do you want to pop up a temporary dzen bar telling you so, or do you have an existing dzen wherein you would like to highlight urgent workspaces?

## Pop up a temporary dzen

Enable your urgency hook by wrapping your config record in a call to `withUrgencyHook`. For example:

    main = xmonad $ withUrgencyHook dzenUrgencyHook { args = ["-bg", "darkgreen", "-xs", "1"] }
                  $ def

This will pop up a dzen bar for five seconds telling you you've got an urgent window.

## Highlight in existing dzen

In order for xmonad to track urgent windows, you must install an urgency hook. You can use the above `dzenUrgencyHook`, or if you're not interested in the extra popup, install NoUrgencyHook, as so:

    main = xmonad $ withUrgencyHook NoUrgencyHook
                  $ def

Now, your XMonad.Hooks.StatusBar.PP must be set up to display the urgent windows. If you're using the `dzen` (from XMonad.Hooks.DynamicLog) or `dzenPP` functions from that module, then you should be good. Otherwise, you want to figure out how to set `ppUrgent`.

## Useful keybinding

You can set up a keybinding to jump to the window that was recently marked urgent. See an example at `focusUrgent`.

# Troubleshooting

There are three steps to get right:

1. The X client must set the UrgencyHint flag. How to configure this depends on the application. If you're using a terminal app, this is in two parts:

   - The console app must send a ^G (bell). In bash, a helpful trick is `sleep 1; echo -e '\a'`.
   - The terminal must convert the bell into UrgencyHint.
2. XMonad must be configured to notice UrgencyHints. If you've added withUrgencyHook, you may need to hit mod-shift-space to reset the layout.
3. The dzen must run when told. Run `dzen2 -help` and make sure that it supports all of the arguments you told DzenUrgencyHook to pass it. Also, set up a keybinding to the `dzen` action in XMonad.Util.Dzen to test if that works.

As best you can, try to isolate which one(s) of those is failing.

# Example: Setting up irssi + rxvt-unicode

This is a commonly asked example. By default, the window doesn't get flagged urgent when somebody messages you in irssi. You will have to configure some things. If you're using different tools than this, your mileage will almost certainly vary. (For example, in Xchat2, it's just a simple checkbox.)

## Configuring irssi

`Irssi` is not an X11 app, so it can't set the `UrgencyHint` flag on `XWMHints`. However, on all console applications is bestown the greatest of all notification systems: the bell. That's right, Ctrl+G, ASCII code 7, `echo -e 'a'`, your friend, the bell. To configure `irssi` to send a bell when you receive a message:

    /set beep_msg_level MSGS NOTICES INVITES DCC DCCMSGS HILIGHT

Consult your local `irssi` documentation for more detail.

## Configuring screen

A common way to run `irssi` is within the lovable giant, `screen`. Some distros (e.g. Ubuntu) like to configure `screen` to trample on your poor console applications -- in particular, to turn bell characters into evil, smelly "visual bells." To turn this off, add:

    vbell off # or remove the existing 'vbell on' line

to your .screenrc, or hit `C-a C-g` within a running `screen` session for an immediate but temporary fix.

## Configuring rxvt-unicode

Rubber, meet road. Urxvt is the gateway between console apps and X11. To tell urxvt to set an `UrgencyHint` when it receives a bell character, first, have an urxvt version 8.3 or newer, and second, set the following in your `.Xdefaults`:

    urxvt.urgentOnBell: true

Depending on your setup, you may need to `xrdb` that.

## Configuring xmonad

Hopefully you already read the section on how to configure xmonad. If not, hopefully you know where to find it.

# Stuff for your config file:

withUrgencyHook :: forall (l :: Type -> Type) h. (LayoutClass l Window, UrgencyHook h) => h -> XConfig l -> XConfig l #

This is the method to enable an urgency hook. It uses the default `urgencyConfig` to control behavior. To change this, use `withUrgencyHookC` instead.

withUrgencyHookC :: forall (l :: Type -> Type) h. (LayoutClass l Window, UrgencyHook h) => h -> UrgencyConfig -> XConfig l -> XConfig l #

This lets you modify the defaults set in `urgencyConfig`. An example:

    withUrgencyHookC dzenUrgencyHook { ... } def { suppressWhen = Focused }

(Don't type the `...`, you dolt.) See `UrgencyConfig` for details on configuration.

data UrgencyConfig #

Global configuration, applied to all types of `UrgencyHook`. See `urgencyConfig` for the defaults.

Constructors

UrgencyConfig |

Fields

- suppressWhen :: SuppressWhen

  when to trigger the urgency hook

- remindWhen :: RemindWhen

  when to re-trigger the urgency hook

#### Instances

Instances details

Read UrgencyConfig # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods readsPrec :: Int -> ReadS UrgencyConfig # readList :: ReadS [UrgencyConfig] # readPrec :: ReadPrec UrgencyConfig # readListPrec :: ReadPrec [UrgencyConfig] #
Show UrgencyConfig # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods showsPrec :: Int -> UrgencyConfig -> ShowS # show :: UrgencyConfig -> String # showList :: [UrgencyConfig] -> ShowS #
Default UrgencyConfig # | The default `UrgencyConfig`: `suppressWhen = `Visible`, remindWhen = `Dont``. Use a variation of this in your config just as you would use any other instance of `def`.
Instance details Defined in XMonad.Hooks.UrgencyHook Methods def :: UrgencyConfig #

urgencyConfig :: UrgencyConfig #

Deprecated: Use def insetad.

The default `UrgencyConfig`: `urgencyConfig = `def``.

data SuppressWhen #

A set of choices as to when you should (or rather, shouldn't) be notified of an urgent window. The default is `Visible`. Prefix each of the following with "don't bug me when":

Constructors

Visible | the window is currently visible
OnScreen | the window is on the currently focused physical screen
Focused | the window is currently focused
Never | ... aww, heck, go ahead and bug me, just in case.

#### Instances

Instances details

Read SuppressWhen # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods readsPrec :: Int -> ReadS SuppressWhen # readList :: ReadS [SuppressWhen] # readPrec :: ReadPrec SuppressWhen # readListPrec :: ReadPrec [SuppressWhen] #
Show SuppressWhen # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods showsPrec :: Int -> SuppressWhen -> ShowS # show :: SuppressWhen -> String # showList :: [SuppressWhen] -> ShowS #

data RemindWhen #

A set of choices as to when you want to be re-notified of an urgent window. Perhaps you focused on something and you miss the dzen popup bar. Or you're AFK. Or you feel the need to be more distracted. I don't care.

The interval arguments are in seconds. See the `minutes` helper.

Constructors

Dont | triggering once is enough
Repeatedly Int Interval | repeat <arg1> times every <arg2> seconds
Every Interval | repeat every <arg1> until the urgency hint is cleared

#### Instances

Instances details

Read RemindWhen # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods readsPrec :: Int -> ReadS RemindWhen # readList :: ReadS [RemindWhen] # readPrec :: ReadPrec RemindWhen # readListPrec :: ReadPrec [RemindWhen] #
Show RemindWhen # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods showsPrec :: Int -> RemindWhen -> ShowS # show :: RemindWhen -> String # showList :: [RemindWhen] -> ShowS #

focusUrgent :: X () #

Focuses the most recently urgent window. Good for what ails ya -- I mean, your keybindings. Example keybinding:

    , ((modm              , xK_BackSpace), focusUrgent)

clearUrgents :: X () #

Just makes the urgents go away. Example keybinding:

    , ((modm .|. shiftMask, xK_BackSpace), clearUrgents)

dzenUrgencyHook :: DzenUrgencyHook #

Flashes when a window requests your attention and you can't see it. Defaults to a duration of five seconds, and no extra args to dzen. See `DzenUrgencyHook`.

data DzenUrgencyHook #

Your set of options for configuring a dzenUrgencyHook.

Constructors

DzenUrgencyHook |

Fields

- duration :: Int

  number of microseconds to display the dzen (hence, you'll probably want to use `seconds`)

- args :: [String]

  list of extra args (as `String`s) to pass to dzen

#### Instances

Instances details

Read DzenUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods readsPrec :: Int -> ReadS DzenUrgencyHook # readList :: ReadS [DzenUrgencyHook] # readPrec :: ReadPrec DzenUrgencyHook # readListPrec :: ReadPrec [DzenUrgencyHook] #
Show DzenUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods showsPrec :: Int -> DzenUrgencyHook -> ShowS # show :: DzenUrgencyHook -> String # showList :: [DzenUrgencyHook] -> ShowS #
Default DzenUrgencyHook # | ``def` = `dzenUrgencyHook``.
Instance details Defined in XMonad.Hooks.UrgencyHook Methods def :: DzenUrgencyHook #
UrgencyHook DzenUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods urgencyHook :: DzenUrgencyHook -> Window -> X () #

data NoUrgencyHook #

Constructors

NoUrgencyHook |

#### Instances

Instances details

Read NoUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods readsPrec :: Int -> ReadS NoUrgencyHook # readList :: ReadS [NoUrgencyHook] # readPrec :: ReadPrec NoUrgencyHook # readListPrec :: ReadPrec [NoUrgencyHook] #
Show NoUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods showsPrec :: Int -> NoUrgencyHook -> ShowS # show :: NoUrgencyHook -> String # showList :: [NoUrgencyHook] -> ShowS #
UrgencyHook NoUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods urgencyHook :: NoUrgencyHook -> Window -> X () #

newtype BorderUrgencyHook #

Constructors

BorderUrgencyHook |

Fields

- urgencyBorderColor :: String

#### Instances

Instances details

Read BorderUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods readsPrec :: Int -> ReadS BorderUrgencyHook # readList :: ReadS [BorderUrgencyHook] # readPrec :: ReadPrec BorderUrgencyHook # readListPrec :: ReadPrec [BorderUrgencyHook] #
Show BorderUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods showsPrec :: Int -> BorderUrgencyHook -> ShowS # show :: BorderUrgencyHook -> String # showList :: [BorderUrgencyHook] -> ShowS #
UrgencyHook BorderUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods urgencyHook :: BorderUrgencyHook -> Window -> X () #

data FocusHook #

Constructors

FocusHook |

#### Instances

Instances details

Read FocusHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods readsPrec :: Int -> ReadS FocusHook # readList :: ReadS [FocusHook] # readPrec :: ReadPrec FocusHook # readListPrec :: ReadPrec [FocusHook] #
Show FocusHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods showsPrec :: Int -> FocusHook -> ShowS # show :: FocusHook -> String # showList :: [FocusHook] -> ShowS #
UrgencyHook FocusHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods urgencyHook :: FocusHook -> Window -> X () #

filterUrgencyHook :: [WorkspaceId] -> Window -> X () #

urgencyhook such that windows on certain workspaces never get urgency set.

Useful for scratchpad workspaces perhaps:

    main = xmonad (withUrgencyHook (filterUrgencyHook ["NSP", "SP"]) def)

filterUrgencyHook' :: Query Bool -> Window -> X () #

`filterUrgencyHook` that takes a generic `Query` to select which windows should never be marked urgent.

minutes :: Rational -> Rational #

A prettified way of multiplying by 60. Use like: `(5 `minutes`)`.

seconds :: Rational -> Int #

Multiplies by ONE MILLION, for functions that take microseconds.

Use like:

    (5.5 `seconds`)

In GHC 7 and later, you must either enable the PostfixOperators extension (by adding

    {-# LANGUAGE PostfixOperators #-}

to the top of your file) or use seconds in prefix form:

    seconds 5.5

askUrgent :: Window -> X () #

Mark the given window urgent.

(The implementation is a bit hacky: send a _NET_WM_STATE ClientMessage to ourselves. This is so that we respect the `SuppressWhen` of the configured urgency hooks. If this module if ever migrated to the ExtensibleConf infrastrcture, we'll then invoke markUrgent directly.)

doAskUrgent :: ManageHook #

Helper for `ManageHook` that marks the window as urgent (unless suppressed, see `SuppressWhen`). Useful in `setEwmhActivateHook` and also in combination with XMonad.Hooks.InsertPosition, XMonad.Hooks.Focus.

# Stuff for developers:

readUrgents :: X [Window] #

X action that returns a list of currently urgent windows. You might use it, or `withUrgents`, in your custom logHook, to display the workspaces that contain urgent windows.

withUrgents :: ([Window] -> X a) -> X a #

An HOF version of `readUrgents`, for those who prefer that sort of thing.

clearUrgents' :: [Window] -> X () #

Clear urgency status of selected windows.

data StdoutUrgencyHook #

Constructors

StdoutUrgencyHook |

#### Instances

Instances details

Read StdoutUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods readsPrec :: Int -> ReadS StdoutUrgencyHook # readList :: ReadS [StdoutUrgencyHook] # readPrec :: ReadPrec StdoutUrgencyHook # readListPrec :: ReadPrec [StdoutUrgencyHook] #
Show StdoutUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods showsPrec :: Int -> StdoutUrgencyHook -> ShowS # show :: StdoutUrgencyHook -> String # showList :: [StdoutUrgencyHook] -> ShowS #
UrgencyHook StdoutUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods urgencyHook :: StdoutUrgencyHook -> Window -> X () #

newtype SpawnUrgencyHook #

Constructors

SpawnUrgencyHook String |

#### Instances

Instances details

Read SpawnUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods readsPrec :: Int -> ReadS SpawnUrgencyHook # readList :: ReadS [SpawnUrgencyHook] # readPrec :: ReadPrec SpawnUrgencyHook # readListPrec :: ReadPrec [SpawnUrgencyHook] #
Show SpawnUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods showsPrec :: Int -> SpawnUrgencyHook -> ShowS # show :: SpawnUrgencyHook -> String # showList :: [SpawnUrgencyHook] -> ShowS #
UrgencyHook SpawnUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods urgencyHook :: SpawnUrgencyHook -> Window -> X () #

class UrgencyHook h where #

The class definition, and some pre-defined instances.

Methods

urgencyHook :: h -> Window -> X () #

#### Instances

Instances details

UrgencyHook BorderUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods urgencyHook :: BorderUrgencyHook -> Window -> X () #
UrgencyHook DzenUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods urgencyHook :: DzenUrgencyHook -> Window -> X () #
UrgencyHook FocusHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods urgencyHook :: FocusHook -> Window -> X () #
UrgencyHook NoUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods urgencyHook :: NoUrgencyHook -> Window -> X () #
UrgencyHook SpawnUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods urgencyHook :: SpawnUrgencyHook -> Window -> X () #
UrgencyHook StdoutUrgencyHook # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods urgencyHook :: StdoutUrgencyHook -> Window -> X () #
UrgencyHook (Window -> X ()) # |
Instance details Defined in XMonad.Hooks.UrgencyHook Methods urgencyHook :: (Window -> X ()) -> Window -> X () #

type Interval = Rational #

borderUrgencyHook :: String -> Window -> X () #

A hook that sets the border color of an urgent window. The color will remain until the next time the window gains or loses focus, at which point the standard border color from the XConfig will be applied. You may want to use suppressWhen = Never with this:

    withUrgencyHookC BorderUrgencyHook { urgencyBorderColor = "#ff0000" } urgencyConfig { suppressWhen = Never } ...

(This should be `urgentBorderColor` but that breaks XMonad.Layout.Decoration. `borderColor` breaks anyone using `XPConfig` from XMonad.Prompt. We need to think a bit more about namespacing issues, maybe.)

focusHook :: Window -> X () #

A hook which will automatically send you to anything which sets the urgent flag (as opposed to printing some sort of message. You would use this as usual, eg.

    withUrgencyHook FocusHook $ myconfig { ...

spawnUrgencyHook :: String -> Window -> X () #

Spawn a commandline thing, appending the window id to the prefix string you provide. (Make sure to add a space if you need it.) Do your crazy xcompmgr thing.

stdoutUrgencyHook :: Window -> X () #

For debugging purposes, really.