platform-update-home/doc/eclipse_about_dialogs.html
Parent Directory
| 
Revision Log
Revision 1.1 - (view) (download) (as text)
| 1 : | jeem | 1.1 | <html> |
| 2 : | |||
| 3 : | <head> | ||
| 4 : | <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> | ||
| 5 : | <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> | ||
| 6 : | <meta name="ProgId" content="FrontPage.Editor.Document"> | ||
| 7 : | <title>Eclipse About Dialogs</title> | ||
| 8 : | </head> | ||
| 9 : | |||
| 10 : | <body> | ||
| 11 : | |||
| 12 : | <h1>Eclipse About Dialogs</h1> | ||
| 13 : | <p>Last revised 14:30 Friday May 17, 2002</p> | ||
| 14 : | <p>This note describes how Eclipse "about" dialogs work.</p> | ||
| 15 : | <h2>What product developers need to know</h2> | ||
| 16 : | <p>Eclipse has an "about" dialog that is shown to the user when they | ||
| 17 : | select the "About" item from the workbench | ||
| 18 : | "Help" menu. The workbench constructs this dialog using | ||
| 19 : | information supplied by features and plug-ins. Product-specific information comes from the product's primary | ||
| 20 : | feature; information about individual features and plug-ins come from each | ||
| 21 : | installed and configured feature and plug-in. The "about" dialog is adjusted | ||
| 22 : | automatically as new features and plug-ins are added, or existing ones upgraded.</p> | ||
| 23 : | All plug-ins must have a file named "<code>about.html</code>" in the plug-in | ||
| 24 : | directory containing a description of the plug-in. This page is shown (in a | ||
| 25 : | standard web browser) when the user explicitly requests information about the | ||
| 26 : | plug-in from the plug-in "about" dialog. | ||
| 27 : | <p>Features plug-ins contain additional files ("<code>about.ini</code>" | ||
| 28 : | together with optional companion files "<code>about.properties</code>" | ||
| 29 : | and | ||
| 30 : | "<code>about.mappings</code>" plus various image files) that provide | ||
| 31 : | text and images that are presented on the "about" dialogs.</p> | ||
| 32 : | <p>A feature's "about" information is given by properties in the | ||
| 33 : | "<code>about.ini</code>" file located within the feature's <i>plug-in</i>. This is | ||
| 34 : | a <a href="http://java.sun.com/j2se/1.3/docs/api/java/util/Properties.html">java.io.Properties</a> | ||
| 35 : | format file (ISO 8859-1 character encoding with \u<i>xxxx </i>Unicode escapes), | ||
| 36 : | with the following keys:</p> | ||
| 37 : | <ul> | ||
| 38 : | <li>"<code>aboutText</code>" - A multi-line text description of the feature | ||
| 39 : | containing copyright, license terms, license | ||
| 40 : | registration info, etc. URLs found in text are presented as links. Line | ||
| 41 : | breaks are indicated by "<code>\n</code>"; lines should be | ||
| 42 : | no longer than 75 characters each, and there is a limit of 15 lines. | ||
| 43 : | This information is shown in the main "about" dialog (used | ||
| 44 : | in conjunction with a half-sized image), and on the secondary "about" | ||
| 45 : | dialog describing individuals feature. All features | ||
| 46 : | are required to have this property.</li> | ||
| 47 : | <li>"<code>windowImage</code>" - A 16x16 pixel color image used to brand | ||
| 48 : | windows created by a product. The value of this property is a plug-in-relative path to an image | ||
| 49 : | file. This property is only required for primary features; other | ||
| 50 : | features may omit it.</li> | ||
| 51 : | <li>"<code>featureImage</code>" - A 32x32 pixel color image used | ||
| 52 : | as an icon for this feature. The value of this property is a plug-in-relative path to an image | ||
| 53 : | file. This image is shown on the "about" dialog describing | ||
| 54 : | individual features, and is also used on the main "about" dialog | ||
| 55 : | to indicate that the feature is present. This property is | ||
| 56 : | optional. Related features supplied by a single provider should | ||
| 57 : | contain copies of the identical image file; this allows duplicate | ||
| 58 : | images to be eliminated.</li> | ||
| 59 : | <li>"<code>aboutImage</code>" - A large color image that appears in the | ||
| 60 : | main "about" dialog for a product. The value of this | ||
| 61 : | property is a plug-in-relative path to an image file. This property | ||
| 62 : | is only | ||
| 63 : | required for primary features; other features should omit it. Both | ||
| 64 : | graphic-and-text, and graphic only layouts are supported, depending | ||
| 65 : | on the size of image provided. A half-size image of up to 250 pixels | ||
| 66 : | wide by 330 pixels high is shown on the main "about" dialog | ||
| 67 : | with text ("<code>aboutText</code>" property) beside it. A | ||
| 68 : | full-size image of up to 500 pixels wide by 330 pixels high is shown without | ||
| 69 : | text.</li> | ||
| 70 : | <li>"<code>welcomePage</code>" - A welcome page. The | ||
| 71 : | value of this property is a plug-in-relative path to an XML-format | ||
| 72 : | file containing the feature's welcome page. This property is | ||
| 73 : | recommended for all major features; other features may omit it.</li> | ||
| 74 : | <li>"<code>welcomePerspective</code>" - The preferred | ||
| 75 : | perspective in which to show the welcome page. The | ||
| 76 : | value of this property is a workbench perspective id. This property is | ||
| 77 : | recommended for features with welcome pages that show better in the | ||
| 78 : | context of the feature's views and editors. Features that do not | ||
| 79 : | have welcome pages, or have no strong opinion where the welcome | ||
| 80 : | pages is shown, should omit it.</li> | ||
| 81 : | <li>"<code>appName</code>" - A short string used to | ||
| 82 : | associate a name with the application on platforms where this makes | ||
| 83 : | sense. In operating environments with the Motif window system, the | ||
| 84 : | value is used for Motif resource lookup (see xrdb and related). In | ||
| 85 : | addition, on the CDE window manager (used on Solaris and AIX), this | ||
| 86 : | is the name which shows up under the icon for windows which are | ||
| 87 : | minimized to the desktop. This property is required for primary features; | ||
| 88 : | other features may omit it.</li> | ||
| 89 : | </ul> | ||
| 90 : | <p>More generally, every plug-in (not just feature plug-ins) should have an | ||
| 91 : | "<code>about.html</code>" file containing information about that plug-ins.</p> | ||
| 92 : | <p>Translatable strings in "<code>about.ini</code>" (the "<code>aboutText</code>" | ||
| 93 : | and "<code>appName</code>" properties) should be extracted into a | ||
| 94 : | companion "<code>about.properties</code>" file (using "<code>%<i>var</i></code>" as | ||
| 95 : | the value in "<code>about.ini</code>" paired with an entry for the key "<i><code>var</code></i>" | ||
| 96 : | in the "<code>about.properties</code>" file; analogous to the way translatable strings in | ||
| 97 : | "<code>plugin.xml</code>" are extracted to "<code>plugin.properties</code>"). The | ||
| 98 : | "<code>about.properties</code>" file is also a <a href="http://java.sun.com/j2se/1.3/docs/api/java/util/Properties.html">java.io.Properties</a> | ||
| 99 : | format file (ISO 8859-1 character encoding with \u<i>xxxx </i>Unicode escapes). | ||
| 100 : | Various translations of the "<code>about.properties</code>" file are located in | ||
| 101 : | NL-specific subdirectories; for example, for the "<code>fr_FR_EURO</code>" locale, | ||
| 102 : | the file would be found in "<code>nl/fr/FR/EURO/about.properties</code>" located | ||
| 103 : | within the feature's plug-in (possibly within a plug-in fragment).</p> | ||
| 104 : | <p>Translated image files are also looked for in NL-specific subdirectories | ||
| 105 : | within the feature plug-in or fragment thereof.</p> | ||
| 106 : | <p>There is an additional mechanism for supplying values for fill-in fields for the "<code>aboutText</code>" | ||
| 107 : | property. The file, named "<code>about.mappings</code>", is typically created | ||
| 108 : | or appended to when a feature is installed and | ||
| 109 : | contains install-time information such as the license | ||
| 110 : | key and the name of the licensed user. The | ||
| 111 : | "<code>about.mappings</code>" file is also a <a href="http://java.sun.com/j2se/1.3/docs/api/java/util/Properties.html">java.io.Properties</a> | ||
| 112 : | format file (ISO 8859-1 character encoding with \u<i>xxxx </i>Unicode escapes). | ||
| 113 : | The keys are integers: "<code>0</code>", "<code>1</code>", etc. | ||
| 114 : | The value of "<code>0</code>" is substituted for the substring "<code>{0}</code>", | ||
| 115 : | in standard java.text.MessageFormat fashion. The "<code>about.mappings</code>" | ||
| 116 : | file is only required when the "<code>aboutText</code>" | ||
| 117 : | property contains fill-in fields.</p> | ||
| 118 : | <p>Example:</p> | ||
| 119 : | <p>File <code>about.ini</code> (this file does not get translated):</p> | ||
| 120 : | <blockquote> | ||
| 121 : | <p><code>appName=%appName<br> | ||
| 122 : | aboutText=%blurb<br> | ||
| 123 : | windowImage=acme-16.gif<br> | ||
| 124 : | featureImage=acme-32.gif<br> | ||
| 125 : | aboutImage=about-acme.gif<br> | ||
| 126 : | welcomePage=acme-welcome.xml<br> | ||
| 127 : | welcomePerspective=org.eclipse.ui.resourcePerspective<br> | ||
| 128 : | </code></p> | ||
| 129 : | </blockquote> | ||
| 130 : | <p>File <code>about.properties</code> (this file gets translated):</p> | ||
| 131 : | <blockquote> | ||
| 132 : | <p><code>appName=Anvil<br> | ||
| 133 : | blurb=\<br> | ||
| 134 : | Acme Anvil 1.0.0 (build {0})\n\<br> | ||
| 135 : | Product id: {1}\n\<br> | ||
| 136 : | This | ||
| 137 : | product licensed to {2}\n\<br> | ||
| 138 : | Visit our web site at http://acme.example.com<br> | ||
| 139 : | </code></p> | ||
| 140 : | </blockquote> | ||
| 141 : | <p>File <code>about.mappings</code> (this file does not get translated):</p> | ||
| 142 : | <blockquote> | ||
| 143 : | <p><code>0=887<br> | ||
| 144 : | 1=T42-24T-ME4U-U4ME<br> | ||
| 145 : | 2=Wile E. Coyote</code></p> | ||
| 146 : | </blockquote> | ||
| 147 : | <h2>What product developers do not need to know</h2> | ||
| 148 : | <p><b>N.B. The details in this section are not Eclipse platform API, and may | ||
| 149 : | change over time. Do not rely on anything described in this section.</b></p> | ||
| 150 : | <p>The "about" dialog presents information at three levels: product, | ||
| 151 : | feature, and plug-in. Product information appears front-and-center on the main | ||
| 152 : | "about" dialog; this information comes from the product's primary | ||
| 153 : | feature plug-in. Feature information appears on a second dialog containing a table | ||
| 154 : | of all configured features. Plug-in information appears on a third dialog containing a table of all configured plug-ins.</p> | ||
| 155 : | <p>The main dialog is designed to give primary billing to the product, and | ||
| 156 : | secondary billing to other features. The product gets most of the screen real | ||
| 157 : | estate to show a large graphic, or a half-sized graphic plus text with embedded | ||
| 158 : | hyperlinks. Underneath the product's area are a bar of 32x32 images for the | ||
| 159 : | various other features. Selecting one of the feature images opens the second dialog | ||
| 160 : | feature dialogs and selects the corresponding feature in the list. | ||
| 161 : | Duplicate images are eliminated (based on comparing CRC-32 of the image file | ||
| 162 : | bytes). The feature images are ordered by feature id. There are buttons at | ||
| 163 : | bottom of the main dialog to allow the user to drill down to find out about | ||
| 164 : | individual features and plug-ins.</p> | ||
| 165 : | <p>The features dialog has a table of features; the columns are provider name, | ||
| 166 : | feature name, and feature version. Selecting any of the features shows the | ||
| 167 : | feature's 32x32 image ("<code>featureImage</code>" property) and blurb ("<code>aboutText</code>" | ||
| 168 : | property) in the area below the table (room for 15 lines, 75 characters per | ||
| 169 : | line). URL in the text look | ||
| 170 : | and act like standard hyperlinks. The table is ordered alphabetically by | ||
| 171 : | provider name first and then by feature name; this keeps each provider's | ||
| 172 : | features together.</p> | ||
| 173 : | <p>The plug-ins dialog has a table of plug-ins; the columns are provider name, | ||
| 174 : | plug-in name, and plug-in version. Selecting any of the plug-ins opens a web | ||
| 175 : | browser showing the plug-in's "<code>about.html</code>" page.</p> | ||
| 176 : | <p>The workbench has a Help -> "Getting Started" menu item that | ||
| 177 : | opens a dialog which presents a list of all features with a welcome page ("<code>welcomePage</code>" | ||
| 178 : | property in feature's plug-in's <code>about.ini</code> file) and affords the | ||
| 179 : | user a way to make a single selection. The selected feature's preferred | ||
| 180 : | perspective (if one is specified by the "<code>welcomePerspective</code>" | ||
| 181 : | property in the feature's plug-in's <code>about.ini</code> file) is then opened | ||
| 182 : | and the feature's welcome page is presented in a special editor.<br> | ||
| 183 : | </p> | ||
| 184 : | |||
| 185 : | </body> | ||
| 186 : | |||
| 187 : | </html> | ||
| 188 : |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |