| <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> | |
| <html> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |
| <meta name="GENERATOR" content="Mozilla/4.5 [en] (Win98; I) [Netscape]"> | |
| <meta name="Author" content="Greg Adams"> | |
| <title>Creating product branding</title> | |
| <link rel="stylesheet" href="../default_style.css"> | |
| </head> | |
| <body> | |
| <div align=right><font face="Times New Roman, Times, serif"><font size=-1>Copyright | |
| © 2001 Object Technology International, Inc.</font></font></div> | |
| <div ALIGN=right><table BORDER=0 CELLSPACING=0 CELLPADDING=2 WIDTH="100%" > | |
| <tr> | |
| <td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF"> Eclipse | |
| Corner Article</font></font></b></td> | |
| </tr> | |
| </table></div> | |
| <h1> | |
| <img SRC="idea.jpg" height=86 width=120></h1> | |
| <center> | |
| <h1> | |
| Creating product branding</h1></center> | |
| <blockquote><b>Summary</b> <br> | |
| In this document we will look at the steps needed to create a product. Before | |
| we get too excited hoping the magic of product building will be revealed, | |
| we should first confess that we will focus only on those aspects of the platform | |
| which you will need to modify in order to give your product some branding. | |
| This will include such items as the splash screen, about dialog, the program | |
| executable and so forth. | |
| <p><b>By Greg Adams, OTI</b> <br> | |
| <font size=-1>November 27, 2001</font> | |
| <p>Editor's note: This article describes Eclipse release 1.0. All aspects of | |
| product branding were completely revamped for Eclipse release 2.0; an updated | |
| version of this article is in preparation. | |
| </blockquote> | |
| <hr WIDTH="100%"> | |
| <h2>The high level picture</h2> | |
| <p>You have written all the code and now it is time to bundle up your code with | |
| the platform and change the identity to have your product brand. Before diving | |
| into the details of each step let's take a sneak peak at the big picture and | |
| get a flavor for the kinds of things we'll be doing. The high level steps are | |
| as follows:</p> | |
| <ol> | |
| <li>Replace the product level graphics (e.g. splash screen)</li> | |
| <li>Create graphics for the executable</li> | |
| <li>Create a new executable</li> | |
| <li>Create a product configuration </li> | |
| <li>Create a product plug-in corresponding to the configuration</li> | |
| <li>Update the install information to use your new configuration.</li> | |
| <li>Remove any existing license information</li> | |
| </ol> | |
| <p>As you work through the steps you may notice the occasional <b><img src="TryIt.gif" width="61" height="13"></b>. | |
| These indicate points at which you may want to test out the work you have done | |
| thus far. Once you have completed the test be sure to delete the <i>eclipse/workspace</i> | |
| directory thus ensuring that the next test starts with a fresh state. Once you | |
| have mastered the steps you should do a final run through the steps (starting | |
| with a clean install) but be sure to skip the "try it" steps. These | |
| steps require you to run the platform and consequently will cause information | |
| to be cached. Your actual product production process should not run the platform | |
| runtime.</p> | |
| <p>The steps in this document assume that you have the <i>runtime</i> build of | |
| the platform installed on your machine. In some cases you will require access | |
| to the SDK build but it is important to note that we will be working with and | |
| modifying the platform build. In the remaining sections we assume that you have | |
| a working knowledge of plug-ins.</p> | |
| <p>Before continuing make sure that you have installed a platform runtime build | |
| and installed into it all of your own plug-ins. You should not consider branding/productization | |
| unless you are also including your own plug-ins.</p> | |
| <p>This article is intended to be a guide to help you produce a release. You need | |
| to ensure that you comply with any terms and conditions of the license under | |
| which you received the platform runtime.</p> | |
| <p> </p> | |
| <h2>Replacing the splash screen</h2> | |
| <p>The splash screen (shown while the program starts) is contained in two files | |
| found in the <i>eclipse/splash</i> directory. You must replace both of these | |
| files with your product splash screens. The file <i>splash_basic</i> and <i>splash_full</i> | |
| correspond to low color and high color versions of the splash screen. The low | |
| color splash screen is used only when the display (color) depth is less than | |
| or equal to eight. Typically most displays have sufficient color depth support | |
| to allow the high color splash to be used. </p> | |
| <p><img src="win_only.gif" width="51" height="13"> On Windows® replace the following | |
| two files (in eclipse/splash) with your splash screen files: </p> | |
| <ul> | |
| <li>splash_basic.bmp </li> | |
| <li>splash_full.bmp </li> | |
| </ul> | |
| <p><img src="linux_only.gif" width="51" height="13"> On Linux replace the following | |
| two files (in eclipse/splash) with your splash screen files:</p> | |
| <ul> | |
| <li>splash_basic.xpm</li> | |
| <li>splash_full.xpm</li> | |
| </ul> | |
| <p> </p> | |
| <p><b><img src="TryIt.gif" width="61" height="13"> </b>Start the program and confirm | |
| that your splash screen is shown. Exit the program. Don't forget to delete the | |
| <i>eclipse/workspace </i>directory thus ensuring things are in a completely | |
| fresh state for our next test.</p> | |
| <p> </p> | |
| <h2>Creating the graphics for our executable</h2> | |
| <p>The executable is located in the <i>eclipse/ </i>root directory and the process | |
| for replacing it is platform specific. Start by extracting the file <i>eclipse/launchersrc.zip | |
| </i>found in the SDK and opening the resulting <i>library </i>subdirectory<i>. | |
| </i>In the following sections, we will work with the <i>library/</i> directory | |
| and once we are finished we will copy the resulting executable back to the runtime | |
| platform build. This is the only time you will require access to files found | |
| in the SDK.</p> | |
| <p><b><img src="win_only.gif" width="51" height="13"> </b>On Windows executable | |
| programs can have an associated icon(s). To create our icon we first need to | |
| replace several .BMP graphics located in the <i>library </i>directory<i>. </i>These | |
| graphics represent 16x16, 32x32 and 48x48 pixel versions of both low color and | |
| high color graphics. In the <i>library/ </i>directory replace the following | |
| files:</p> | |
| <ul> | |
| <li>icon16_basic.bmp</li> | |
| <li>icon16_full.bmp</li> | |
| <li>icon32_basic.bmp</li> | |
| <li>icon32_full.bmp</li> | |
| <li>icon48_basic.bmp</li> | |
| <li>icon48_full.bmp</li> | |
| </ul> | |
| <p>Using an appropriate graphics tool (e.g. ICONPRO provided in the MSDN) of your | |
| choice, combine these graphics into a single .ICO (icon) file called<i> eclipse.ico</i> | |
| and replace <i>library/eclipse.ico</i> with your new eclipse.ico file. The <i>eclipse.ico</i> | |
| is referenced by the file<i> library/eclipse.rc</i> which is automatically used | |
| when the executable build script is run. Once the build script has finished | |
| we will have a new program executable with an associated icon.</p> | |
| <p><img src="linux_only.gif" width="51" height="13"> Linux does not directly associate | |
| an icon with an executable program however we can include an icon that users | |
| can use when associating a shortcut with the program. Create yourself an xpm | |
| graphic (representing your program icon) using your favorite graphics editor | |
| and place it into <i>library/icon.xpm. </i>Once we have built the executable | |
| we will copy both the executable and the <i>.xpm </i>file to the <i>eclipse/</i> | |
| root directory of the platform runtime build.</p> | |
| <h2> </h2> | |
| <h2>Creating a new executable program</h2> | |
| <p>Executable icon in hand, it's time to make the executable. We will continue | |
| to work with the <i>library/ </i>directory and once we have created our executable | |
| we will copy it to the <i>eclipse/</i> root directory of the runtime platform | |
| build. The process for creating the program executable is different for each | |
| platform however the <i>library/</i> directory includes build scripts to help | |
| make the process easier.</p> | |
| <h3><b>Preparing the build script</b></h3> | |
| <p><img src="win_only.gif" width="51" height="13"> In the <i>library/</i> directory | |
| you will find the build script <i>build.bat</i>. We will need to edit this build | |
| file to point it to the location of your compiler. To do this, simply uncomment | |
| the following lines (by removing <i>rem</i>) and modify <i>MSVC_HOME </i>to | |
| point to the root directory of your compiler installation.</p> | |
| <blockquote> | |
| <pre>rem IF NOT "%MSVC_HOME%"=="" GOTO MAKE | |
| rem set MSVC_HOME=k:\dev\products\msvc60\vc98 | |
| rem call %MSVC_HOME%\bin\vcvars32.bat</pre> | |
| </blockquote> | |
| <p>This script has been tested with Microsoft® Visual C/C++ Compiler 6.0 however | |
| it is possible that you may need to make additional modifications for your compiler. | |
| If you are using Windows 98 you will also need to remove the line<i> rem Usage: | |
| build <PROGRAM_OUTPUT> <PROGRAM_NAME></i> to work around a known | |
| problem.</p> | |
| <p><img src="linux_only.gif" width="51" height="13"> On Linux, the build script | |
| (<i>build.csh)</i> has been tested against GNU C and C++ Compiler. You typically | |
| should not need to make any changes to the Linux build script.</p> | |
| <p> </p> | |
| <h3><b>Running the build script</b></h3> | |
| <p>The build script takes two arguments, the filename of the executable file to | |
| create and the title (name) of your program. If the program name has spaces | |
| in it (as in the example below) you will need to put double-quotes around it. | |
| </p> | |
| <p>In the example below the program name <i>Cool Stuff </i>will be shown | |
| in the task bar while the program is starting. As we will soon learn the icon | |
| shown in the top left corner of each Workbench window is set separately and | |
| is unrelated to the icons specified for the executable.</p> | |
| <p><img src="win_only.gif" width="51" height="13"> On Windows you can run the | |
| build script (<i>build.bat)</i> as shown below. Prior to running the build script | |
| you should delete any <i>.res</i> files from the <i>library</i> directory. These | |
| files will typically only be present if you have run the build script previously. | |
| This example will create an executable file named <i>cool.exe</i> with the icon | |
| we created above.</p> | |
| <blockquote> | |
| <pre>build cool.exe "Cool Stuff"</pre> | |
| </blockquote> | |
| <p><img src="linux_only.gif" width="51" height="13"> On Linux you can run the | |
| build script (<i>build.csh)</i> as shown below. This example will create an | |
| executable file named <i>cool</i>. On Linux an icon is not automatically associated | |
| with the executable.</p> | |
| <blockquote> | |
| <pre>csh build.csh cool "Cool Stuff"</pre> | |
| </blockquote> | |
| <p> </p> | |
| <h3><b>Replacing the existing executable</b> </h3> | |
| <p>Now that you have your own executable, you can copy it to the <i>eclipse/</i> | |
| root directory of the runtime platform build. Next, delete the current executable | |
| from the <i>eclipse/ </i>root directory. If you forget to delete the existing | |
| executable a user will not know which executable to run so its important not | |
| to forget this little step.</p> | |
| <p><img src="linux_only.gif" width="51" height="13"> On Linux we also need to | |
| copy the <i>icon.xpm </i>(we created above) to the <i>eclipse/ </i>root replacing | |
| the one already found there. </p> | |
| <p> </p> | |
| <p><b><img src="TryIt.gif" width="61" height="13"> </b>Let's give it a whirl! | |
| Go to the<i> eclipse/</i> root directory of the runtime platform build and start | |
| the program by running your executable. Confirm that your executable properly | |
| starts, that your icons and program name are shown in the appropriate places | |
| and that your splash screen is still shown. Don't worry about the icon or title | |
| in the resulting Workbench window we'll fix those in a later section. Exit the | |
| program. Don't forget to delete the <i>eclipse/workspace </i>directory thus | |
| ensuring things are in a completely fresh state for our next test.</p> | |
| <p> </p> | |
| <h2>Create a product configuration</h2> | |
| <p>A product configuration and its corresponding plug-in define several key product | |
| attributes including the icon and title shown in each window, the welcome page, | |
| about dialog information and much more. Product configurations are defined in | |
| the <i>eclipse/install/configurations </i>directory. If you take a glance at | |
| this directory you will likely observe more than one product configuration. | |
| Which one defines the product? The answer lies in the file <i>eclipse/install/install.properties | |
| </i> that specifies which configuration is the <i>dominant</i> configuration. | |
| At any given time only one configuration is the dominant configuration. Each | |
| configuration also has a corresponding plug-in directory. We will start by finding | |
| the dominant configuration and then proceed to create a new product configuration | |
| and corresponding plug-in. Finally we will update the <i>install.properties</i> | |
| file to point to the new configuration. </p> | |
| <h3><b>Discovering the dominant configuration</b> </h3> | |
| <p>Open the file <i>eclipse/install/install.properties</i> and go to the line | |
| with <b>application.configuration = .</b> The information appearing on the right | |
| hand side is the name (id and version) of the current <i>dominant</i> configuration. | |
| Typically the <b>application.configuration</b> has the form <i>xyz_version</i>. | |
| For example <i>xyz_1.0.0</i> indicates the configuration id is <i>xyz</i> and | |
| the version level is <i>1.0.0</i>. </p> | |
| <p>Now that we know the name (id and version) of the dominant configuration take | |
| another look at the <i>eclipse/install/configurations </i>directory<i>. </i>You | |
| should see a subdirectory with the same name as the dominant configuration name. | |
| For example if <i>install.properties </i>had the line <b>application.configuration | |
| = xyz_1.0.0 </b>then we should expect to see a directory <i>xyz_1.0.0</i>. In | |
| addition you should find a plug-in (in <i>eclipse/plugins</i>) with the exact | |
| same name as the configuration directory. </p> | |
| <p>Make a note of the dominant configuration name (id and version) because we'll | |
| want to copy both the configuration and the plug-in directories in the following | |
| sections.</p> | |
| <h3><b>Choosing a name for our configuration</b></h3> | |
| <p>You may recall (from the section on creating the executable) that the name | |
| of our program is "Cool Stuff". To make things easier to follow let's | |
| assume the id we want to give to our configuration and plug-in is <i>org.cool.stuff</i> | |
| and the version number is <i>1.0.0</i>. Consequently our configuration and plug-in | |
| directories will have the name <i>org.cool.stuff_1.0.0</i> and ultimately we | |
| will edit the <i>install.properties</i> file to have application.configuration | |
| <b>= </b>org.cool.stuff_1.0.0. </p> | |
| <h3><b></b> <b>Creating the configuration</b> </h3> | |
| <p>Open the <i>eclipse/install/configurations </i>directory and copy the current | |
| dominant configuration (recall we recorded its name above) to a directory of | |
| your own naming. For our example we need to copy the dominant configuration | |
| to a directory named to <i>eclipse/install/configurations/<b>org.cool.stuff_1.0.0</b></i>. | |
| It is important that you copy the directory, you must not simply rename the | |
| existing dominant configuration directory. </p> | |
| <p>Next edit the file <i>install.xml</i> found in the new configuration directory. | |
| You will need to edit the fields (lines) as follows:</p> | |
| <table width="80%" border="1" cellspacing="0" cellpadding="0"> | |
| <tr bgcolor="#CCCCCC"> | |
| <td width="30%"><b>Field</b></td> | |
| <td width="80%"><b>Editing Instructions</b></td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td width="20%"><b>label</b></td> | |
| <td width="70%">Change this to be the name of your product (e.g. Cool Stuff)</td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td width="20%"><b>id</b></td> | |
| <td width="80%">Change this to match the unique name of your configuration | |
| (e.g. org.cool.stuff)</td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td width="20%"><b>version</b></td> | |
| <td width="80%">Change this to the appropriate version number of your configuration | |
| (e.g. 1.0). Note that 1.0 can be used in place of 1.0.0.</td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td width="20%"><b>provider-name</b></td> | |
| <td width="80%">Change this to be the name of your company.</td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td width="20%"><b>description</b></td> | |
| <td width="80%">Change this to be a description of the configuration.</td> | |
| </tr> | |
| </table> | |
| <p>The following example shows what the<i> install.xml </i>file would look like | |
| for the Cool example. </p> | |
| <blockquote> | |
| <pre><?xml version="1.0" encoding="UTF-8" ?> | |
| <configuration | |
| label="Cool Stuff" | |
| id="org.cool.stuff" | |
| version="1.0" | |
| provider-name="Cool Stuff Company"></pre> | |
| <pre> <description> | |
| The Cool Stuff Configuration | |
| </description><br></configuration></pre> | |
| </blockquote> | |
| <p> </p> | |
| <h2><b>Create a plug-in</b> corresponding to the configuration</h2> | |
| <p>Every configuration has a corresponding plug-in. The name of the plug-in directory | |
| is identical to the name of the configuration directory. Since our configuration | |
| directory was named org.cool.stuff_1.0.0 we will create a plug-in with the same | |
| name. </p> | |
| <p>Open the <i>eclipse/plugins </i>directory and copy the plug-in corresponding | |
| to current dominant configuration (see above) to a directory matching the name | |
| of your configuration (e.g. <i>org.cool.stuff_1.0.0</i>). It is important that | |
| you copy the directory, you must not simply rename the existing dominant configuration | |
| plug-in directory. </p> | |
| <p>Your new plug-in directory should contain the following files. If you do not | |
| see all of these files, you may have copied a regular plug-in directory instead | |
| of the plug-in directory corresponding to the dominant configuration.</p> | |
| <ol> | |
| <ol> | |
| <li>plugin.xml</li> | |
| <li>plugin.properties</li> | |
| <li>about.html</li> | |
| <li>product.ini</li> | |
| <li>product.properties</li> | |
| <li>about_prod.gif</li> | |
| <li>about_prod_basic.gif</li> | |
| <li>prod.gif</li> | |
| <li>prod_basic.gif</li> | |
| <li>welcome.xml</li> | |
| <li>platform.ini</li> | |
| <li>platform.properties</li> | |
| </ol> | |
| </ol> | |
| <p>Files 1-3 you might recognize because they appear in most other plugins. Files | |
| 4-10 are unique to plug-ins corresponding to configurations. These represent | |
| product attribution information including icon and title for Workbench windows, | |
| graphics and text for the about dialog, and the text of the welcome page. Files | |
| 11-12 (<i>platform.ini</i> and <i>platform.properties</i>) are also unique however | |
| these <b>must not</b> be edited.</p> | |
| <h3>Editing the standard files plug-in</h3> | |
| <p>Let's start by modifying files 1-3 which are the three standard files <i>(plugin.xml, | |
| plugin.properties and about.html) </i>found in most plug-ins.</p> | |
| <p><b>plugin.xml</b></p> | |
| <p>Edit the fields of plugin.xml as follows:</p> | |
| <table width="80%" border="1" cellspacing="0" cellpadding="0"> | |
| <tr bgcolor="#CCCCCC"> | |
| <td width="30%"><b>Field</b></td> | |
| <td width="70%"><b>Editing Instructions</b></td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td width="20%"><b>id</b></td> | |
| <td width="80%">Change this to match the id of your configuration (e.g. <i>org.cool.stuff</i>). | |
| Do not include the version number of your configuration.</td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td width="20%"><b>version</b></td> | |
| <td width="80%">Change this to match the version number of your configuration | |
| (e.g. 1.0). Note that 1.0 can be used in place of 1.0.0.</td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td width="20%"><b>Provider-name</b></td> | |
| <td width="80%">Change this to be the name of your company.</td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td width="20%"><b>name</b></td> | |
| <td width="80%">Do not edit this field. It has been externalized and will | |
| edit the plugin.properties file next.</td> | |
| </tr> | |
| </table> | |
| <p>The <i>plugin.xml</i> file for our Cool example should appear as follows:</p> | |
| <blockquote> | |
| <pre><?xml version="1.0" encoding="UTF-8"?> | |
| <plugin | |
| id="org.cool.stuff" | |
| name="%pluginName" | |
| version="1.0" | |
| provider-name="Cool Stuff Company"> | |
| </plugin></pre> | |
| </blockquote> | |
| <p><b>plugin.properties</b></p> | |
| <p>Notice that while editing the <i>plugin.xml</i> file we did not modify the | |
| <b>name</b> field. This is because the name field has been externalized into | |
| <i>plugin.properties</i>. Open <i>plugin.properties</i> and edit the <b>pluginName</b> | |
| field. Our Cool example's <i>plugin.properties</i> file is as follows:</p> | |
| <blockquote> | |
| <pre>pluginName = Cool Stuff Plug-In</pre> | |
| </blockquote> | |
| <p><b>about.html</b></p> | |
| <p> The last file commonly found in most plug-ins is <i>about.html</i>. This HTML | |
| file allows you to provide any arbitrary information about your plug-in or company. | |
| Some plug-in suppliers opt to include links to their company sites. A user can | |
| view a plug-in's about.html by opening the About dialog from the Workbench's | |
| Help menu and clicking "Plugin Info..." to open a dialog listing all | |
| of the installed plug-ins. Selecting a plug-in and clicking "More Info..." | |
| displays the plug-in's about.html.</p> | |
| <p>Edit the about.html file to include any interesting information about your | |
| plug-in.</p> | |
| <p><b><img src="TryIt.gif" width="61" height="13"> </b>We have created a configuration | |
| and its corresponding plug-in. We haven't wired in our configuration but we | |
| can do a quick test to see that our plug-in and its about.html show up correctly | |
| in the Workbench's About dialog. Start the platform and open the About dialog | |
| (from the Workbench's Help menu). Click on the "Plugin Info..." button | |
| and confirm the plug-in name, provider and version number are correct for your | |
| plug-in (i.e. correspond to the values you entered above). Next select the plug-in | |
| and choose "More Info..". and confirm the contents of your about.html | |
| are properly displayed. Exit the program. Don't forget to delete the <i>eclipse/workspace | |
| </i>directory thus ensuring things are in a completely fresh state for our next | |
| test.</p> | |
| <h3><b>Editing the plug-in product files</b></h3> | |
| <p>Plug-in's corresponding to configurations contain two special files, <i>product.ini</i> | |
| and <i>product.properties</i>. These files provide product level information. | |
| The latter of these (<i>product.properties</i>) contains strings externalized | |
| from the <i>product.ini</i>. The configuration plug-in also contains two other | |
| files, <i>platform.ini</i> and <i>platform.properties</i>, these files <b>must | |
| not </b>be modified. These files are reserved for the platform itself.</p> | |
| <p><b>product.ini</b></p> | |
| <p>Although you are allowed to edit any field in product.ini it is strongly recommended | |
| that you follow the advice provided below. There are several fields which are | |
| either unnecessary to modify, or have potentially serious implications if you | |
| modify them (e.g. <b>application</b>). Some fields have been externalized from | |
| <i>product.ini</i> consequently we will edit them by modifying <i>product.properties</i>. | |
| Fields referencing graphics (e.g. product icon, about graphic) do not need to | |
| be altered, because we will replace their corresponding graphic files in subsequent | |
| sections. </p> | |
| <table width="100%" border="1" cellspacing="0" cellpadding="0"> | |
| <tr bgcolor="#CCCCCC"> | |
| <td><b>Field</b></td> | |
| <td><b>Editing Instructions</b></td> | |
| <td><b>Where is it shown</b></td> | |
| </tr> | |
| <tr valign="top" align="left"> | |
| <td><b>name</b></td> | |
| <td>Change this to match the name of your product (e.g. Cool Stuff). If your | |
| product name is lengthy you may want to use a shorter version of it for | |
| this field. The value of this field is shown in the title of Workbench windows.</td> | |
| <td>Workbench windows</td> | |
| </tr> | |
| <tr valign="top" align="left"> | |
| <td>detailedName</td> | |
| <td>Do not edit this field since it has been externalized. We will edit it | |
| by changing <i>product.properties</i>. Typically this field is the same | |
| as the <i>name</i> field however if your product name is lengthy you may | |
| opt to use the <i>name</i> field for a shorter version of the product name.</td> | |
| <td>About dialog</td> | |
| </tr> | |
| <tr valign="top" align="left"> | |
| <td>image</td> | |
| <td>Do not edit this field. We will replace prod.gif with our product graphic.</td> | |
| <td>Workbench windows (icon in top left corner of window)</td> | |
| </tr> | |
| <tr valign="top" align="left"> | |
| <td>image_basic</td> | |
| <td>Do not edit this field. We will replace prod_basic.gif with our product | |
| graphic.</td> | |
| <td>Workbench windows (icon in top left corner of window). This image is only | |
| shown for low color displays.</td> | |
| </tr> | |
| <tr valign="top" align="left"> | |
| <td><b>Version</b></td> | |
| <td>Change this to match the version number of your product. This string is | |
| a "pretty" name (e.g. R1.0, Beta-1) that will appear in the Workbench's | |
| about dialog. It does not have to match the configuration version number | |
| or plug-in version number. </td> | |
| <td>About dialog</td> | |
| </tr> | |
| <tr valign="top" align="left"> | |
| <td>application</td> | |
| <td>Do not edit this field. There are very small set of cases under which | |
| this needs to be edited (e.g. headless product). Before attempting to edit | |
| this field you should thoroughly read the Platform Plug-in Developer Guide. | |
| In addition, modifying this attribute may prevent other third party plug-ins | |
| from running. </td> | |
| <td>N/A</td> | |
| </tr> | |
| <tr valign="top" align="left"> | |
| <td><b>productURL</b></td> | |
| <td>Change this to be your company or product URL (e.g. http://www.cool-stuff.org)</td> | |
| <td>Currently this field is not automatically shown. Consequently many product | |
| teams include a URL in their copyright text (see product.properties below). | |
| </td> | |
| </tr> | |
| <tr valign="top" align="left"> | |
| <td>aboutImage</td> | |
| <td>Do not edit this field. We will replace about_prod.gif with our about | |
| graphic.</td> | |
| <td>About dialog (large graphic in top left corner)</td> | |
| </tr> | |
| <tr valign="top" align="left"> | |
| <td>aboutImage_basic</td> | |
| <td>Do not edit this field. We will replace about_prod_basic.gif with our | |
| graphic.</td> | |
| <td>About dialog (large graphic in top left corner). This image is only shown | |
| for low color displays.</td> | |
| </tr> | |
| <tr valign="top" align="left"> | |
| <td>welcomePage</td> | |
| <td>Do not edit this field. We will replace welcome.xml with our own welcome | |
| page.</td> | |
| <td>Shown in the welcome page.</td> | |
| </tr> | |
| <tr valign="top" align="left"> | |
| <td><b>baseInfosets</b></td> | |
| <td>This field identifies the id's of infosets (documentation books) and the | |
| order they should be shown in the Workbench's help system. You can edit | |
| this list to include the books appropriate to your product, and alter the | |
| order as necessary.</td> | |
| <td>Help perspective and associated views.</td> | |
| </tr> | |
| <tr valign="top" align="left"> | |
| <td><b>defaultPerspectiveId</b></td> | |
| <td>Change this field to be the perspective the Workbench should initially | |
| show. By default the Resources perspective is shown.</td> | |
| <td>N/A</td> | |
| </tr> | |
| <tr valign="top" align="left"> | |
| <td>copyright</td> | |
| <td>Do not edit this field since it has been externalized. We will change | |
| it by editing <i>product.properties</i>.</td> | |
| <td>About dialog.</td> | |
| </tr> | |
| <tr valign="top" align="left"> | |
| <td><b>buildID</b></td> | |
| <td>Change this field to describe the build number of your product build (e.g. | |
| 2.100). The build version is shown in the Workbench's About dialog. </td> | |
| <td>About dialog.</td> | |
| </tr> | |
| </table> | |
| <p>Following is the product.ini file for our Cool example. The fields we have | |
| changed for the purpose of the example have been marked in bold. For the sake | |
| of illustration the PDE infoset has been moved to be the first infoset listed | |
| in <i>baseInfosets. </i>The default perspective has been left unchanged.</p> | |
| <blockquote> | |
| <pre> <b>name</b> = Cool Stuff | |
| detailedName = %detailedName | |
| image = prod.gif | |
| image_basic = prod_basic.gif | |
| <b>version</b> = R1.0 Sneak Peak | |
| application = org.eclipse.ui.workbench | |
| <b>productURL</b> = http://www.cool-and-neat-stuff.org | |
| aboutImage = about_prod.gif | |
| aboutImage_basic = about_prod_basic.gif | |
| welcomePage = welcome.xml | |
| <b>baseInfosets</b> = org.eclipse.pde.doc.user.infoset_Guide,\ | |
| org.eclipse.platform.doc.user.infoset_Guide,\ | |
| org.eclipse.jdt.doc.user.infoset_Guide,\ | |
| org.eclipse.platform.doc.isv.infoset_Guide,\ | |
| org.eclipse.jdt.doc.isv.infoset_Guide | |
| defaultPerspectiveId = org.eclipse.ui.resourcePerspective | |
| copyright = %copyright | |
| <b>buildID</b> = 2.345</pre> | |
| </blockquote> | |
| <p><b>product.properties</b></p> | |
| <p>While we were editing the above product.ini file there were several fields | |
| we skipped over because they had been externalized. The time has come to edit | |
| those fields by editing them in the file <i>product.properties</i> as follows:<br> | |
| </p> | |
| <table width="100%" border="1" cellspacing="0" cellpadding="0"> | |
| <tr bgcolor="#CCCCCC"> | |
| <td width="20%"><b>Field</b></td> | |
| <td width="80%"><b>Editing Instructions</b></td> | |
| <td width="80%"><b>Where is it shown</b></td> | |
| </tr> | |
| <tr> | |
| <td width="20%">detailedName</td> | |
| <td width="80%">Change this to match the name of your product (e.g. Cool Stuff). | |
| </td> | |
| <td width="80%">About dialog</td> | |
| </tr> | |
| <tr> | |
| <td width="20%">copyright</td> | |
| <td width="80%">Change this to be the copyright text for your application. | |
| You can use \n and \ (line continuation) for lengthy copyright messages. | |
| You may also want to include a URL in your copyright text.</td> | |
| <td width="80%">About dialog</td> | |
| </tr> | |
| </table> | |
| <p>The <i>product.properties</i> file for our Cool example might look something | |
| like this. <br> | |
| </p> | |
| <blockquote> | |
| <pre> | |
| copyright = (c) Copyright Cool and Neat Stuff\n\ | |
| \n\ | |
| Visit the website at http://www.cool-and-neat-stuff.org\n\ | |
| detailedName = Cool Stuff for Developers </pre> | |
| </blockquote> | |
| <h3>Editing the welcome page</h3> | |
| <p>The next plug-in file we need to edit is <i>welcome.xml. </i>When the Workbench | |
| first opens you may recall seeing a Welcome page displayed. This page is defined | |
| by the file <i>welcome.xml</i> found in the dominant configuration's corresponding | |
| plug-in. The purpose of the Welcome page is to provide initial introductory | |
| information to help a user get started. Here is the <i>welcome.xml</i> for our | |
| Cool example. For additional information on the types of things you can include | |
| in the <i>welcome.xml</i> consult the Platform Plug-in Develop Guide.</p> | |
| <blockquote> | |
| <pre><?xml version="1.0" encoding="UTF-8" ?> | |
| <welcomePage | |
| title="Welcome to Cool Stuff"> | |
| <intro>This page will help familiarize you with many fun things. | |
| To get started, read the section below and click on the related links. </intro></pre> | |
| <pre><item><b>Create your first cool thing </b> | |
| To begin doing cool things you need to start by creating a cool project | |
| and then creating several cool files. | |
| </item> | |
| </welcomePage></pre> | |
| </blockquote> | |
| <p> </p> | |
| <h3><b>Updating some more graphics</b></h3> | |
| <p>The last thing we need to do with our plug-in is to replace several of the | |
| graphics files. The graphics we are replacing are those referenced from the | |
| <i>product.ini</i> by the fields: image, image_basic, aboutImage and aboutImage_basic. | |
| Files with the suffix "basic" represent low color graphics.</p> | |
| <p>Replace the following graphic files that are used to provide the icon for the | |
| top left corner of every window.</p> | |
| <ul> | |
| <li>prod.gif</li> | |
| <li>prod_basic.gif</li> | |
| </ul> | |
| <p></p> | |
| <p></p> | |
| <p>Replace the following graphic files that are used for the large graphic in | |
| the top left corner of the about dialog.</p> | |
| <ul> | |
| <li>about_prod.gif</li> | |
| <li>about_prod_basic.gif</li> | |
| </ul> | |
| <p></p> | |
| <h2> </h2> | |
| <h2><b>Updating the install.properties to use our configuration</b></h2> | |
| <p>We have our configuration and after a number of edits and file replacements | |
| we hopefully have a corresponding plug-in. Now comes the moment of truth as | |
| we edit the<i> install.properties</i> file to point to our new configuration. | |
| Edit <i>eclipse/install/install.properties </i>and change the <b>application.configuration | |
| </b>line to point to the new configuration. You may recall (from above) the | |
| <b>application.configuration</b> has the form <i>xyz_version</i>. For example | |
| <i>xyz_1.0.0</i> indicates the configuration name is <i>xyz</i> and the version | |
| level is <i>1.0.0</i>. For our Cool example the line will need to be:</p> | |
| <blockquote> | |
| <pre>application.configuration=org.cool.stuff_1.0.0</pre> | |
| </blockquote> | |
| <p>Remove any other lines that may exist in <i>install.properties</i>. If you | |
| have done any of the earlier "try it" tests, you may have additional | |
| lines in <i>install.properties </i>representing cached information. In addition, | |
| if there is a cached file<i> update.cfg</i> you should delete this. There may | |
| be additional files in this directory (also cached by the platform) but you | |
| do not need to worry about them.</p> | |
| <h2> </h2> | |
| <h2>License and notice</h2> | |
| <p>You should check legal notices such as: license.html, notice.html, cpl-v05.html | |
| and the about.html files in the root directory and plugin subdirectories to | |
| make sure they are appropriate for your distribution and that you comply with | |
| them or their terms. We can't tell you what to do here, you need to get your | |
| own legal advice.</p> | |
| <p> </p> | |
| <h2>Wrapping it up</h2> | |
| <p>Now that all the pieces are in place we can run our program executable one | |
| more time. Our Cool example should look something like the screen snapshot below. | |
| </p> | |
| <p align="center"><img src="final.jpg" width="800" height="602"></p> | |
| <p> </p> | |
| <p>Before celebrating the branding of your product you should take a moment to | |
| confirm the following:</p> | |
| <ul> | |
| <li>welcome page is correct</li> | |
| <li>the icon and title shown in the window title bar is correct</li> | |
| <li>the Help pulldown properly indicate the name of the about dialog (e.g. About | |
| Cool Stuff)</li> | |
| <li>the about dialog properly include your graphic, copyright text, version | |
| and build numbers</li> | |
| <li>the about dialog properly includes the platform version information in the | |
| lower half of the dialog</li> | |
| </ul> | |
| Now that you have mastered the steps you should do a final run through the steps | |
| (starting with a clean install) but be sure to skip the "try it" steps. | |
| These steps require you to run the platform and consequently will cause information | |
| to be cached. Your actual product production process should not run the platform | |
| runtime. | |
| <h2> </h2> | |
| <h2>A brief word on NL enablement</h2> | |
| <p>In the previous sections we did not discuss NL (National Language) support | |
| for your product branding. There are two important parts to localizing the product | |
| branding:</p> | |
| <ul> | |
| <li>localizing the configuration's plug-in</li> | |
| <li>localizing the splash screen</li> | |
| </ul> | |
| <p>Configuration plug-ins are localized in a manner similar to the many other | |
| plug-ins you have probably seen. That means creating one or more NL plug-in | |
| fragments to contain the localized information. </p> | |
| <p>To localize the splash screen you will need to create locale subdirectories | |
| under <i>eclipse/splash.</i> The names of these directories follow the standard | |
| Java™ locale naming conventions. For example the platform looks up the splash | |
| screen for USA english locale (en_US) as follow:</p> | |
| <ol> | |
| <li>eclipse\splash\en_US\<image file></li> | |
| <li>eclipse\splash\en\<image file></li> | |
| <li>eclipse\splash\<image file></li> | |
| </ol> | |
| <p>where <image file> is the name of the splash file (e.g. splash_full.bmp | |
| or splash_full.xpm).</p> | |
| <p>For additional information on localizing plug-ins consult the Platform Plug-in | |
| Developer Guide.</p> | |
| <p> </p> | |
| <h2>Product directory</h2> | |
| <p>In the previous sections we have been working in the <i>eclipse/</i> directory. | |
| You are probably asking yourself whether or not you should rename the <i>eclipse</i> | |
| directory. The answer is no. Doing so may prevent future fixes and updates from | |
| installing. The correct approach is to include the <i>eclipse/</i> directory | |
| inside your own product directory. For example our Cool product would look as | |
| follows:</p> | |
| <blockquote> | |
| <p>\cool<br> | |
| \cool\<b>eclipse<br> | |
| </b>\cool\<b>eclipse\cool.exe</b><br> | |
| \cool\product-readme<br> | |
| \cool\.... </p> | |
| </blockquote> | |
| It is also worth noting that the steps we have gone through describe the complete | |
| set of steps you need to follow in order to productize/brand your work. Other | |
| than adding more of your own plug-ins you should not make other modifications | |
| in the <i>eclipse/</i> directory. | |
| <h2>Summary</h2> | |
| <p>We have covered the tasks required to add branding to a product based on the | |
| platform. The process involves rebuilding the executable, replacing a number | |
| of graphics and creating a product configuration and corresponding plug-in. | |
| Once you have mastered the steps you should do a final run through the steps | |
| but be sure to skip the "try it" steps. These steps require you to | |
| run the platform and consequently will cause information to be cached. Your | |
| actual product production process should not run the platform runtime. Here | |
| is a quick checklist (ignoring NL issues) to help refresh your memory on what | |
| we modified.</p> | |
| <table width="80%" border="1" cellspacing="0" cellpadding="0"> | |
| <tr bgcolor="#CCCCCC"> | |
| <td width="20%"><b>Item</b></td> | |
| <td width="40%"><b>Windows</b></td> | |
| <td width="40%"><b>Linux</b></td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td>Splash</td> | |
| <td> | |
| <p>Replace the following:</p> | |
| <ul> | |
| <li>eclipse/splash/splash_basic.bmp</li> | |
| <li>eclipse/splash/splash_full.bmp</li> | |
| </ul> | |
| </td> | |
| <td> | |
| <p>Replace the following: </p> | |
| <ul> | |
| <li>eclipse/splash/splash_basic.xpm</li> | |
| <li>eclipse/splash/splash_full.xpm</li> | |
| </ul> | |
| </td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td>Executable graphics</td> | |
| <td> | |
| <p>Replace the following in <i>library/</i> (obtained from the SDK)</p> | |
| <ul> | |
| <li>icon16_basic.bmp</li> | |
| <li>icon16_full.bmp</li> | |
| <li>icon32_basic.bmp</li> | |
| <li>icon32_full.bmp</li> | |
| <li>icon48_basic.bmp</li> | |
| <li>icon48_full.bmp</li> | |
| </ul> | |
| <p>and build them into single ICO file by replacing:</p> | |
| <ul> | |
| <li>library/eclipse.ico</li> | |
| </ul> | |
| </td> | |
| <td> | |
| <p>Replace the following:</p> | |
| <ul> | |
| <li>eclipse/icon.xpm</li> | |
| </ul> | |
| </td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td>Executable</td> | |
| <td colspan="2"> | |
| <p>Remove existing executable from eclipse/ and replace with your product's | |
| executable program built using the build scripts in <i>library/ </i>of | |
| the SDK<i> </i>. </p> | |
| </td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td>Product configuration</td> | |
| <td colspan="2"> | |
| <p>Copy the dominant configuration directory to eclipse/install/configurations/<i>your_configuration_id_and_version</i></p> | |
| <p>Modify the following files in the new configuration directory</p> | |
| <ul> | |
| <li>install.xml</li> | |
| </ul> | |
| </td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td>Product plug-in</td> | |
| <td colspan="2">Copy the dominant configuration plug-in directory to eclipse/plugins/<i>your_configuration_id_and_version</i></td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td>Standard plug-in files </td> | |
| <td colspan="2"> | |
| <p>Modify the following files in eclipse/plugins/<i>your_configuration_id_and_version</i></p> | |
| <ul> | |
| <li>plugin.xml</li> | |
| <li>plugin.properties</li> | |
| <li>about.html</li> | |
| </ul> | |
| </td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td>Plug-in product files</td> | |
| <td colspan="2"> | |
| <p>Modify the following product files in eclipse/plugins/<i>your_configuration_id_and_version. | |
| </i>These provide product naming, About dialog text and the welcome page.</p> | |
| <ul> | |
| <li>product.ini</li> | |
| <li>product.properties</li> | |
| <li>welcome.xml</li> | |
| </ul> | |
| </td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td>Plug-in product graphics</td> | |
| <td colspan="2"> | |
| <p>Replace the following product graphics files in eclipse/plugins/<i>your_configuration_id_and_version</i>. | |
| These represent the about dialog and the icon shown in the top left corner | |
| of all windows:</p> | |
| <ul> | |
| <li>about_prod.gif</li> | |
| <li>about_prod_basic.gif</li> | |
| <li>prod.gif</li> | |
| <li>prod_basic.gif</li> | |
| </ul> | |
| </td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td>Installation </td> | |
| <td colspan="2">Update eclipse/install/install.properties to reference <i>your_configuration_id_and_version</i></td> | |
| </tr> | |
| <tr align="left" valign="top"> | |
| <td>License</td> | |
| <td colspan="2">You should check legal notices such as: license.html, notice.html, | |
| cpl-v05.html and the about.html files in the root directory and plugin subdirectories | |
| to make sure they are appropriate for your distribution and that you comply | |
| with them or their terms. We can't tell you what to do here, you need to | |
| get your own legal advice.</td> | |
| </tr> | |
| </table> | |
| <p><small>Java and all Java-based trademarks and logos are trademarks or registered | |
| trademarks of Sun Microsystems, Inc. in the United States, other countries, or | |
| both.</small></p> | |
| <p><small>Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.</small></p> | |
| </body> | |
| </html> |