Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Platform-releng/Updating Branding"
m (Feature icons for about dialog) |
m (→Version Numbers) |
||
| (21 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
This page contains information on updating the Eclipse SDK branding elements (icon, splash screen, etc). | This page contains information on updating the Eclipse SDK branding elements (icon, splash screen, etc). | ||
| + | |||
| + | Most items on this page only need updating when there is a change in branding, or theme, such as perhaps for every major release. | ||
| + | |||
| + | But, some need to be updated every release, even service releases, such as see [[Platform-releng/Updating_Branding#Version_Numbers| Version Numbers]] and [[#Copyright_blurbs| Copyright blurbs]]. | ||
| + | |||
= Splash screen = | = Splash screen = | ||
| Line 6: | Line 11: | ||
In the same org.eclipse.platform bundle, the plugin.xml file contains properties specifying the font color and position of progress messages that are overlayed on the splash screen during startup. These properties might need changing if there are significant changes to the splash screen layout. See properties startupForegroundColor, startupMessageRect, and startupProgressRect | In the same org.eclipse.platform bundle, the plugin.xml file contains properties specifying the font color and position of progress messages that are overlayed on the splash screen during startup. These properties might need changing if there are significant changes to the splash screen layout. See properties startupForegroundColor, startupMessageRect, and startupProgressRect | ||
| + | |||
| + | '''Note: ''' If your image program offers a choice, such as GIMP 2.8.10 does, it is important to save the the bmp WITHOUT color space information saved or, else, the splash screen will not be displayed on Windows .... apparently a silent failure to read a "modern" BMP file (watch {{bug|439573}}). Also, The bitmap should be saved in 24 bit format (8R, 8G, 8B) for else "funny colors" (such as red instead of blue, or green instead of blue) will sometimes appear if the 32 bit format is used, with 8 bits of "transparency". | ||
= Icons = | = Icons = | ||
| Line 48: | Line 55: | ||
*Every feature with a branding plugin contains a copy of the 32-bit PNG file. The file name is specified in about.ini, but is usually called eclipse32.png.<br>''Note:'' The About dialog groups the features by their icons. To do this, it compares the file content and not the name! | *Every feature with a branding plugin contains a copy of the 32-bit PNG file. The file name is specified in about.ini, but is usually called eclipse32.png.<br>''Note:'' The About dialog groups the features by their icons. To do this, it compares the file content and not the name! | ||
| − | * | + | *The primary product features (org.eclipse.platform and org.eclipse.sdk), also contain a larger 116x164 pixel image for the about dialog called eclipse_lg.gif. |
=== Window images === | === Window images === | ||
| Line 62: | Line 69: | ||
Typically you can just replace the existing files with new files of the same name. If you need to add additional sizes, they are listed in plugin.xml, in the property "windowImages". | Typically you can just replace the existing files with new files of the same name. If you need to add additional sizes, they are listed in plugin.xml, in the property "windowImages". | ||
| − | === Launcher icons === | + | === Launcher (Desktop) icons === |
| − | On Windows, the icon is embedded in the eclipse.exe executable. This is done by the launcher build. The icon file is placed [http://git.eclipse.org/c/equinox/rt.equinox.framework.git/tree/ | + | ==== Windows ==== |
| + | On Windows, the '''eclipse.ico''' icon is embedded in the eclipse.exe executable. This is done by the launcher build. The icon file (which itself contains 6 or so icons of various sizes), is placed in [http://git.eclipse.org/c/equinox/rt.equinox.framework.git/tree/features/org.eclipse.equinox.executable.feature/library/win32/ this Git location]. A launcher build must then be run to build a new executable with the embedded icon. Most build systems can "replace" those icons during a custom build, as long as replacements are "same shape" as what is in original, embedded ICO resource. | ||
| − | On other platforms, the icon is just included as a separate file in the launcher installable unit. The icons just need to be dropped into this [http://git.eclipse.org/c/equinox/rt.equinox.framework.git/tree/ | + | ===== Use common pallet ===== |
| + | |||
| + | As mentioned in {{bug|433094#c3}} for icons that will, or might, require a "reduced pallet" (say, 256 colors only) then all those icons must use the same pallet, in an ICO file. Hence it is important to create them with this in mind (i.e. with exact same pallet), otherwise, heavy distortions may occur as "ICO creation" tools try to adjust them to all fit in the same pallet. Ideally, even if original images require more than 256 colors, the "main" 256 colors will all be common. | ||
| + | |||
| + | ==== Others ==== | ||
| + | |||
| + | On other platforms, the icon is just included as a separate file (or, files) in the launcher installable unit. The icons just need to be dropped into appropriate Git location(s), and then are packaged by the rest of the build. Note: currently, some icons are duplicated, either literally or by "copy-resources" during the build to the 'tychobuilder' product definitions. We probably only need them in the product definitions area, not the executable feature area (except, for Windows, since that is built into executable), but still need to investigate pros and cons of that approach. See {{bug|427428}}. | ||
| + | |||
| + | ===== MacOSX ===== | ||
| + | |||
| + | The '''Eclipse.icns''' file goes in subdirector of the 'Eclipse.app', such as this in [http://git.eclipse.org/c/equinox/rt.equinox.framework.git/tree/features/org.eclipse.equinox.executable.feature/bin/cocoa/macosx/x86/Eclipse.app/Contents/Resources/ this Git location]. | ||
| + | |||
| + | ===== Linux ===== | ||
| + | |||
| + | The '''icon.xpm''' icon file goes under the architecture directory for Linux, such as in [http://git.eclipse.org/c/equinox/rt.equinox.framework.git/tree/features/org.eclipse.equinox.executable.feature/bin/gtk/linux/x86_64 this Git location]. | ||
| + | |||
| + | ===== Solaris ===== | ||
| + | |||
| + | For Solaris, there are 4 sizes of pixmap icons, '''Eclipse.l.pm''', '''Eclipse.m.pm''', '''Eclipse.s.pm''', and '''Eclipse.t.pm''' that go under the architecture directory for Solaris, such as in [http://git.eclipse.org/c/equinox/rt.equinox.framework.git/tree/features/org.eclipse.equinox.executable.feature/bin/gtk/solaris/x86 this Git Location]. | ||
=== Icon in IDE === | === Icon in IDE === | ||
| − | The IDE itself uses | + | The IDE itself uses the 16x16 PNG variant of the Eclipse icon ('eclipse16.png'). Note that this icon must have a border of space around it, e.g. in the Product wizard or for the Eclipse launch configuration: |
| − | */org.eclipse. | + | */org.eclipse.ant.ui/icons/full/obj16/eclipse16.png |
| − | */org.eclipse.pde.api.tools.ui/icons/full/obj16/ | + | */org.eclipse.pde.api.tools.ui/icons/full/obj16/eclipse16.png |
| − | */org.eclipse.pde.ui/icons/etool16/ | + | */org.eclipse.pde.ui/icons/etool16/eclipse16.png |
| − | */org.eclipse.pde.ui/icons/obj16/ | + | */org.eclipse.pde.ui/icons/obj16/eclipse16.png |
== References == | == References == | ||
| Line 89: | Line 115: | ||
* http://developer.gnome.org/hig-book/stable/icons-types.html.en#application_icons | * http://developer.gnome.org/hig-book/stable/icons-types.html.en#application_icons | ||
* http://tango.freedesktop.org/Tango_Icon_Theme_Guidelines#Sizes | * http://tango.freedesktop.org/Tango_Icon_Theme_Guidelines#Sizes | ||
| + | * [http://docs.oracle.com/cd/E19683-01/806-7492/creatingicons-20497/index.html Solaris Desktop Icons] Such as 'Eclipse.l.pm', 'Eclipse.m.pm', etc. | ||
| + | * Good [http://www.visualpharm.com/articles/icon_sizes.html summary of icon sizes] for many popular platforms and devices. | ||
= Other branding elements = | = Other branding elements = | ||
| Line 95: | Line 123: | ||
The welcome page has branding that may need updating if there is a major theme change. | The welcome page has branding that may need updating if there is a major theme change. | ||
| + | |||
| + | == Version Numbers == | ||
| + | |||
| + | Most "versions" displayed for feature or bundles are determined by the version of the feature (in feature.xml) or bundle (in MANIFEST.MF). And, remember, a "branding bundle" should be assigned the same version as the feature for which it is the branding bundle, even though it itself may not change. | ||
| + | |||
| + | One exception is the "version" in the main "about box". For Eclipse 4.5 (Mars release) this says "Version: Mars (4.5)" and, for example, would be expected to be "Mars.1 (4.5.1)" for first maintenance release. | ||
| + | * The "train name", is set in the parent pom, via the property "releaseName", for example, <nowiki><releaseName>Mars</releaseName></nowiki> which would be <nowiki><releaseName>Mars.1</releaseName></nowiki> for first service release. | ||
| + | * The "marketing number" in the about box, such as "4.4", or "4.4.1", is also set in the parent pom, with the properties | ||
| + | <nowiki><releaseNumberSDK></nowiki> and <nowiki><releaseNumberPlatform></nowiki>. Typically these are the same value, and typically the same value as the "feature version" of the Eclipse Platform or Eclipse SDK, but would not have to be. They are, technically, an attribute of the ''product'' Eclipse Platform and Eclipse SDK. | ||
| + | * The version in the splash screen (for the Eclipse SDK) is determined by a property defined in the .product file, such as for sdk.product: | ||
| + | <pre> | ||
| + | <nowiki> | ||
| + | <property name="eclipse.buildId" value="${unqualifiedVersion}.${buildQualifier}" /> | ||
| + | </nowiki> | ||
| + | </pre> | ||
| + | The "unqualifiedVersion" part of that value, is artifact ID of the maven artifact for the product, as defined in the product's pom.xml file. One of the few cases where the artifact Id must be updated for maintenance streams. (This is handled differently than the above "release number" cases simply because Tycho is in charge of one of them, and our "branding bundles" are in charge of the other.) And, this value determines the release number in "updates" (that is, becomes part of the content repository metadata. | ||
| + | * For main features, there's a description property in the *.p2.inf that contains the release name, see [http://git.eclipse.org/c/platform/eclipse.platform.releng.aggregator.git/commit/?id=41534d7c402c4f20b931dc6db730f4fb417ad081 here], e.g. | ||
| + | properties.1.value = Initial Mars Release of the Eclipse Platform. | ||
| + | These should be changed every release so that users can "see" that something is new, even if it is to say simply "First Update Release for Mars", or similar. | ||
| + | * Another change to make every release, is in the <code>.eclipseproduct</code> marker file, that is a root file of the eclipse platform feature. It's version should be updated to match the "marketing number" of the release. (Investigating if can be automated, in {{bug|476075}}). | ||
| + | |||
| + | == Copyright blurbs == | ||
| + | |||
| + | The copyright statement comes from two sources. First are the about.properties file, for any "root feature". | ||
| + | |||
| + | But, the copyright in the main "about box" comes from the plugin.properties of the branding bundle for the product. | ||
| + | |||
| + | Note: we intentionally, currently do not use the copyright symbol ('\u00A9', or '©') since it is not part of every code page in every language. See {{bug|427514#c19}} or [http://en.wikipedia.org/wiki/Copyright_symbol#Digital_representation other sources]. | ||
[[Category:Eclipse_Platform_Releng| ]] | [[Category:Eclipse_Platform_Releng| ]] | ||
Revision as of 16:54, 27 August 2015
This page contains information on updating the Eclipse SDK branding elements (icon, splash screen, etc).
Most items on this page only need updating when there is a change in branding, or theme, such as perhaps for every major release.
But, some need to be updated every release, even service releases, such as see Version Numbers and Copyright blurbs.
Splash screen
The splash screen used for both the Eclipse SDK and Eclipse Platform Runtime is located in the bundle org.eclipse.platform (see in Git repository). It is a single file called splash.bmp (a 452x302 bitmap). The same directory in the source tree contains some PhotoShop source files that can be used to update the splash. Typically each year the splash needs updating with the current year in the copyright statement, and the name of the Simultaneous Release.
In the same org.eclipse.platform bundle, the plugin.xml file contains properties specifying the font color and position of progress messages that are overlayed on the splash screen during startup. These properties might need changing if there are significant changes to the splash screen layout. See properties startupForegroundColor, startupMessageRect, and startupProgressRect
Note: If your image program offers a choice, such as GIMP 2.8.10 does, it is important to save the the bmp WITHOUT color space information saved or, else, the splash screen will not be displayed on Windows .... apparently a silent failure to read a "modern" BMP file (watch bug 439573). Also, The bitmap should be saved in 24 bit format (8R, 8G, 8B) for else "funny colors" (such as red instead of blue, or green instead of blue) will sometimes appear if the 32 bit format is used, with 8 bits of "transparency".
Icons
The icons for the Eclipse SDK are rarely updated, but when they do change, it is a significant process. Icons have to be prepared in various sizes and formats for different platforms. They have to be inserted into the build in various places.
Icon sizes and formats
The following sizes and formats are needed, as a starting point:
Png - 32 bit: (all sizes) 16, 22, 24, 32, 48, 64, 128, 256, 512, 1024
Gif - 8 bit / 256 colors 16, 22, 24, 32, 48
4 bit / 16 colors 16,22,24,32,48
Note: Besides the "normal" icon, a 16x16 Gif is needed where the Eclipse icon has a border around it. This is used inside the IDE at various places (see below)
How these sizes and formats will be further prepared for delivery depends on platform:
Windows ICO file containing:
- 32 bit PNG: 16x16, 24x24, 32x32, 48x48, 64x64 and 256x256
- 8 bit GIF: 16, 24, 32, 48
- 4 bit GIF: 16, 24, 32, 48
- Only a 32-bit copy of the 256x256 pixel image should be included, and only the 256x256 pixel image should be
compressed to keep the file size down. Note that the sizes (24x24 and 64x64) are included for "classic" mode on XP.
MAC ICNS file format containing 1024x1024, 512x512, 256x256, 128x128, 32x32, 16x16, original format is PNG
Linux XPM file containing a single resolution. Currently 256x256.
Icon locations
Feature icons for about dialog
- Every feature with a branding plugin contains a copy of the 32-bit PNG file. The file name is specified in about.ini, but is usually called eclipse32.png.
Note: The About dialog groups the features by their icons. To do this, it compares the file content and not the name! - The primary product features (org.eclipse.platform and org.eclipse.sdk), also contain a larger 116x164 pixel image for the about dialog called eclipse_lg.gif.
Window images
The images that appear in the upper left hand corner of each window are specified by the product branding plugin (org.eclipse.platform and org.eclipse.sdk in our case). A variety of sizes and formats are given, and SWT has an algorithm to select the most appropriate image for a given platform. We currently provide:
- 32x32 GIF image (eclipse32.gif)
- 48x48 GIF image (eclipse48.gif)
- 32x32 PNG image (eclipse32.png)
- 48x48 PNG image (eclipse48.png)
- 256x256 PNG image (eclipse256.png)
Typically you can just replace the existing files with new files of the same name. If you need to add additional sizes, they are listed in plugin.xml, in the property "windowImages".
Launcher (Desktop) icons
Windows
On Windows, the eclipse.ico icon is embedded in the eclipse.exe executable. This is done by the launcher build. The icon file (which itself contains 6 or so icons of various sizes), is placed in this Git location. A launcher build must then be run to build a new executable with the embedded icon. Most build systems can "replace" those icons during a custom build, as long as replacements are "same shape" as what is in original, embedded ICO resource.
Use common pallet
As mentioned in bug 433094#c3 for icons that will, or might, require a "reduced pallet" (say, 256 colors only) then all those icons must use the same pallet, in an ICO file. Hence it is important to create them with this in mind (i.e. with exact same pallet), otherwise, heavy distortions may occur as "ICO creation" tools try to adjust them to all fit in the same pallet. Ideally, even if original images require more than 256 colors, the "main" 256 colors will all be common.
Others
On other platforms, the icon is just included as a separate file (or, files) in the launcher installable unit. The icons just need to be dropped into appropriate Git location(s), and then are packaged by the rest of the build. Note: currently, some icons are duplicated, either literally or by "copy-resources" during the build to the 'tychobuilder' product definitions. We probably only need them in the product definitions area, not the executable feature area (except, for Windows, since that is built into executable), but still need to investigate pros and cons of that approach. See bug 427428.
MacOSX
The Eclipse.icns file goes in subdirector of the 'Eclipse.app', such as this in this Git location.
Linux
The icon.xpm icon file goes under the architecture directory for Linux, such as in this Git location.
Solaris
For Solaris, there are 4 sizes of pixmap icons, Eclipse.l.pm, Eclipse.m.pm, Eclipse.s.pm, and Eclipse.t.pm that go under the architecture directory for Solaris, such as in this Git Location.
Icon in IDE
The IDE itself uses the 16x16 PNG variant of the Eclipse icon ('eclipse16.png'). Note that this icon must have a border of space around it, e.g. in the Product wizard or for the Eclipse launch configuration:
- /org.eclipse.ant.ui/icons/full/obj16/eclipse16.png
- /org.eclipse.pde.api.tools.ui/icons/full/obj16/eclipse16.png
- /org.eclipse.pde.ui/icons/etool16/eclipse16.png
- /org.eclipse.pde.ui/icons/obj16/eclipse16.png
References
(1) SWG User Interface Branding - Application Icon, Icon Creation: http://stwweb1.torolab.ibm.com/uibranding/rational/appl_icon_creation.html - for Windows only, does not include latest larger size 256
- Information and links provided by Eclipse developers
- Windows sizes and production information
- Mac reference
- https://bugzilla.mozilla.org/show_bug.cgi?id=495250
- bug 341645 - master bug for updating graphics in Juno release
- http://developer.gnome.org/hig-book/stable/icons-types.html.en#application_icons
- http://tango.freedesktop.org/Tango_Icon_Theme_Guidelines#Sizes
- Solaris Desktop Icons Such as 'Eclipse.l.pm', 'Eclipse.m.pm', etc.
- Good summary of icon sizes for many popular platforms and devices.
Other branding elements
Welcome page
The welcome page has branding that may need updating if there is a major theme change.
Version Numbers
Most "versions" displayed for feature or bundles are determined by the version of the feature (in feature.xml) or bundle (in MANIFEST.MF). And, remember, a "branding bundle" should be assigned the same version as the feature for which it is the branding bundle, even though it itself may not change.
One exception is the "version" in the main "about box". For Eclipse 4.5 (Mars release) this says "Version: Mars (4.5)" and, for example, would be expected to be "Mars.1 (4.5.1)" for first maintenance release.
- The "train name", is set in the parent pom, via the property "releaseName", for example, <releaseName>Mars</releaseName> which would be <releaseName>Mars.1</releaseName> for first service release.
- The "marketing number" in the about box, such as "4.4", or "4.4.1", is also set in the parent pom, with the properties
<releaseNumberSDK> and <releaseNumberPlatform>. Typically these are the same value, and typically the same value as the "feature version" of the Eclipse Platform or Eclipse SDK, but would not have to be. They are, technically, an attribute of the product Eclipse Platform and Eclipse SDK.
- The version in the splash screen (for the Eclipse SDK) is determined by a property defined in the .product file, such as for sdk.product:
<property name="eclipse.buildId" value="${unqualifiedVersion}.${buildQualifier}" />
The "unqualifiedVersion" part of that value, is artifact ID of the maven artifact for the product, as defined in the product's pom.xml file. One of the few cases where the artifact Id must be updated for maintenance streams. (This is handled differently than the above "release number" cases simply because Tycho is in charge of one of them, and our "branding bundles" are in charge of the other.) And, this value determines the release number in "updates" (that is, becomes part of the content repository metadata.
- For main features, there's a description property in the *.p2.inf that contains the release name, see here, e.g.
properties.1.value = Initial Mars Release of the Eclipse Platform.
These should be changed every release so that users can "see" that something is new, even if it is to say simply "First Update Release for Mars", or similar.
- Another change to make every release, is in the
.eclipseproductmarker file, that is a root file of the eclipse platform feature. It's version should be updated to match the "marketing number" of the release. (Investigating if can be automated, in bug 476075).
Copyright blurbs
The copyright statement comes from two sources. First are the about.properties file, for any "root feature".
But, the copyright in the main "about box" comes from the plugin.properties of the branding bundle for the product.
Note: we intentionally, currently do not use the copyright symbol ('\u00A9', or '©') since it is not part of every code page in every language. See bug 427514#c19 or other sources.