How to Customize Window Matching

Sometimes Docky does not properly match your windows to the launcher you expect. This is especially problematic for Java applications. As of revision 1217 in trunk, there is a method for overriding and manually specifying how Docky should match.

NOTE: there is a Java agent available which helps with matching Java applications.

This method makes use of the StartupWMClass attribute inside the launcher (.desktop files). When Docky sees this attribute, it will attempt to match against the window's WM_CLASS instead of using the normal matching algorithm.

Example

Since most Java applications have problems matching in Docky, we will use JabRef as an example. Here is the original launcher for JabRef (/usr/share/applications/jabref.desktop):

[Desktop Entry]
Name=JabRef
Comment=Graphical editor for BibTex bibliographies
Exec=jabref %f
Icon=/usr/share/pixmaps/jabref32.xpm
Terminal=false
Type=Application
Categories=Office;Database
MimeType=text/x-bibtex

The problem here is that the Exec attribute specifies 'jabref' which is a script that then calls 'java net.sf.jabref.JabRefMain'. When the JabRef main window pops up and Docky attempts to match it, all it sees is 'java net.sf.jabref.JabRefMain'. This string does not match the Exec attribute specified by that launcher and thus Docky can not match it.

Instead what we will do is get the WM_CLASS property from the window. We run this command from a terminal:

xprop | grep WM_CLASS | awk '{print $4}'

This gives us the output:

"net-sf-jabref-JabRefMain"

This is the WM_CLASS for the window. We use this string (unquoted) as the value for the StartupWMClass attribute in the launcher. So we add that attribute to the original launcher:

[Desktop Entry]
Name=JabRef
Comment=Graphical editor for BibTex bibliographies
Exec=jabref %f
Icon=/usr/share/pixmaps/jabref32.xpm
Terminal=false
Type=Application
Categories=Office;Database
MimeType=text/x-bibtex
StartupWMClass=net-sf-jabref-JabRefMain

Now we stop Docky. To be safe, we remove the file(s) ~/.cache/docky/docky.desktop.*.cache (which caches the launchers) and then restart Docky. Now JabRef matches as you would expect!