Pimp Your XMonad #4: Urgency Hooks

In a traditional desktop environment such as Gnome or KDE, one has a Windows-style taskbar and tray, with small icons for various apps. When an app wants your attention, it generally changes its tray icon, and might highlight or flash the taskbar entry. In a pure xmonad setup, one typically has neither a taskbar nor a tray, so how do you know when someone addresses you on IRC, or sends a Pidgin message?

Xmonad offers a solution, the XMonad.Hooks.UrgencyHook module. This module offers a variety of ways for xmonad to notify you that an app is requesting your attention, and some ways for you to respond.

XMonad Setup
When an app sets the X WM_URGENT option (see below on how to configure this in some common apps), UrgencyHook will notify you. Precisely how it does so is up to you. One uncommon choice is popping up a temporary dzen2 window, which I won’t be covering here (see the XMonad.Hooks.UrgencyHook docs). By far the most common technique is highlighting the workspace in your dzen or xmobar workspace list.

To start, import XMonad.Hooks.UrgencyHook. Then your xmonad defaultConfig { ... } line changes to: xmonad $ withUrgencyHook NoUrgencyHook defaultConfig { ... }. If you run the darcs version of xmonad and use the dzen function or dzenPP for your logHook you’re all set! Both of those functions set up dzen to show urgency by highlighting the workspace with the urgent window.

If you use the xmobar or xmobarPP functions, or want custom colours for your dzen, a little more work is required. You probably have a logHook defined, and it probably uses xmobarPP or dzenPP. If not, see the documentation for XMonad.Hooks.DynamicLog, that’s outside of the scope of this article.

You’ll have to add the field ppUrgent = xmobarColor "yellow" "red" . xmobarStrip to your xmobarPP for xmobar, or ppUrgent = dzenColor "yellow" "red" . dzenStrip for dzen. Of course, you can choose whatever colours you like.

N.B. The dzenStrip and xmobarStrip functions only exist in darcs. If you don’t run darcs xmonad, you can get the code from here and paste it into your xmonad.hs.

A Handy Keybinding: focusUrgent
XMonad.Hooks.UrgencyHook contains a useful keybinding function, focusUrgent, which takes no arguments and focuses the most recently urgent window.

Configuring Pidgin
The second part of setting up UrgencyHook is configuring apps to set WM_URGENT. To do this for Pidgin, you need to enable the Message Notificaton plugin (included with Pidgin), and in the plugin configuration tick the “Set window manager ‘URGENT’ hint” option.

Configuring urxvt
Another common thing to want highlighting for is when someone uses your name in IRC. To make urxvt set urgent on a bell, add the line URxvt.urgentOnBell: true to your ~/.Xdefaults.

Of course, you’ll also have to set your IRC client to trigger a bell on highlight (in irssi: /set bell_beeps ON and /set beep_msg_level MSGS NOTICES DCC DCCMSGS HILIGHT). If you run it in screen, make sure screen isn’t set to use visual bell either.

The XMonad.Hooks.UrgencyHook docs also have information on setting up these apps and others. If you use a different terminal or IRC client, Google knows how to set it up for urgency hints.

UrgencyHook in Action
Here’s a screenshot of me hard at work on xmonad, with UrgencyHook notifying me that I’ve received a Pidgin message on workspace 2: IM.

P.S. Twitter
I’m now on Twitter as bradenshep.


11 Responses to Pimp Your XMonad #4: Urgency Hooks

  1. redline6561 says:

    Thanks. I’d been putting off doing this in my config.

  2. 1. BTW, I don’t have a statusbar, so I go the uncommon route of popping up a temporary dzen. :)

    2. focusUrgent doesn’t just go to the last urgent; it pops the stack (or dequeues the queue, I forget).

    3. At work, I have taken use of this extension to an extreme level. My PS1 includes a bell, any time I have a bash script that calls `read`, I echo a bell, and my .vimrc includes “norm \” and “au WinEnter * norm \” which will echo a bell. Pretty much any time something is asking for input on another workspace, I get notified. (I’d love to do this at the pty level instead of app-specific hacks, but I don’t [yet] know enough about how/if that’s possible.)

  3. frosch03 says:

    Thx :) That was missing in my xmonad.hs for a longe time :)

    Btw, if you want your xterm to set the urgent-flag on a bell-event add the following to your .Xresources

    XTerm*bellIsUrgent: true

    And don’t forget `xrdb -merge .Xresources` to merge the changes :)

  4. […] is off the ground by then. Also, if you use Xmonad there’s a good guide to Urgency Hooks here. Open Source development is still being thoughtfully explored. See, The Free as in Beer Economy and […]

  5. Jon says:

    Sorry for the late reply, it took me a while to get urgency hooks working (actually they wouldn’t work at all in dzen2, so I had to try xmobar instead).

    Anyway, my question is what other apps will send urgency bells besides pidgin? Pine seems to do so, and will be replacing my thunderbird shortly. What else should I be using to take advantage of urgency hooks?

  6. bradenshep says:


    #xmonad can help you with dzen not working, if you’d prefer to go back to it.

    As to which apps will set urgency, I don’t know of any off the top of my head. On some level any apps that might need to notify you should do it, but most don’t or don’t make the option easy to find. (Really, Pidgin’s isn’t easy to find, it’s just such a widely used app that it was easy to find on Google.) There may be extensions for Thunderbird that do that, I don’t know.

    Console apps, though, are another story. Lots of them use the system bell as a notification by default or have obvious options to do so. Then you can simply set up your terminal as above. That allows pine, mutt, anything to trigger urgency.

    When I’m running a long compile job or other process on some workspace, and don’t want to forget about it, I use
    compile command; echo -e “\a”, which turns on escape character interpretation in echo, and echoes a bell character, triggering the urgency hints.

  7. IIRC, XChat has an urgency option that’s pretty easy to find. (I think it says something about flashing the taskbar.) That option is actually what started my desire for urgency in xmonad.

    Braden – at work, I take it further – I put \a in my $PS1. If *any* command finishes off-screen, I know about it. I also put “au * BufRead norm \” in my .vimrc so I can go elsewhere while waiting for vim to load a file from a slow NFS mount, or while waiting for our slow-ass VCS to pop up $EDITOR.

  8. bradenshep says:

    Creative, I may do that. I forget about offscreen commands all the time and end up thinking “What was I waiting for again?”

  9. scottkidder says:

    I have an alias for the bell, bp=’echo -e “\a”‘
    So I can run about anything, eg. pacman -Syu && bp and get notified when it’s done.

  10. ben says:

    Screenshot is 404’d.

  11. jayjay says:

    this is my main loop. i get errors when i try to change it to a similar loop like the one in this article. I want to add the withUrgencyHook NoUrgencyHook into my loop. does anyone have any ideas?

    main = xmonad=<< statusBar myBar myPP toggleStrutsKey myConfig
    — removed stuff from here

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: