Customizing a product

Customizing a Product

There are many customizable aspects of a product, such as its splash screen, about dialog text, window icons, etc. Most of these customizations are defined in the contribution to the org.eclipse.core.runtime.products extension point.

Let's look at how some of the more common customizable elements are defined.

About Dialogs

The platform "about" dialog is shown whenever the user selects Help > About in the workbench menu.

About dialog

The upper part of the about dialog shows product level information while the lower part details the features (if any) and plug-ins installed. The feature details (branding if you will) are supplied using about.ini, about.properties and about.html files in the plug-in associated with the feature. This information is displayed when the user requests feature details and selects a particular feature.

The product branding (top half of the dialog) is specify by extension properties that describe the text and images that are shown in this dialog. For example, the following extract from the Eclipse Platform product declaration.

	<property
		name="aboutText"
		value="%aboutText"/>
	<property
		name="aboutImage"
		value="icons/eclipse_lg.png"/>
	</product>

aboutText specifies the text to show in the about dialog
aboutImage specifies an image that should be used in the about dialog. Large images will be shown by themselves, and smaller images will be shown along with the about text.

See IProductConstants for more information about these properties.

Window Images

A 16x16 pixel color image can be used to brand windows created by the product. It will appear in the upper left hand corner of product windows. It is specified in the windowImage attribute in the products extension definition. Alternatively, the windowImages attribute can be used to describe an array of images of different sizes that should be used in the upper left hand corner.

	<property
		name="windowImages"
		value="icons/eclipse.png,icons/eclipse32.png"/>

The windowImages property supercedes the windowImage property if both are specified.

Welcome Page

Products using the Eclipse 2.1 welcome page mechanism can specify the name and location of their welcome page file in the welcomePage property.

	<property
		name="welcomePage"
		value="$nl$/welcome.xml"/>

Use of this property is now discouraged in favor of the org.eclipse.ui.intro extension point. See Welcome/Intro support for more detail about the new welcome/intro mechanisms.

Preferences Defaults

The preferenceCustomization property can be used to specify a file containing default preference values for the product.

	<property
		name="preferenceCustomization"
		value="plugin_customization.ini"/>

This file is a java.util.Properties format file. Typically this file is used to set the values for preferences that are published as part of a plug-in's public API. That is, you are taking a risk if you refer to preferences that are used by plug-ins but not defined formally in the API.

Dialog Settings Defaults

If the custom preferences file is used as described above, setting the org.eclipse.ui/default_dialog_settings_rootUrl property in that file allows to specify a folder containing default dialog settings values for product plug-ins. The property value must be a valid URL.
The preference can be set using the following URL schemes.

org.eclipse.ui/default_dialog_settings_rootUrl=http://mycompany/dialog_settings
org.eclipse.ui/default_dialog_settings_rootUrl=file:/etc/mycompany/dialog_settings
org.eclipse.ui/default_dialog_settings_rootUrl=platform:/plugin/my.company.bundle/dialog_settings

The directory specified by this URL must contain folders with dialog_settings.xml files for every plug-in to be customized, each directory with the symbolic name of concrete plug-in, such as such as dialog_settings/org.eclipse.ui.ide/dialog_settings.xml, dialog_settings/org.eclipse.ui.navigator/dialog_sttings.xml, dialog_settings/my.company.bundle/dialog_settings.xml... Those dialog_settings.xml files for each bundle can be retrieved from a running instance of the Eclipse Platform, under the folder ${workspace}/.metadata/.plugins. You can simply copy-paste those existing files into the directory set as value for the org.eclipse.ui/default_dialog_settings_rootUrl preference.

Splash Screens

The product splash screen is specified in the config.ini which is located underneath the product's configuration directory. The osgi.splashPath property in this file describes places to search for a file called splash.bmp. The osgi.splashLocation property identifes a complete and exact path to the splash screen file to use. Specifying a splash path allows for locale specific splash screens to be used as the given search path can indicate several plug-ins or fragments to search as well as $nl$ style paths. See the platform SDK's config.ini file for a complete description of properties that can be configured in this file. The image should be supplied in 24-bit color BMP format (RGB format) and should be approximately 500x330 pixels in size.

The location, size, and color of the progress bar and progress message shown in the splash screen during startup can be configured using the properties startupProgressRect, startupMessageRect, and startupForegroundColor. See IProductConstants for more information about these properties. Note that by default, no progress will be reported at startup. To enable startup progress reporting, set the following preference to true, for example in the preference customization file: IWorkbenchPreferenceConstants.SHOW_PROGRESS_ON_STARTUP