-
Notifications
You must be signed in to change notification settings - Fork 198
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Loading status checks…
Add an example for providing an icon pack
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.
- Y20250214-1000
- Y20250213-1000
- Y20250212-1000
- Y20250211-1000
- Y20250210-1000
- Y20250209-1000
- Y20250208-1000
- Y20250207-1000
- Y20250206-1000
- Y20250205-1000
- Y20250204-1000
- Y20250203-1000
- Y20250202-1000
- Y20250201-1000
- Y20250131-1000
- Y20250130-1000
- Y20250129-1000
- Y20250128-1000
- Y20250127-1000
- Y20250125-1000
- Y20250124-1000
- Y20250123-1000
- Y20250122-1000
- Y20250121-1000
- Y20250120-1000
- Y20250119-1000
- Y20250118-1000
- Y20250117-1000
- Y20250116-1000
- Y20250115-1000
- Y20250114-1000
- Y20250113-1000
- Y20250112-1000
- Y20250111-1000
- S4_35_0_M3
- I20250215-0600
- I20250214-1800
- I20250213-1800
- I20250213-0210
- I20250212-2340
- I20250212-1800
- I20250212-0500
- I20250211-1800
- I20250211-0520
- I20250210-1800
- I20250209-1800
- I20250208-1800
- I20250207-1800
- I20250206-1800
- I20250205-1800
- I20250204-1800
- I20250203-1800
- I20250203-0500
- I20250202-1800
- I20250201-1800
- I20250131-1800
- I20250130-1800
- I20250129-1800
- I20250129-0030
- I20250127-1800
- I20250126-1800
- I20250125-1800
- I20250124-1800
- I20250123-1800
- I20250122-1800
- I20250121-1800
- I20250120-1800
- I20250120-0740
- I20250119-1800
- I20250118-1800
- I20250117-1800
- I20250116-1800
- I20250116-0550
- I20250115-1800
- I20250115-0110
- I20250114-1800
- I20250113-1800
- I20250112-1800
- I20250111-1800
Showing
12 changed files
with
162 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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> |
2 changes: 2 additions & 0 deletions
2
examples/org.eclipse.ui.examples.iconpack/.settings/org.eclipse.core.resources.prefs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
eclipse.preferences.version=1 | ||
encoding/<project>=UTF-8 |
4 changes: 4 additions & 0 deletions
4
examples/org.eclipse.ui.examples.iconpack/.settings/org.eclipse.pde.core.prefs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 |
9 changes: 9 additions & 0 deletions
9
examples/org.eclipse.ui.examples.iconpack/META-INF/MANIFEST.MF
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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)" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. ... |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
("Content"). Unless otherwise indicated below, the Content | ||
is provided to you under the terms and conditions of the Eclipse | ||
Public License Version 2.0 ("EPL"). 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, "Program" 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 | ||
("Redistributor") 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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 |
1 change: 1 addition & 0 deletions
1
examples/org.eclipse.ui.examples.iconpack/forceQualifierUpdate.txt
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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] | ||
|
||
|