First of all, why am I reading this?

You probably pointed your browser to this page because you're somehow interested in knowing a bit more about icon themes from a developer point of view. You probably asked me something and I just pointed you to this page, if that's the case, I'm sorry to not explain things more personally, but I'm tired of explaining the same thing over and over again. You know, I don't like to repeat the same things around 20 times a day.

And why did you wrote this?

Are you really going to make me repeat it ? :)

Where should good behaving KDE 3rd party applications install their icons to?

The answer for KDE 3.0(.x) apps:
All the icons you want to use in your application _must_ be installed to the hicolor icon theme.

The answer for KDE 3.1 and newer:
All the icons you want to use in your application _must_ be installed to the hicolor icon theme.

So what's the difference between KDE 3.0, KDE 3.1 and KDE 3.2 ?

None, you always had to install your icons to hicolor and you'll always have to do so (probably until KDE 4.0 )

What if I'm developing using KDE 3.1 but I still want to support users of KDE 3.0?

Repeat with me : there's no change, hicolor has been, is, and will be the correct place to install your default icons

But what if I also want to install icons for other icon themes so that my app matches the different styles of the different icon themes?

Of course, you're free to do so, but note that you said "also" (ok, I've been putting words in your mouth, but that way it's easier for me to explain it :) ). The main point here is that you _must_ install icons to hicolor, and then you can _optionally_ install icons to other icon themes (kdeclassic, ikons, locolor, crystalsvg, etc.).

Also, you have to keep in mind that only hicolor is guaranteed to be installed always (with crystalsvg to be guaranteed to be installed on KDE 3.1 installations, nothing more, nothing less).

And what happens if I want to keep my app icons separate from the rest of standard icons?

You can put it in your app icon directory, that's on $(kde_datadir)/appname/icons/hicolor/ following the icon theme directory structure, e.g. $(kde_datadir)/appname/icons/hicolor/22x22/actions/mysuperaction.png

Then, what's all that noise about the hicolor/default/kdeclassic/crystalsvg icon themes?

KDE 3.0 installed a hicolor icon theme which contained all the standard icons of KDE and where apps installed their 3rd party icons.

With KDE 3.1, the default icon theme was changed to crystalsvg, so all the icons on KDE cvs changed to use the crystalsvg look where possible. As we want to keep backward compatibility with apps developed with KDE 3.0, then we used a simple technique of icon themes to make old apps continue working: inheritance. crystalsvg inherits from hicolor, so when an application tries to load an icon, the icon loader first looks tries to load it from the crystalsvg icon theme and if it can't be found, from hicolor.

To make life easier in the future in case we decide to change again the default icon theme (from crystalsvg to something else), we changed hicolor to be an empty ("holder") icon theme, which is there just to store 3rd party apps icons. That means that the user cannot select it anymore from the Control Center.

I liked the old icons! I want my old icons! Give me back my old icons!

Ok, ok, don't worry. "Your" old icons are still available at the kdeartwork module, and the theme is now called kdeclassic. So the inheritance graph is now :

kdeclassic -> crystalsvg -> hicolor

What happens with all the current users of hicolor?

There are no users of hicolor any longer. hicolor cannot be selected anymore from the Control Center so it's replaced with crystalsvga. If you want to use the old icons, install kdeclassic.

Wait, I looked at the index.desktop file of kdeclassic and it says "Inherit=default". Are you trying to fool me?

No, noone is trying to fool you, there's no secret conspiracy to make your icon theme stop working. The "default" icon theme in the Inherit config key is substituted with the default icon theme (crystalsvg).

Ok, I'm writing an icon theme, what icon theme should I inherit from?

You can inherit from the icon theme that you prefer, but note that this creates a dependency on that icon theme. So in most cases you only want to inherit from the "default" icon theme (which will be substituted to the correct value)

And what happens if I inherit explictly from crystalsvg ? Wouldn't that be better?

NO! Think what will happen with your icon theme once we change the default icon theme and crystalsvg is no longer available in every KDE system.

Then what happens with the tons of icon themes that currently inherit from hicolor?

That's ok because "Inherit=hicolor" is currently the same than "Inherit=default" so they're automatically "reparented" to inherit from the default icon theme whenever an icon theme inherits from hicolor.

Now either me or you are getting nuts, are you trying to say that the default icon theme is not the same than the "default" icon theme?

Exactly that . And yes, you are getting nuts (because I'm already, so I cannot be "getting" :) ).

The default icon theme is currently crystalsvg, and the "default" icon theme which only appears when inheriting is hicolor. Note the difference: the default icon theme is the one KIconTheme::defaultThemeName() is returning while the "default" icon theme is just a different name for "hicolor" (and more appropiate to the current use of it) given to it only when inheriting.

Note also that the default icon theme may change from release to release, but the "default" icon theme is always the same.

So there's no directory named "default" and no default/index.desktop file?

No there aren't. The name "default" is only given to hicolor in the "Inherit=default" line.

Ok, I think I understood everything, but why do KDE apps from KDE's cvs install their icons to crystalsvg instead of hicolor?

With apps from KDE's cvs we can play a little trick as we know which one is the "current" default icon theme in each KDE release, so we can install our icons to that icon theme instead of the hicolor icon theme. It provides a bit of speed as that way there's not a lookup to crystalsvg and then one to hicolor, because the icon is usually found more easily in crystalsvg. Also, it keeps icons in the correct place. On one hand it's illogical to distribute an empty apps directory in crystalsvg (I can see the dialogs . User: "What? there are no apps icons in crystalsvg ?" We: "Yes, there are, just that they're installed into hicolor"). On the other hand, the basic idea behind changing an icon theme would be broken. No icon should change its style inside an icon theme. But if KDE installs its icons to hicolor, then in a future release we may change the style of those icons if KDE chooses to change its look again which will be wrong ("Neutral style? then why does it change?").

But if I understood you correctly, KDE apps (let's say ... kit ;-) )must install their icons to hicolor and can install them to crystalsvg, isn't it?

NO. Perhaps there's something that wasn't clear. Let me explain it again. All icon themes inherit from the default icon theme (crystalsvg currently) not from hicolor, and only the default icon theme inherits from hicolor.

That means that only apps that want to have its icons in the correct place for every KDE release (3.0, 3.1, 3.2, etc.) have to install them to hicolor. But hey! all applications from outside of KDE's cvs want to do that!

But why can't I install the icons of my application (which is in my own cvs) to crystalsvg?

Do your homework.

Ok, it was very easy, I wonder why did you had to write this whole document instead of doing more productive things like programming some new and cool app or even fixing bugs somewhere else

That's what I wonder myself.

Perhaps it was because there were too many people asking you the same things and you got tired?

Yes. maybe.

So I have to install my icons to hicolor, isn't it?

Yes

But...

... please go to this page to read more about this.

If you have any other question, ask it to me (Antonio Larrosa).

Hope you have a good sense of humour, it definitely has saved my life more than once.

Antonio Larrosa Jiménez
larrosa@kde.org