Skip to content

Commit

Permalink
Add an example for providing an icon pack
Browse files Browse the repository at this point in the history
There are some ongoing demands for providing custom icons to the Eclipse
IDE or RCP applications.

This now adds an example of how such an "icon-pack" can be created and
used inside Eclipse IDE.
laeubi committed Jan 11, 2025

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
1 parent 33f4606 commit d876bc7
Showing 12 changed files with 162 additions and 0 deletions.
22 changes: 22 additions & 0 deletions examples/org.eclipse.ui.examples.iconpack/.project
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
<name>org.eclipse.ui.examples.iconpack</name>
<comment></comment>
<projects>
</projects>
<buildSpec>
<buildCommand>
<name>org.eclipse.pde.ManifestBuilder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.pde.SchemaBuilder</name>
<arguments>
</arguments>
</buildCommand>
</buildSpec>
<natures>
<nature>org.eclipse.pde.PluginNature</nature>
</natures>
</projectDescription>
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
eclipse.preferences.version=1
encoding/<project>=UTF-8
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
eclipse.preferences.version=1
pluginProject.equinox=false
pluginProject.extensions=false
resolve.requirebundle=false
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Iconpack
Bundle-SymbolicName: org.eclipse.ui.examples.iconpack
Bundle-Version: 1.0.0.qualifier
Bundle-Vendor: Eclipse.org
Automatic-Module-Name: org.eclipse.ui.examples.iconpack
Equinox-Transformer: /transform.txt
Require-Capability: osgi.extender;filter:="(osgi.extender=equinox.transforms.hook)"
78 changes: 78 additions & 0 deletions examples/org.eclipse.ui.examples.iconpack/README.MD
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# Example for providing an icon pack to Eclipse IDE / RCP

This example demonstrate how to create an icon pack for the Eclipse IDE or a custom RCP application.

An icon pack on a technical level is a simple bundle that can be installed like any other piece of software and
ships one or more alternative representations of an existing icon resource to one or more bundles already installed
in the system. This allows an icon pack to customize the look and feel of Eclipse RCP Applications even further
beyond what is already possible with css.

For a bundle to be recognized by the system one needs the following things demonstrated in this example:

1. The bundle should list the following header in its manifest to make sure the equinox transform hook is made available when installing it:
`Require-Capability: osgi.extender;filter:="(osgi.extender=equinox.transforms.hook)"`
2. It needs to maintain transformer rules file, in our example this is done by the file `transform.txt` but any
name / extension is valid here, the format of the file is described below.
3. It must list the location in the manifest with the `Equinox-Transformer: /transform.txt` bundle header to be recognized by the framework
4. Make sure that the icons and the transform rules files are included in the `bin.include` in the `build.properties`!

## writing transformer rules file

a transformer rules file is a simple text file that (similar to rewrite rules in a webserver) tells the framework what resources in a bundle should be replaced
with another.

The general format is `<bundle pattern>,<resource pattern>,<transformer instructions>,<transformer>`, where the last part can be omitted here as it defaults
to `replace` what is the one we need for icon packs.

### replace one icon by another

Now assume we want to replace the save icon because a floppy-disk is really nothing people today know and might wonder what this strange quadratic thing should actually
mean to them and today a downwards arrow is more common (even though for demonstration purpose our icon looks quite ugly so it is easily spotted as being replaced).

1. We first need to know the bundle that provides this what in this case is the `org.eclipse.ui` so our pattern for matching this bundle would be `org\.eclipse\.ui`,
what would only match this single bundle. If an icon has to be replaced in multiple bundles we can either use a less narrow pattern or use two different rules.
2. Then one needs to find the icon to replace in this case it is `icons/full/etool16/save_edit.png`, as before we could use an exact match or we can use a more
generic form to possibly match multiple path. In the example we use `icons/.*/save_edit.png`, please note that you even can replace a gif file by a png or whatever
fileformat fits your needs. The code will still see the old name so this might still be used with care if the caller maybe make decisions based on the extension!
3. Of course we need our replacement resource that will be used and we put it in as the last instruction as we are using the default replace tranformer that just keeps
the provided resource as a replacement for the original.

The full line then looks like this:

```
org\.eclipse\.ui,icons/.*/save_edit.png,/myicons/saveme.png
```

### replace multiple icons

A transformer rules file can contain as many lines as you want and you can replace also icons from as many bundles as you like in the same icon pack.

## Running the example

If you want to run the example, make sure that you add the following to your run configuration (or extend an existing configuration):

```
-Dosgi.framework.extensions=org.eclipse.equinox.transforms.hook
```

this enables the equinox transforms hook extension also make sure that at least version `1.4.200` is used as it includes the required enhancements
used in this example.

Also make sure the example is included in the launch e.g. add it to an existing feature of your product / launch configuration.

If everything worked well, you should see your new save icon in the toolbar like this:

![example showing replaced icon](replaced_icon.png)

## Future enhancements

This example is currently only a very bare example, everyone is encouraged to help enhancing it and sharing ideas how this can be made more comfortable,
also there is currently no tooling around this so any help is appreciated.

Here is an (incomplete) list of things that might be useful in future versions:

1. supporting capture groups in a transform instruction to match a large amount of icon with one line and also support `@2x` variants more easily (currently it requires a duplicate line)
2. having a way to exactly match a bundle without the need to escape special chars like `.` and supporting simple ant style glob pattern
3. some tooling that allows to select a bundle and generate a list of icon replacements automatically
4. support systemproperty or variable placeholders to support for example a theming system
5. ...
36 changes: 36 additions & 0 deletions examples/org.eclipse.ui.examples.iconpack/about.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
<title>About</title>
</head>
<body lang="EN-US">
<h2>About This Content</h2>

<p>November 30, 2017</p>
<h3>License</h3>

<p>
The Eclipse Foundation makes available all content in this plug-in
(&quot;Content&quot;). Unless otherwise indicated below, the Content
is provided to you under the terms and conditions of the Eclipse
Public License Version 2.0 (&quot;EPL&quot;). A copy of the EPL is
available at <a href="http://www.eclipse.org/legal/epl-2.0">http://www.eclipse.org/legal/epl-2.0</a>.
For purposes of the EPL, &quot;Program&quot; will mean the Content.
</p>

<p>
If you did not receive this Content directly from the Eclipse
Foundation, the Content is being redistributed by another party
(&quot;Redistributor&quot;) and different terms and conditions may
apply to your use of any object code in the Content. Check the
Redistributor's license that was provided with the Content. If no such
license exists, contact the Redistributor. Unless otherwise indicated
below, the terms and conditions of the EPL still apply to any source
code in the Content and such source code may be obtained at <a
href="http://www.eclipse.org/">http://www.eclipse.org</a>.
</p>

</body>
</html>
6 changes: 6 additions & 0 deletions examples/org.eclipse.ui.examples.iconpack/build.properties
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
bin.includes = META-INF/,\
myicons/,\
about.html,\
transform.txt

src.includes = about.html
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# To force a version qualifier update add the bug here
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 4 additions & 0 deletions examples/org.eclipse.ui.examples.iconpack/transform.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
org\.eclipse\.ui,icons/.*/save_edit.png,/myicons/saveme.png
org\.eclipse\.ui,icons/.*/[email protected],/myicons/[email protected]


0 comments on commit d876bc7

Please sign in to comment.