How Can I Give My Eclipse Blob An Icon In The Flippin’ About Dialog?

Posted by pookzilla on January 18, 2006

I recently set out to do what I thought should be very simple : add a new iconified button to the bottom of the Help -> About dialog using the same process that is used to add the currently existing Eclipse button. Because I work in and own a section of the code that pulls this information from Core/OSGi/Update I figured that I’d have no problem doing this seemingly trivial task. Not quite.

First, I’ll explain how we pull the info out of core. When I’ve explained this I will move onto how you package this information such that core can read it. When the About dialog is opened we query core for a list of IBundleGroupProviders. In Eclipse there is only the one IBundleGroupProvider provided by the runtime. From this provider we collect a list of all available IBundleGroup objects. An IBundleGroup is essentially a collection of OSGI bundles as well as some metadata relating to the collection that is represented by key-value pairs. When it comes time to create the buttons we iterate over this list and collect the IBundleGroup.getProviderName() and the icon represented by the property returned from IBundleGroup.getProperty() when it is passed IBundleGroupConstants.FEATURE_IMAGE as the key. For every unique provider/image pair we create a button. In the case of the Eclipse SDK, there are many bundle groups but each has a provider of “Eclipse.org” and each shares the same 32×32 gif icon. As a result only one button is drawn.

Okay, so that’s the nitty gritty of the process from our end but what the heck does all that mean for you as a plug-in developer? It means that if you want an icon representing your plug-in or group of plug-ins to show up in this dialog you’re going to need to provide a bundle group. As it happens, you can do this by associating your plug-in to a Feature. Bundle groups have a one to one relationship with features so your first step is to create a feature to encapsulate your plug-ins. I wont elaborate on this point because an excellent article, “How To Keep Up To Date”, has been written by Dejan Glozic and Dorian Birsan that describes the process. I suggest you follow this tutorial to get yourself into a state where you have a feature to play with.

Once you have your feature you’re almost there. SO CLOSE! SO PAINFULLY CLOSE! A feature is well and good on its own as a grouping of functionality that can be used to distribute and manage plug-ins but it can be also used for branding Eclipse in various ways. If you open your feature.xml file and go to the Overview page you’ll note a field for Branding Plug-In. By themselves features offer no ability to brand eclipse. It is by associating them with a Branding Plug-In that you have the ability to tweak Eclipse’s appearance. Point your feature.xml at a plug-in that you designate to be your branding plug-in. It can be any plug-in that is contained within the feature, including those that offer your plug-in functionality, but some people choose to create a specific plug-in for this purpose for the sake of clarity. Note that as a shortcut you can omit the pointer in your feature.xml to a branding plug-in by providing a plug-in in your feature that has the same id as the feature itself. In this case the plug-in will implicitly be the branding plug-in.

Now that you’ve designated a plug-in to be the branding plug-in for your feature it’s time to add some branding. This is accomplished by adding an about.ini file to your branding plug-in. In the about.ini you can specify the various branding characteristics for your feature. The about.ini format is the typical key=value format that you should be used to already and the key we’re interested in today is featureImage. This key should point at a value that is a relative path to a 32×32 icon that represents your feature. For instance:

featureImage=OMGIGotItToWork.jpg

Provided you’ve crossed all of your t’s and dotted your i’s you should now see a new icon in your About dialog after deploying your feature and plug-ins. Isn’t that exciting?!

In the process of writing this I discovered an excellent article regarding features written by Pat McCarthy over on IBM Developer works entitled “Put Eclipse Features To Work For You”. If you follow this article you’ll be shown how to do what I’ve described above in addition to other types of feature-related branding. I’ve decided to post this entry despite the existence of this excellent article because I found the process quite unintuitive. Although I had a very clear idea of what I wanted to do I couldn’t articulate the idea in terms of feature, branding plug-ins, and about.ini files at the onset.

In summary:

1. create a feature that contains the plug-ins you wish to brand
2. declare one of them the branding plug-in or create a new one to fill that role
3. create an about.ini file in your branding plug-in that points to the image you wish to use
4. profit!