Support for "Icon Packs" in Eclipse Platform and Eclipse IDE Products

[BeckerWdf]

Scope Of This Discussion

Since quite some time there is the wish to support alternative icons in Eclipse Platform / Eclipse IDE Products.
See for example #13

"Icon Packs" can cater multiple use cases. This post tries to list these use cases and to rank them. This post is the shared understanding of the Vector (especially @fedejeanne and @HeikoKlare and SAP community members (especially @BeckerWdf, @sratz and @thomasritter). This should start a discussion with the whole community about this topic. The discussion should address the "what" (what to achieve) of the "Icon Pack" topic. Details of the "how" (how to technically implement this and how this looks from the user's point-of-view) should follow later.

Use Cases

Use Case 1: Deliver a Whole Product With Custom Styling

A company delivers a complete product that is based on the Eclipse (RCP) Platform. This product has nothing to do with Eclipse itself except for the fact that it is based on the Eclipse (RCP) Platform. The company wants their product to comply to a application specific styling.

Example

The ACME (A Company Modelling Everything) company builds an RCP application for modelling products. It uses the Eclipse Platform and SWT as the technology to build that product. This product is not anything similar to an IDE.

Characteristics

• The provider of that product has complete control over which bundles and features are included in that product.
• There is only a small(er) amount of icons to deliver for own bundles.
• There is no need to wait for other bundles to deliver appropriate icons, every icon can be created by the same team.
• The provider of that product needs to replace icons from Eclipse (RCP) Platform with icons that follow a custom styling.

Use Case 2: Extend Existing Product and Contribute Icons to an Icon Pack of That Product

A company extends an existing product that is based on the Eclipse (RCP) Platform. This is for example the case when one delivers extensions to the Eclipse IDE. In this case, the product is the Eclipse IDE. The company want's to contribute icons to an icon pack that is defined by the extended product.

Example

Eclipse Platform defines an icon pack called "Monochrome Flat". The Eclipse Platform bundles provide icons for this icon pack. Bundles from other Eclipse SimRel projects (e.g. JDT, CDT, ...) also contribute icons for this icon pack. A Company provides their own set of bundles to provide IDE support for their proprietary programming language and also want to contribute icons of Eclipse Platform's "Monochrome Flat" icon pack.

Characteristics

• The provider of the extension has control only over a limited set of bundles and feature in the product.
• There's a large amount of icons, scattered through several bundles (and possibly several teams).

Potential Issues

• There might be some bundles that don't provide icons for a given icon pack which means that the product may end up having a mixture of differently looking (3D-ish colorful vs- flat monochrome) icons.

Use Case 3: Provide Community Icon Pack

A freelance developer wants to define her own icon pack for a product she even does not provide or extend.
This use case is some kind of mixture of use case 1.

Example

A developer loves the Eclipse IDE but does not like the Eclipse default icons and also not the icon packs provided by the Eclipse IDE. Instead she wants to have 3D-ish monochrome icons in shades of purple.

Characteristics

• The developer of the icon pack has no control over which bundled and feature are included in the product.
• There are no "own" icons to deliver.
• There is no existing icon pack available to extend.
• The developer of the icon pack needs to define an own icon pack.
• The developer of the icon pack needs to replace icons of "foreign" bundles.

Ranking of Requirements

We see use use case 1 and use case 2 as the most important ones. Use case 3 seems not so important but should be possible anyway. But use case 3 should not add much complexity for the solutions for use use case 1 and use case 2.

Requirements For All Use Cases

• For use case 1 it might be no need for the user to have a possibility to change icon packs. But it might be that someone wants to deploy multiple icon packs for a complete RCP product that are interchangeable. So this possibility could be a desirable optional extension of this use case.
• For use case 2 and use case 3 the icons should be exchangeable at runtime. Best case would be without the need for a restart but a restart would also be ok.
• It should be possible to exchange the icons independently of the UI-Theme (CSS Theme).

Technical Considerations

Even though this document should only collect requirements but don't provide too much technical / implementation details this chapter lists some of them.

It should be possible to choose if the (replacement) icons will be delivered in bundles or in fragments.

Use case 1 seems to be already addressed by eclipse-equinox/equinox#732 and eclipse-equinox/equinox#731. See the example provided by #2686.

For Use case 2 and Use case 3 we still have to think of implementation ideas.

Outside Of The Scope of Icon Packs

Related Requirements

These are requirements that are related to the topic icons but are independent from the implementation of the icon pack use cases.
They should not be a prerequisite for icon packs and should be handled and implemented separately.

• Icons should be able to adapt to the current UI theme (Light/Dark).

  • There shouldn't be "light" and "dark" icon packs. Instead, the designer should be able to deliver more than one version of the same icon. A technical possibility to distinguish between them could be by the name of the file or by a segment in the file path e.g.
    • folder_icon.png is for the "light" UI theme and may be used for the "dark" UI theme too.
    • folder_icon_dark.png is for the "dark" theme and, if present, will be used instead of folder_icon.png when the UI theme is "dark".

• Sharing of frequently used icons between bundles should be possible.

  • Without the need of copying files.
  • Providing bundle should have a possibility to explicitly state for which icons this sharing should be possible (explicitly making it part of the API). Today sharing is possible e.g. via platform:/ uris but the API-aspect of it is missing

• Style of alternative icons (See: Refinement of the new modern icon style eclipse.platform.images#117)

• Possibility to use SVG natively in SWT for icons.

[laeubi]

For Use case 2 and Use case 3 we still have to think of implementation ideas.

I'm not completely sure why case 2+3 should not be possible with what we have for case 1 and how case 2+3 actually differ?

I also missing a bit the question or what to exactly discuss here even though it gives a good overview about different aspects of the topic.

From my point of view it would be most suitable to enhance the example documentation here:

https://github.com/eclipse-platform/eclipse.platform.ui/blob/master/examples/org.eclipse.ui.examples.iconpack/README.MD

with new aspects and or demonstrate missing features with real code example (maybe more examples).

[vogella]

I think we should have the option to link icon sets optional to CSS theme and a theme should have the option to define also a default icon set. In my opinion icon sets should register themself via OSGI services or extension points and the theme engine should be able to activate it. Most likely a restart of the application will be necessary to use the new icon sets.

The actual icon set selectioin can be stored as preference either for the workspace or in the user space in case the user decides so similar to the new default theme implementation I did.

I really like the existing JSON structure of https://github.com/eclipse-platform/eclipse.platform.ui/blob/master/examples/org.eclipse.ui.examples.iconpack my implementation could use the json mapping file to identify the correct icon if it is requested to load it.

[HeikoKlare]

Sounds reasonable to make it possible to optionally link an icon theme to a CSS theme.
Just note that something like an icon theme needs to consist of multiple icon set/packs that are combined to a theme with a defined precedence of the icon sets (in case one icon is redefined multiple time), because you will need to have independent icon sets for extensions that contribute to or can be combined to something like a theme.
I remember that we had already developed/sketched a concept for that (@BeckerWdf @thomasritter @sratz) but not sure if we have documented it somewhere already.

[vogella]

I have a concept for it, in case it is decided to get implemented. Contributing multiple configurations in which later entries override initial entries like CSS rules do, should definitely part of it, Dynamic icon updates at runtime might be possible but for that I would have to have an implementation prototype.

[BeckerWdf]

Maybe you could share your concept here...

[vogella]

I think it is part of the work item planned, right? So polishing it that other can read and discuss it would be part of that IMHO.

[vogella]

Concept: Theme Aware Icon Replacement for Eclipse Platform UI

1. Goal

Enable Eclipse based products (IDE and RCP) to replace the icons of any contributing bundle without patching those bundles, and to have the replacement follow the active theme (for example light, dark, high contrast, or a customer branded icon set). The mechanism should be transparent to existing plug ins, preserve HiDPI behavior, and be usable both by product vendors (custom look and feel) and by community icon packs.

2. Problem Statement

Today, Eclipse plug ins resolve their icons through platform URLs that point to files inside the contributing bundle. Customers and product teams who want a consistent visual identity, better dark mode icons, or a branded IDE currently have to fork bundles, override extensions one by one, or ship patched JARs. This is expensive, fragile, and does not scale across hundreds of bundles.

A sustainable solution must:

1. Intercept icon resolution at a single, well defined point inside the platform.
2. Allow an external mapping (icon pack) to decide, per icon, whether and how to redirect.
3. Integrate with the existing theming story so that switching the theme can switch the icon set.
4. Keep HiDPI, SVG, and zoom handling intact without the caller being aware.

3. Proposed Approach

We propose a small, additive extension point inside the platform's image loading layer, combined with a thin, optional bundle that ships a default icon pack format and a default discovery mechanism.

The approach has four layers:

Layer A, Core Hook (JFace). A minimal, additive strategy is introduced at the exact point where the platform turns an icon reference into bytes on disk. When no strategy is registered, behavior is byte for byte identical to today. When a strategy is registered, it is consulted once per resolution and can either pass the original reference through or return a replacement. This keeps the change in JFace tiny, auditable, and fully backward compatible.

Layer B, Icon Pack Format and Runtime (Workbench). A lightweight, declarative mapping format (one file per icon pack) describes which original icons are replaced by which replacement resources. A small runtime in the workbench loads the active icon pack at startup, builds a fast lookup structure, and wires it into the Layer A hook. Icon packs are ordinary OSGi bundles, so they can be installed, updated, and removed through p2 like any other feature.

Layer C, CSS and Theme Integration. The active icon pack is selected via the existing theme infrastructure, so that choosing a theme (for example "Dark with Fluent Icons") automatically activates the matching pack. This reuses the CSS engine and preference scopes already in place, rather than introducing a parallel configuration surface.

Layer D, HiDPI, SVG, and Zoom. Replacement happens on the base reference; the platform's existing zoom, @2x, and SVG rendering logic then applies on top. This means icon packs can ship @1x bitmaps, HiDPI variants, or SVG, and the same code paths that serve the stock icons serve the replacements, with no special cases.

4. Why This Design

• Minimal API surface. One small addition inside the platform. Everything else (mapping format, discovery, theme binding) lives outside and can evolve without breaking API.
• Zero impact when unused. Products that do not ship an icon pack see no behavior change and no measurable overhead.
• No fork, no patch. Third party plug ins continue to reference their own icons; the platform transparently redirects at load time.
• Composable with CSS. Icon choice becomes part of the theme, which is where users already expect it.
• Restart acceptable. Phase 1 activates icon packs at startup, which removes the need to invalidate caches across the workbench and keeps the change risk low.

5. Deliverables

1. Platform changes (core hook) with full test coverage, including HiDPI resolution paths.
2. Reference icon pack runtime in the workbench (mapping loader, activation, theme binding).
3. One sample icon pack bundle demonstrating the end to end flow.
4. Automated tests (unit and UI) covering the resolution paths and the mapping loader.
5. Developer documentation: how to build an icon pack, how to bind it to a theme, how to publish it through p2.
6. Upstream contribution plan (issues, PRs, review coordination) so the feature lands in the Eclipse Platform release stream rather than being a private fork.

6. Out of Scope (Phase 1)

• Hot swapping icon packs without restart.
• Automatic generation of icon packs from existing themes.
• A UI for end users to build or edit icon packs interactively.

These are natural follow ups and can be offered as a Phase 2.

7. Risks and Mitigations

• API review by the Platform team. Mitigated by keeping the added API minimal, additive, and behaviorally neutral when unused, and by pre aligning with committers before the PR.
• Performance at startup. Mitigated by building an O(1) lookup once at activation and applying it only to URL based resolution.
• Interaction with existing image caches. Mitigated by the "activate at startup, no runtime swap" constraint in Phase 1.
• Theme coverage gaps. Addressed by shipping a reference pack and documenting fallbacks so that missing mappings transparently fall back to the stock icon.

8. Indicative Plan and Effort

The work breaks down into four milestones: (1) core hook plus tests, (2) icon pack runtime and mapping format, (3) CSS and theme binding, (4) reference pack, documentation, and upstream contribution. A concrete effort estimate and schedule will be provided with the commercial offer, based on the scope confirmed with you.

9. Qualification

vogella has long standing committer presence on Eclipse Platform UI, CSS styling, JFace, and the E4 workbench, and has previously landed changes in all the areas this work touches (image loading, theming, CSS engine, workbench startup). We are therefore in a position to both implement the change and shepherd it through Eclipse Platform review so that your investment lands in the official release stream.

[iloveeclipse]

Layer C, CSS and Theme Integration. The active icon pack is selected via the existing theme infrastructure, so that choosing a theme (for example "Dark with Fluent Icons") automatically activates the matching pack. This reuses the CSS engine and preference scopes already in place, rather than introducing a parallel configuration surface.

Just to clarify: the proposal should still support the case if application doesn't use themes at all (CSS themes disabled).

[vogella]

Layer C, CSS and Theme Integration. The active icon pack is selected via the existing theme infrastructure, so that choosing a theme (for example "Dark with Fluent Icons") automatically activates the matching pack. This reuses the CSS engine and preference scopes already in place, rather than introducing a parallel configuration surface.

Just to clarify: the proposal should still support the case if application doesn't use themes at all (CSS themes disabled).

You want to to be able to select the icon set without using CSS, correct? Or do you want to see the default icons if no CSS is enabled (no icon theming support in this case)?

[iloveeclipse]

I just want that this proposal, if implemented, does not break use of applications with CSS themes disabled, means, whatever icon set is considered to be "default for Eclipse" should be still there without CSS themes. Of course it would be good to change icons without using CSS theme, but it is "nice to have" and not "must have" requirement (at least for me).

[vogella]

As preparation for this potential work, I reviewed the CSS engine in detail, and I plan to optimize it in an upcoming release. This effort is part of this work, but it helped to understand this issue better.

Based on this analysis, I can estimate the implementation effort for this item with reasonable confidence at 2–5 days: 2 days if everything goes as expected, more if extensive review discussion is needed or if additional challenges surface during implementation.