| xmonad-contrib-0.8.1: Third party extensions for xmonad | Source code | Contents | Index

XMonad.Hooks.UrgencyHook

Portability | unportable
Stability | unstable
Maintainer | Devin Mullins <me@twifkak.com>

Contents

Usage
  Pop up a temporary dzen
  Highlight in existing dzen
  Useful keybinding
  Note
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 :: (LayoutClass l Window, UrgencyHook h) => h -> XConfig l -> XConfig (HandleEvent (WithUrgencyHook h) l)
withUrgencyHookC :: (LayoutClass l Window, UrgencyHook h) => h -> UrgencyConfig -> XConfig l -> XConfig (HandleEvent (WithUrgencyHook h) l)

data UrgencyConfig = UrgencyConfig {

suppressWhen :: SuppressWhen

}

urgencyConfig :: UrgencyConfig

data SuppressWhen

= Visible
| OnScreen
| Focused
| Never

focusUrgent :: X ()
dzenUrgencyHook :: DzenUrgencyHook

data DzenUrgencyHook = DzenUrgencyHook {

duration :: Int
args :: [String]

}

seconds :: Rational -> Int
data NoUrgencyHook = NoUrgencyHook
data FocusHook = FocusHook
readUrgents :: X [Window]
withUrgents :: ([Window] -> X a) -> X a
data StdoutUrgencyHook = StdoutUrgencyHook
newtype SpawnUrgencyHook = SpawnUrgencyHook String
class (Read h, Show h) => UrgencyHook h where

urgencyHook :: h -> 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"] }
                   $ defaultConfig

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
                   $ defaultConfig

Now, your XMonad.Hooks.DynamicLog must be set up to display the urgent windows. If you're using the dzen 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`.
Note
Note: UrgencyHook installs itself as a LayoutModifier, so if you modify your urgency hook and restart xmonad, you may need to rejigger your layout by hitting mod-shift-space.
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 :: (LayoutClass l Window, UrgencyHook h) => h -> XConfig l -> XConfig (HandleEvent (WithUrgencyHook h) l) | Source

This is the method to enable an urgency hook. It suppresses urgency status for windows that are currently visible. If you'd like to change that behavior, use `withUrgencyHookC`.

withUrgencyHookC :: (LayoutClass l Window, UrgencyHook h) => h -> UrgencyConfig -> XConfig l -> XConfig (HandleEvent (WithUrgencyHook h) l) | Source

If you'd like to configure *when* to trigger the urgency hook, call this function with a custom `UrgencyConfig`. Or, by example:

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

(Don't type the `...`, you dolt.) See documentation on your options at `SuppressWhen`.

data UrgencyConfig | Source

Global configuration, applicable to all types of `UrgencyHook`.
Constructors

UrgencyConfig |

suppressWhen :: SuppressWhen | see `SuppressWhen` for options

Instances

Read UrgencyConfig
Show UrgencyConfig

urgencyConfig :: UrgencyConfig | Source

The default `UrgencyConfig`. Use a variation of this in your config just as you use a variation of defaultConfig for your xmonad definition.

data SuppressWhen | Source

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

Read SuppressWhen
Show SuppressWhen

focusUrgent :: X () | Source

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

     , ((modMask              , xK_BackSpace), focusUrgent)

dzenUrgencyHook :: DzenUrgencyHook | Source

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 | Source

Your set of options for configuring a dzenUrgencyHook.
Constructors

DzenUrgencyHook |

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

Read DzenUrgencyHook
Show DzenUrgencyHook
UrgencyHook DzenUrgencyHook

seconds :: Rational -> Int | Source

Multiplies by ONE MILLION, for functions that take microseconds.

Use like:

     (5.5 `seconds`)

data NoUrgencyHook | Source

Constructors

NoUrgencyHook |

Instances

Read NoUrgencyHook
Show NoUrgencyHook
UrgencyHook NoUrgencyHook

data FocusHook | Source

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 { ...

Constructors

FocusHook |

Instances

Read FocusHook
Show FocusHook
UrgencyHook FocusHook

Stuff for developers:

readUrgents :: X [Window] | Source

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 | Source

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

data StdoutUrgencyHook | Source

For debugging purposes, really.
Constructors

StdoutUrgencyHook |

Instances

Read StdoutUrgencyHook
Show StdoutUrgencyHook
UrgencyHook StdoutUrgencyHook

newtype SpawnUrgencyHook | Source

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.
Constructors

SpawnUrgencyHook String |

Instances

Read SpawnUrgencyHook
Show SpawnUrgencyHook
UrgencyHook SpawnUrgencyHook

class (Read h, Show h) => UrgencyHook h where | Source

The class definition, and some pre-defined instances.
Methods

urgencyHook :: h -> Window -> X () | Source

Instances

UrgencyHook StdoutUrgencyHook
UrgencyHook SpawnUrgencyHook
UrgencyHook FocusHook
UrgencyHook DzenUrgencyHook
UrgencyHook NoUrgencyHook

Produced by Haddock version 2.4.2