diff --git a/examples/org.eclipse.ui.examples.iconpack/.project b/examples/org.eclipse.ui.examples.iconpack/.project new file mode 100644 index 00000000000..f50ac3dc96d --- /dev/null +++ b/examples/org.eclipse.ui.examples.iconpack/.project @@ -0,0 +1,22 @@ + + + org.eclipse.ui.examples.iconpack + + + + + + org.eclipse.pde.ManifestBuilder + + + + + org.eclipse.pde.SchemaBuilder + + + + + + org.eclipse.pde.PluginNature + + diff --git a/examples/org.eclipse.ui.examples.iconpack/.settings/org.eclipse.core.resources.prefs b/examples/org.eclipse.ui.examples.iconpack/.settings/org.eclipse.core.resources.prefs new file mode 100644 index 00000000000..99f26c0203a --- /dev/null +++ b/examples/org.eclipse.ui.examples.iconpack/.settings/org.eclipse.core.resources.prefs @@ -0,0 +1,2 @@ +eclipse.preferences.version=1 +encoding/=UTF-8 diff --git a/examples/org.eclipse.ui.examples.iconpack/.settings/org.eclipse.pde.core.prefs b/examples/org.eclipse.ui.examples.iconpack/.settings/org.eclipse.pde.core.prefs new file mode 100644 index 00000000000..e8ff8be0bab --- /dev/null +++ b/examples/org.eclipse.ui.examples.iconpack/.settings/org.eclipse.pde.core.prefs @@ -0,0 +1,4 @@ +eclipse.preferences.version=1 +pluginProject.equinox=false +pluginProject.extensions=false +resolve.requirebundle=false diff --git a/examples/org.eclipse.ui.examples.iconpack/META-INF/MANIFEST.MF b/examples/org.eclipse.ui.examples.iconpack/META-INF/MANIFEST.MF new file mode 100644 index 00000000000..303312da8d3 --- /dev/null +++ b/examples/org.eclipse.ui.examples.iconpack/META-INF/MANIFEST.MF @@ -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)" diff --git a/examples/org.eclipse.ui.examples.iconpack/README.MD b/examples/org.eclipse.ui.examples.iconpack/README.MD new file mode 100644 index 00000000000..81f601c4c09 --- /dev/null +++ b/examples/org.eclipse.ui.examples.iconpack/README.MD @@ -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 `,,,`, 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. ... \ No newline at end of file diff --git a/examples/org.eclipse.ui.examples.iconpack/about.html b/examples/org.eclipse.ui.examples.iconpack/about.html new file mode 100644 index 00000000000..164f781a8fd --- /dev/null +++ b/examples/org.eclipse.ui.examples.iconpack/about.html @@ -0,0 +1,36 @@ + + + + +About + + +

About This Content

+ +

November 30, 2017

+

License

+ +

+ 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 http://www.eclipse.org/legal/epl-2.0. + For purposes of the EPL, "Program" will mean the Content. +

+ +

+ 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 http://www.eclipse.org. +

+ + + \ No newline at end of file diff --git a/examples/org.eclipse.ui.examples.iconpack/build.properties b/examples/org.eclipse.ui.examples.iconpack/build.properties new file mode 100644 index 00000000000..10a6e4470b9 --- /dev/null +++ b/examples/org.eclipse.ui.examples.iconpack/build.properties @@ -0,0 +1,6 @@ +bin.includes = META-INF/,\ + myicons/,\ + about.html,\ + transform.txt + +src.includes = about.html \ No newline at end of file diff --git a/examples/org.eclipse.ui.examples.iconpack/forceQualifierUpdate.txt b/examples/org.eclipse.ui.examples.iconpack/forceQualifierUpdate.txt new file mode 100644 index 00000000000..8ad7a91157b --- /dev/null +++ b/examples/org.eclipse.ui.examples.iconpack/forceQualifierUpdate.txt @@ -0,0 +1 @@ +# To force a version qualifier update add the bug here \ No newline at end of file diff --git a/examples/org.eclipse.ui.examples.iconpack/myicons/saveme.png b/examples/org.eclipse.ui.examples.iconpack/myicons/saveme.png new file mode 100644 index 00000000000..0f957d8a2e1 Binary files /dev/null and b/examples/org.eclipse.ui.examples.iconpack/myicons/saveme.png differ diff --git a/examples/org.eclipse.ui.examples.iconpack/myicons/saveme@2x.png b/examples/org.eclipse.ui.examples.iconpack/myicons/saveme@2x.png new file mode 100644 index 00000000000..93a325b47a8 Binary files /dev/null and b/examples/org.eclipse.ui.examples.iconpack/myicons/saveme@2x.png differ diff --git a/examples/org.eclipse.ui.examples.iconpack/replaced_icon.png b/examples/org.eclipse.ui.examples.iconpack/replaced_icon.png new file mode 100644 index 00000000000..fc7bd95c030 Binary files /dev/null and b/examples/org.eclipse.ui.examples.iconpack/replaced_icon.png differ diff --git a/examples/org.eclipse.ui.examples.iconpack/transform.txt b/examples/org.eclipse.ui.examples.iconpack/transform.txt new file mode 100644 index 00000000000..2008dd8491c --- /dev/null +++ b/examples/org.eclipse.ui.examples.iconpack/transform.txt @@ -0,0 +1,4 @@ +org\.eclipse\.ui,icons/.*/save_edit.png,/myicons/saveme.png +org\.eclipse\.ui,icons/.*/save_edit@2x.png,/myicons/saveme@2x.png + +