Eclipse About Dialogs

Last revised 14:30 Friday May 17, 2002

This note describes how Eclipse "about" dialogs work.

What product developers need to know

Eclipse has an "about" dialog that is shown to the user when they select the "About" item from the workbench "Help" menu. The workbench constructs this dialog using information supplied by features and plug-ins. Product-specific information comes from the product's primary feature; information about individual features and plug-ins come from each installed and configured feature and plug-in. The "about" dialog is adjusted automatically as new features and plug-ins are added, or existing ones upgraded.

All plug-ins must have a file named "about.html" in the plug-in directory containing a description of the plug-in. This page is shown (in a standard web browser) when the user explicitly requests information about the plug-in from the plug-in "about" dialog.

Features plug-ins contain additional files ("about.ini" together with optional companion files "about.properties" and "about.mappings" plus various image files) that provide text and images that are presented on the "about" dialogs.

A feature's "about" information is given by properties in the "about.ini" file located within the feature's plug-in. This is a java.io.Properties format file (ISO 8859-1 character encoding with \uxxxx Unicode escapes), with the following keys:

"aboutText" - A multi-line text description of the feature containing copyright, license terms, license registration info, etc. URLs found in text are presented as links. Line breaks are indicated by "\n"; lines should be no longer than 75 characters each, and there is a limit of 15 lines. This information is shown in the main "about" dialog (used in conjunction with a half-sized image), and on the secondary "about" dialog describing individuals feature. All features are required to have this property.
"windowImage" - A 16x16 pixel color image used to brand windows created by a product. The value of this property is a plug-in-relative path to an image file. This property is only required for primary features; other features may omit it.
"featureImage" - A 32x32 pixel color image used as an icon for this feature. The value of this property is a plug-in-relative path to an image file. This image is shown on the "about" dialog describing individual features, and is also used on the main "about" dialog to indicate that the feature is present. This property is optional. Related features supplied by a single provider should contain copies of the identical image file; this allows duplicate images to be eliminated.
"aboutImage" - A large color image that appears in the main "about" dialog for a product. The value of this property is a plug-in-relative path to an image file. This property is only required for primary features; other features should omit it. Both graphic-and-text, and graphic only layouts are supported, depending on the size of image provided. A half-size image of up to 250 pixels wide by 330 pixels high is shown on the main "about" dialog with text ("aboutText" property) beside it. A full-size image of up to 500 pixels wide by 330 pixels high is shown without text.
"welcomePage" - A welcome page. The value of this property is a plug-in-relative path to an XML-format file containing the feature's welcome page. This property is recommended for all major features; other features may omit it.
"welcomePerspective" - The preferred perspective in which to show the welcome page. The value of this property is a workbench perspective id. This property is recommended for features with welcome pages that show better in the context of the feature's views and editors. Features that do not have welcome pages, or have no strong opinion where the welcome pages is shown, should omit it.
"appName" - A short string used to associate a name with the application on platforms where this makes sense. In operating environments with the Motif window system, the value is used for Motif resource lookup (see xrdb and related). In addition, on the CDE window manager (used on Solaris and AIX), this is the name which shows up under the icon for windows which are minimized to the desktop. This property is required for primary features; other features may omit it.

More generally, every plug-in (not just feature plug-ins) should have an "about.html" file containing information about that plug-ins.

Translatable strings in "about.ini" (the "aboutText" and "appName" properties) should be extracted into a companion "about.properties" file (using "%var" as the value in "about.ini" paired with an entry for the key "var" in the "about.properties" file; analogous to the way translatable strings in "plugin.xml" are extracted to "plugin.properties"). The "about.properties" file is also a java.io.Properties format file (ISO 8859-1 character encoding with \uxxxx Unicode escapes). Various translations of the "about.properties" file are located in NL-specific subdirectories; for example, for the "fr_FR_EURO" locale, the file would be found in "nl/fr/FR/EURO/about.properties" located within the feature's plug-in (possibly within a plug-in fragment).

Translated image files are also looked for in NL-specific subdirectories within the feature plug-in or fragment thereof.

There is an additional mechanism for supplying values for fill-in fields for the "aboutText" property. The file, named "about.mappings", is typically created or appended to when a feature is installed and contains install-time information such as the license key and the name of the licensed user. The "about.mappings" file is also a java.io.Properties format file (ISO 8859-1 character encoding with \uxxxx Unicode escapes). The keys are integers: "0", "1", etc. The value of "0" is substituted for the substring "{0}", in standard java.text.MessageFormat fashion. The "about.mappings" file is only required when the "aboutText" property contains fill-in fields.

Example:

File about.ini (this file does not get translated):

appName=%appName aboutText=%blurb windowImage=acme-16.gif featureImage=acme-32.gif aboutImage=about-acme.gif welcomePage=acme-welcome.xml welcomePerspective=org.eclipse.ui.resourcePerspective

File about.properties (this file gets translated):

appName=Anvil blurb=\ Acme Anvil 1.0.0 (build {0})\n\ Product id: {1}\n\ This product licensed to {2}\n\ Visit our web site at http://acme.example.com

File about.mappings (this file does not get translated):

0=887 1=T42-24T-ME4U-U4ME 2=Wile E. Coyote

What product developers do not need to know

N.B. The details in this section are not Eclipse platform API, and may change over time. Do not rely on anything described in this section.

The "about" dialog presents information at three levels: product, feature, and plug-in. Product information appears front-and-center on the main "about" dialog; this information comes from the product's primary feature plug-in. Feature information appears on a second dialog containing a table of all configured features. Plug-in information appears on a third dialog containing a table of all configured plug-ins.

The main dialog is designed to give primary billing to the product, and secondary billing to other features. The product gets most of the screen real estate to show a large graphic, or a half-sized graphic plus text with embedded hyperlinks. Underneath the product's area are a bar of 32x32 images for the various other features. Selecting one of the feature images opens the second dialog feature dialogs and selects the corresponding feature in the list. Duplicate images are eliminated (based on comparing CRC-32 of the image file bytes). The feature images are ordered by feature id. There are buttons at bottom of the main dialog to allow the user to drill down to find out about individual features and plug-ins.

The features dialog has a table of features; the columns are provider name, feature name, and feature version. Selecting any of the features shows the feature's 32x32 image ("featureImage" property) and blurb ("aboutText" property) in the area below the table (room for 15 lines, 75 characters per line). URL in the text look and act like standard hyperlinks. The table is ordered alphabetically by provider name first and then by feature name; this keeps each provider's features together.

The plug-ins dialog has a table of plug-ins; the columns are provider name, plug-in name, and plug-in version. Selecting any of the plug-ins opens a web browser showing the plug-in's "about.html" page.

The workbench has a Help -> "Getting Started" menu item that opens a dialog which presents a list of all features with a welcome page ("welcomePage" property in feature's plug-in's about.ini file) and affords the user a way to make a single selection. The selected feature's preferred perspective (if one is specified by the "welcomePerspective" property in the feature's plug-in's about.ini file) is then opened and the feature's welcome page is presented in a special editor.