The icon themes have got a lot of rework for qooxdoo 0.6.5.

• Before 0.6.5 qooxdoo was pre-packaged with two icon themes from KDE: CrystalSVG and Nuvola. However, it was complicated to add new icon sets because the mapping of KDE icon names to qooxdoo icon names was not documented properly. Another issue was that Nuvola was only a subset of CrystalSVG. This meant that it was not always possible to switch between those two icon themes because of (potentially) missing icons in Nuvola.

• Both, Gnome and (hopefully) KDE will move to the new Freedesktop Icon Naming Specifications in the next releases of their desktops. For qooxdoo it was decided to meet the challenge of moving to the future (now de-facto) standard of icon naming.

• Due to the switch to a dual license, qooxdoo needed at least one icon theme with an LGPL/EPL compatible license. Unfortunately, both included icon sets were under LGPL only, and could not be re-licensed for LGPL/EPL (lacking the authors' consent).

• Is based on the de-facto (and future) standard icon naming theme as defined by freedesktop.org. To adhere to an (industry) standard naming scheme is advantegeous to a deliberate home-brewn solution. This decision would also support easy drop-in replacements by various external icon themes.
• Provides (at least) one EPL/LGPL compatible icon theme to make qooxdoo easily usable for EPL licensed projects.
• Defines a whitelist of icons which each qooxdoo theme must qualify for. This way it is possible to switch between icon themes easily at any time of development.
• Implements some powerful and convenient tools to integrate external KDE (and later Gnome) icon themes into qooxdoo without much manual labor.

Nuvola
Author: David Vignoni (david AT icon-king DOT com)
License: LGPL

nuoveXT
Author: Alexandre Moore (alexandre DOT moore AT gmail DOT com)
License: GPL & LGPL/EPL

Vista-Inspirate
Author: Alexandre Moore (alexandre DOT moore AT gmail DOT com)
License: GPL & LGPL/EPL

Crystal Clear
Author: Everaldo (everaldo AT everaldo DOT com)
License: LGPL

The migration from older versions of qooxdoo (0.6.4 and older) may be problematic because of the following reasons:

• Not all corrections to icon paths in existing applications can be done automatically using migration scripts. The migration scripts only handle hard-coded definitions well e.g. icon/16/tux.png. This affects for example loop structures where the icons are defined by a data structure. There are no warnings available for those icons, because there is no safe way to automatically determine code parts that use the old icon naming.
• Some icons may not have a representation in the new naming scheme. This is because qooxdoo has limited the whitelist to icons which are available in a broader range of the larger icon sets.

You are able to integrate complete icon themes or just a few separate icons. This can be done by simply copying them into the resource folder of the application (typically source/resource), e.g. into a folder anotherIconTheme.

To access your new icons you could use custom/anotherIconTheme/icon.png in our application code. Of course, you may put very large sets of icons into your resource icon folder, not only a few.

Sometimes it easier to just copy the few icons your application needs from an existing icon theme directly into the resource folder. For example you could structure your resource folder like this:

resource/core
resource/core/header.jpg
resource/toolbar/navi-back.png
resource/toolbar/navi-forward.png
resource/status/online.png
resource/status/offline.png

This should give you a first idea of how to work with custom icons. You can easily access such an icon with the following icon path: custom/core/header.jpg. This should be the same in both, source and build versions of the application.

Please note that with the current system it is not possible to actually theme your custom resources out of the box. Depending on your backend software you may prefer to solve this either in the backend or in your client-side application. For example you could switch the setting like this:

if (sometest())
{
  qx.Settings.setDefault("resourceUri", "./resource/theme1");
} else {
  qx.Settings.setDefault("resourceUri", "./resource/theme2");
}

As this is a setting it is also possible to switch this using the generator.py script. For a deeper understanding of this please refer to the documentation how to customize qooxdoo.