PyGTK Application Icon Blurred in Unity

What's going on

The <property name="icon"> settings refers to the window icon, not the application icon. As I understand it, the Ubuntu windowing server (X.org) squashes these to a tiny size after loading. If you don't recall from year 2009, they used to be used in this capacity:

Using application icons instead

Ubuntu Unity will use this low-res format if needed. However it usually fetches application icons according to the Icon= value of a given window's application launcher, called a "desktop entry".

If you're a normal application developer who just plans to publish their program with the App Developer Portal, you can probably stop reading here. The free packaging service will handle writing your app's desktop entry and placing its installed icons in the right part of the filesystem. If not...

The nitty gritty

How to create a desktop entry and get Ubuntu to match your PyGTK window to the correct application icon and name is already documented in this question. But where do you actually place icons to get the right one displayed?

As it happens, the answer is fairly arcane. Per freedesktop.org specifications, icons are searched for and loaded by size, icon theme, and (when necessary) localization. Icons can even be installed in several difference prefixes depending on the source that installed them. Ubuntu "queries" icons by context.

The simple rules: use a unique icon name for your application to prevent false matches with other icons. Place the icon(s) for your application in one of the following directory (or a subdirectory thereof):

<user prefix>/share/icons/<icon width>x<icon height>/apps/
<user prefix>/share/icons/scalable/apps/

<user_prefix> is your application's install path (it will be /usr for packages installed by the package manager, /usr/local/ for other software installed for all users, and $HOME/.local for single-user installations). <icon width> and <icon height> (or 'scalable' for SVGs) refer to the dimensions of the icon. If you create many different icon resolutions, Ubuntu will always find and select the right one for any context.

Getting the right app icon to display while developing

1. Create a scalable or high-resolution icon and place it in the correct subdirectory of your user home's share/ directory. For example, myapp.svg would go in $HOME/.local/share/icons/scalable/

2. Write a desktop entry that includes the non-extensioned name of your icon. For example

   [Desktop Entry]
   
   Name=My Application
   Exec=my_binary
   Icon=myapp
   

   Place this in $HOME/.local/share/applications/. Note that my_binary must be an executable searchable in one of your $PATH directories.

3. Run your application either (a) from the Unity Dash, (b) from the command line using the exact name of your $PATH executable [eg 'my_binary'].

If that all reads like gibberish...

Open your file browser and explore the directories /usr/share/applications/ and /usr/share/icons/. Look around and you'll catch on to how application metadata and icons work in Ubuntu.