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

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!
This entry was posted in Eclipse. Bookmark the permalink. Follow any comments here with the RSS feed for this post. Both comments and trackbacks are currently closed.

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

  1. Anonymous

    Maybe one should note that using the “debugging” way of starting a Runtime Workbench from inside of Eclipse does not load the feature (only the plugins). So, if you want to see your icon you have to deploy it into a real Eclipse instance and start that.

    Have fun, Philipp

  2. Suresh Krishna

    At last i could find some related article for my problem. I really got tired of trying to see my own feature image in the About “productname”. I am using the Eclipse 3.2.1. I have my own plug-ins and feature developed, and i have no luck till now to show the image. Worst of all i am not able to see my feature itself in the “Feature details”.
    I have the product plug-in as a separate entity. I have the about.ini in this folder and have the featureImage=abc.jpg. My feature plug-in just contains feature.properties, feature.xml and license.html.
    Can you please let me know the possible mistake i am doing or any pointers to it.
    Any kind of help would be great.

  3. Anonymous

    Nice article. One thing you might want to add. You won’t see the feature button UNTIL you build the product/feature. It doesn’t display when running from within the IDE.

  4. Anonymous

    Thanks Kim, very helpful. This looked great on our Windows installation, but the branding does not appear on our MAC installations. Is there anything different that needs to be done for MACs?

  5. Anonymous

    Hello, thank you for this nice blog. I learned a lot.

    One reason I came along which could prevend your icon from being shown is, that you might not extract your plug-in in the plug-in folder. If it remains as a .jar, it does not work. In the feature configuration, you can check it to be extracted.

    Good luck

  6. Thomas

    If you feature is not shown up in the “Feature details” dialog, try to set one of your features as “primary=true”. This works for me.

  7. Bibi

    Great Article !
    It’s possible to You to create a zip file with a plugin project , a feature project and an update site project and attach it to this blog ?
    Thanks

  8. Brice

    Great Article!
    However, in my case I followed all the steps summarized in your summary but my icon still does not show up. I have two plug-ins and two features but only one icon shows up the other one doesn’t. I want two icons for the two plug-ins.
    Any Idea why this is happening?
    Thanks

  9. pookzilla Post author

    Sorry, i have no idea. I am on the outside of the eclipse community now and i haven’t been following the status of these features.

Comments are closed.

  • About Me

    Hi! My name is Kimberly Horne and I have absolutely nothing interesting to say. Unfortunately for you I DO have an overpowering need to tinker with technology which is explains the presence of this journal. I mostly talk about games (video and tabletop), technology, tattoos, and my pets.

    If you're an Eclipse user you may find my Eclipse category more interesting.

    Similarly, if you're an Arduino nerd then maybe my projects might be of interest.

    Since I've discovered Twitter this journal has been neglected somewhat. If you really want to stalk me your best bet is to follow me on twitter.