When the root node Eclipse Platform is selected, you will see some additional functions listed on the right side of the window. By clicking the Revert to Previous hyperlink you can return to the state of the platform before you applied the last change to the configuration. If you have previously added features by simply unpacking them into the \eclipse\ root folder, the Process Detected Changes hyperlink appears. By clicking this hyperlink you can perform the missing installation steps for such a feature. Install Handlers The Eclipse Update Manager can be extended via so-called install handlers. These are Java classes that implement the interface IInstallHandler from the package org.eclipse.update.core (usually they extend the standard implementation BaseInstallHandler). The methods of such a class are called at specific points of the installation or update process and can perform specific actions. You can predefine an install handler as a global install handler. This is done in the manifest file plugin.xml of a suitable plug-in at the extension point org.eclipse.update.core .installHandlers. Alternatively, you can include an install handler in the installation archive. However, in this case, they can be used only within the current installation (a local install handler). If you want to use an install handler during the installation of a feature, you must declare it on the Advanced page of the feature manifest feature.xml (see the section “Creating and Editing Features”). There you specify, in the Library field, the name of the archive containing the install handler. In the Handler field, you specify the name of the IInstallHandler class. If you use a global instead of a local install handler, the Library field remains empty and the Handler field specifies the identification under which the global install handler was installed. A typical application of install handlers is for the installation of resources outside the Eclipse platform, for example, if you want to deploy a specific Java Runtime Environment. Internationalizing Products I am wary of writing anything about this topic, because there is an excellent article about international- ization by Dan Kehn, Scott Fairbrother, and Cam-Thu Le on www.eclipse.org. A short overview should therefore be sufficient. A practical example is given in the section “Internationalizing the Spell Checker” of Chapter 13. Internationalization is often understood as merely translating texts presented to the end user into a national language. This is certainly an important aspect of internationalization, but it is not the only one. For example, the meaning of images may differ from culture to culture and so the images should also be adapted to the target culture. You probably are aware of the confusion that date formats (European vs. U.S.) can cause. But the placement of GUI elements may also differ from culture to culture. Countries such as the Arabic nations and Israel, for example, read from right to left, and many Asiatic countries read from top to bottom. A good example of how things can go wrong was an advertisement for a new detergent in Arabic countries. It read: “Big effect in very little time” and displayed the dirty laundry on the left and the clean laundry on the right! 401 Developing Your Own Eclipse-Based Products 14_020059_ch12.qxd 10/8/04 11:31 AM Page 401 Similarly, people may have different expectations of where important form elements should be positioned. The various lengths of text constants in different languages may also influence the layout of screen masks. Despite these layout problems, I will concentrate here on text elements in different languages. Internationalizing other items such as images and icons as well as currency and date formats can often be achieved by mapping them onto text strings (image name, format string). Text Constants in Programs The simplest case is the internationalization of text constants in programs. In the Java source editor, Eclipse offers excellent support for this with the context function Source > Externalize Strings. This wiz- ard creates a list with all string constants used in a compilation unit. Afterward, you can sort these string constants into three different categories: ❑ Translate. In this case the string constant is moved to a properties file. In the source code, the string constant is replaced with a call to an access method. This method fetches the string con- stant at runtime from the properties file with the help of a specified key. In addition, the source line is suffixed with a comment that looks like this: //$NON-NLS-1$ This comment indicates that the string constant (now the key) must not be analyzed when the function Externalize Strings is executed again. For example, the instruction replaceAction.setText("Replace"); is translated into replaceAction.setText Messages.getString("SpellCorrectionView.Replace_5")); //$NON-NLS-1$ ❑ Never Translate. The string constant is equipped with a // $NON-NLS-…$ comment, so that it is not analyzed in future invocations of the function Externalize Strings. For example manager.add(new Separator("Additions")); is translated into manager.add(new Separator("Additions")); //$NON-NLS-1$ ❑ Skip. Nothing is changed. The string constant is offered for externalization in future invocations of the function Externalize Strings. The wizard performs all the selected replacements in the source file. It also creates a properties file within the current package that contains the externalized string constants. It also creates a Messages class that organizes access to the file via the getString() method. 402 Chapter 12 14_020059_ch12.qxd 10/8/04 11:31 AM Page 402 All that remains to do is to translate the properties file into the target language. If you use the Java nam- ing convention basename_lang_region_variant.properties for the properties file, the Message class will automatically use the correct properties file, depending on the national language of the target host platform. You can then add new languages in the form of new properties files without recompiling a single Java class. In some cases, it may be necessary to embed program-generated values into the string constants. This can be done with the help of parameters. These are defined in the string literals in the properties file, in the following way: Editor.save.SVG.error=Error saving SVG file {0} in folder {1} If you use such parameters, it is a good idea to extend the Messages class with a parameterized variant of the method getString(): public static String getString(String key, Object[] params) { if (params == null) return getString(key); try { return java.text.MessageFormat.format(getString(key), params); } catch (Exception e) { return "!"+key+"!"; } } Text Constants in Manifest Files To internationalize the various manifest files such as plugin.xml, feature.xml, fragment.xml, site.xml, about.ini, etc. requires a bit more work, because there is no tool support for this task. Here, you need to create a corresponding properties file for each of these files: plugin.properties, feature.properties, site.properties, about.properties, etc. The exception is fragment.xml. Instead of fragment.properties, the file plugin.properties is used. In the original file, replace the translatable string constants with key strings that are identified via a pre- fixed % character. In the corresponding properties file, specify the key definition. You can translate these files into the target language afterward, as discussed in the previous section. Here is an example of the definition of an Action Set in the manifest file plugin.xml: label="Check spelling" You would change this into label="%checkSpelling" and include in the plugin.properties file the line checkSpelling=Check spelling 403 Developing Your Own Eclipse-Based Products 14_020059_ch12.qxd 10/8/04 11:31 AM Page 403 Help Texts and Cheat Sheets In the case of help pages and Cheat Sheets this approach is not suitable. Instead, you need to translate the whole page. You must create a separate folder for each language in which to store the translated pages. At runtime, the correct folder is selected by evaluating substitution variables. Eclipse understands four different substitution variables that can modify library paths: os This variable is replaced by a token representing the current operation system (linux, macosx, qnx, solaris, win32). ws This variable is replaced by a token representing the current windowing system (carbon, gtk, motif, photon, win32). nl This variable is replaced by the current Java locale. arch This variable is replaced by a token representing the current processor architecture (PA_RISC, ppc, sparc, x86). When you want to test a plug-in that uses these variables, you can set the variables under Window > Preference > Plug-in Development > Target Environment. For example, if you specify a Cheat Sheet (see the section “The Help System” in Chapter 11) in plugin.xml, you can use a substitution variable for the folder name: contentFile="$nl/vedit.xml" During execution, the variable $nl is replaced by the current locale, for example by DE_de. The Cheat Sheet is then fetched from DE_de/vedit.xml. This works quite similarly for help pages, too. Here you would translate not only the HTML pages but also the table of contents (toc.xml) and the context associations (contexts.xml), since these files contain references as well as display texts. References to toc.xml and contexts.xml (for example, from plugin.xml) would then be prefixed with $nl/. This is normally not required for the references specified in toc.xml and contexts.xml, since these references are usually specified relative to the current location. Unfortunately, this approach has a severe disadvantage: if a specific language package is not available, Eclipse will simply show nothing instead of the standard English version. Fortunately, there is an alter- native, which works without substitution variables. This alternative approach relies solely on naming conventions. If you want, for example, to create help pages and Cheat Sheets in the German language, you would store them under the directory nl/de (for all German language areas) and nl/de/DE (for Germany only). At runtime, Eclipse evaluates the Locale information of the JVM and tries to find an appropriate folder under the nl/ directory. If such a folder is not found, the standard help pages and Cheat Sheets (usually in English) are used. These pages are not stored under the nl/ directory. 404 Chapter 12 14_020059_ch12.qxd 10/8/04 11:31 AM Page 404 Deploying National Language Resource Bundles The best method is to deploy language bundles as separate fragments (see “Plug-ins and Fragments”). To do so, just create a package structure within the new fragment that mirrors the package structure of the corresponding plug-in. However, the fragment packages contain only the properties files that have been translated into the target language. The translated nl/ folders are also included in the fragment. You must mark these folders on the Build page of the manifest editor for inclusion into the deployment archive (see the section “Deploying a Feature”). An exception to the rule is the plugin_locale.xml files, which must be stored in the src/ directory instead of the project folder. Patches When a product is deployed and then bugs are later discovered, it is often unacceptable for the customer to reinstall the whole product, especially if the product is large. Download times are lengthy in such cases, and sometimes an online update is impossible. Fixing bugs by sending CDs to customers is expensive. Fortunately, Eclipse-based applications have a modular structure that enables a partial update. The Eclipse Feature Patch allows exactly that. Instead of redeploying the entire updated feature, you can create a feature patch that contains only the modified plug-ins. The Eclipse Update Manager is intel- ligent enough to merge the patch into the installed feature. To create a Feature Patch, create a new project by choosing File > New > Other > Plug-in Development > Feature Patch. In the wizard enter a project name, and continue to the next page. There define a patch ID, a patch name, and the patch provider. Then select the feature to be patched. On the Included Plug-ins and Fragments page, select the plug-ins and fragments that go into the patch. Then press Finish. The Feature Patch project is now ready for deployment. It can be deployed like any other feature project. Summary In this chapter I have discussed additional concepts required for creating Eclipse-based products. You should now know what fragments and features are and how they relate to plug-ins. You should be able to internationalize and customize your application and to deploy such an application. In the next chapter you will apply the knowledge gained in Chapter 11 and this chapter in a larger example. 405 Developing Your Own Eclipse-Based Products 14_020059_ch12.qxd 10/8/04 11:31 AM Page 405 14_020059_ch12.qxd 10/8/04 11:31 AM Page 406 Project Three: A Spell Checker as an Eclipse Plug-in The third example application is a fully functional spell checker for the Eclipse SDK. An early ver- sion of this example was published in my book Eclipse 2 for Java Developsers, and the (enhanced) plug-in that was offered as a separate download became quite popular—so popular that in Eclipse 3 the Java editor was equipped with an integrated spell checker. The spell checker presented here, however, is more versatile. It can perform spell checking not only in Java sources but in any editor and text widget. And it can be extended with plug-ins so that it can intelligently spell-check text formats such as Java, C++, JavaScript, HTML, PHP, JSP, and so on. For the purpose of this book, I present a stripped-down version (no checking while typing, no overriding of preferences on the project level) due to space limitations. The full version, including source code, is available at www.wrox.com (see also Appendix C). During the implementation of this spell checker I demonstrate the following plug-in development techniques: ❑ Definition of a plug-in manifest ❑ Integration of third-party JARs into your own plug-ins ❑ Use of the API for the ITextEditor interface and the MultiEditor class ❑ Addition of menu items to the menu structure of the Eclipse workbench ❑ Addition of menu items to the context menu of editors ❑ Addition of tool buttons to the toolbar of the Eclipse workbench ❑ Association of actions with keyboard shortcuts ❑ Implementation of a workbench view (for correction proposals) 13 13 15_020059_ch13.qxd 10/8/04 12:49 PM Page 407 ❑ Creation of a view toolbar and a view menu ❑ Location and opening of view instances ❑ Creation of new preference pages ❑ Creation of a help system, including table of contents, context-sensitive help (InfoPops), and active help ❑ Internationalization of a plug-in I also show how to write a plug-in that can be extended by others. The spell-checking functionality will not be implemented in the form of a single plug-in but as a group of cooperating plug-ins. Different spell-checking strategies for different document types can be implemented as required and installed separately. To do this, the spell checker base plug-in defines its own extension points. These points allow the addition of file type–specific plug-ins. As an example I will show the implementation of an extension plug-in for spell checking in JavaScript source files. This gives the end user the optional ability to perform spell checking in Javadoc comments, non-Javadoc comments, and string literals. When I implement this plug-in, I will demonstrate the following techniques: ❑ Definition of an extension point, including a schema ❑ Definition of dependencies between plug-ins ❑ Integration of help systems from several plug-ins The Spell Checker Core Classes The core classes of the spell checker consist of the a spell checking engine (which we take from an exist- ing Open Source project), and classes that construct a framework in which later add-ons may plug in. This framework is, in particular, responsible for implementing a GUI (Spell Correction View, actions, preference pages), for controlling the spell-checking engine, and for managing additional plug-ins. The Engine I don’t implement the core spell checking classes myself but instead use the engine of the jazzy spell checker. This engine is completely implemented in Java and is available as an Open Source project at sourceforge.net/projects/jazzy. The algorithms used in this engine belong to the most effective current spell-checking algorithms. I use version 0.5 of jazzy here. The archive jazzy-0.5-bin.zip also contains the source code. In addition, the dictionary english.0.zip is required, which is also available on the SourceForge Web site. The jazzy archive also contains the JAR file jazzy-core.jar. This is the archive that you will need for your project. It contains the packages com.swabunga.spell.engine and com.swabunga.spell.event. 408 Chapter 13 15_020059_ch13.qxd 10/8/04 12:49 PM Page 408 Overview Figure 13.1 shows the most important classes in the spell checker and how they interact (the numbers in parentheses indicate the sequence of method calls). In addition, there are the Plugin class, the classes for managing the preferences, and the classes for configuring the spell-checking engine. The spell- checking process is initiated by the CheckSpellingActionDelegate class. The SpellCheckManager class acts as a central controller. The SpellCheckCorrectionView class dis- plays spelling errors and interacts with the end user. The DocumentWordTokenizer class is used by the jazzy engine to tokenize a document into single words. The SpellCheckingTarget class acts as a common view on editors and text widgets. It provides the text content of these objects in the form of IDocument instances to the other classes and is concerned with text selection and text replacement. 409 Project Three: A Spell Checker as an Eclipse Plug-in CheckSpellingActionDelegate SpellCheckManager SpellCorrectionView DocumentWordTokenizer jazzy-Engine SpellCheckingTarget checkDocument (1) getSelection(2) getDocument(3) checkSpelling(5) setInput(9) (wait) spellingError(7) setSelection(8) init(4) nextWord(6) replaceWord(11) replaceWord(12) replaceText(13) notify(14) ignore/add/replace/cancel (via SpellCheckingEvent) (10) Figure 13.1 15_020059_ch13.qxd 10/8/04 12:49 PM Page 409 Setting Up the Project First, you want to make sure that the functions for plug-in development are enabled in your Eclipse platform. Go to Window > Configure Activities and mark Plug-in Development. Next, you must set up the target platform. Testing and debugging a plug-in does not happen in the development platform but in a separate Eclipse session. The configuration of this platform can differ considerably from the configuration of the development platform. For example, you may want to run the new plug-in in the minimal Eclipse runtime environment, that is, in a platform that does not have a Java IDE or a PDE. So you must first determine with which plug-ins your target platform is equipped. You can do this with the function Window > Preferences > Plug-in Development > Target Platform (Figure 13.2). You can exclude certain plug-ins during the configuration of the target platform, and you can include other plug-ins that are not in the Eclipse workspace by clicking the Not In Workspace button. 410 Chapter 13 Figure 13.2 In this case, you may want to test the spell checker plug-in in an environment that is equipped with a Java IDE and a PDE, since you want to use the spell-checking facility in the editors of those features. Therefore, you need to checkmark all plug-ins of the target platform with the exception of the example plug-ins and the source code plug-ins. If you have already installed the spell checker plug-in into your development platform, you should also disable all of the plug-ins that start with com.bdaum.SpellChecker in order to avoid conflicts. Instead of modifying the global preferences for the target platform, another possibility is to later create a special Run configuration for the new plug-in. To do so, invoke Run > Run and press the New button to create a new configuration for a runtime workbench. On the Plug-ins page, you may select from vari- ous options. When you mark the Choose Plug-ins and Fragments to Launch option from the list, you 15_020059_ch13.qxd 10/8/04 12:49 PM Page 410 [...]... org .eclipse. swt.widgets.Display; org .eclipse. swt.widgets.Shell; org .eclipse. swt.widgets.Text; org .eclipse. ui.IEditorActionDelegate; org .eclipse. ui.IEditorPart; org .eclipse. ui.IPartListener; org .eclipse. ui.IPartService; org .eclipse. ui.IWorkbenchPage; org .eclipse. ui.IWorkbenchPart; org .eclipse. ui.IWorkbenchWindow; org .eclipse. ui.IWorkbenchWindowActionDelegate; org .eclipse. ui.PartInitException; org .eclipse. ui.PlatformUI;... org .eclipse. jface.viewers.ISelection; org .eclipse. jface.viewers.ISelectionProvider; org .eclipse. swt.custom.StyledText; org .eclipse. swt.events.ModifyEvent; org .eclipse. swt.events.ModifyListener; org .eclipse. swt.graphics.Point; org .eclipse. swt.widgets.Control; org .eclipse. swt.widgets.Text; org .eclipse. ui.IEditorInput; org .eclipse. ui.IEditorPart; org .eclipse. ui.IWorkbenchPart; org .eclipse. ui.texteditor.IDocumentProvider; org .eclipse. ui.texteditor.ITextEditor;... plug-ins for the Eclipse runtime: org .eclipse. core.resources and org .eclipse. core.runtime Second, you will need the basic plug-ins for the user interface of the Eclipse IDE, org .eclipse. ui and org .eclipse. ui.ide Third, because the plug-in deals with text editors and text processing, you will also need the plug-ins org .eclipse. jface.text and org .eclipse. ui.workbench.texteditor And finally, the plug-in for. .. the plug-in It also provides methods for obtaining information about the plug-in 419 Chapter 13 package com.bdaum.SpellChecker; import java. io.IOException; import java. net.URL; import import import import import org .eclipse. core.runtime.IStatus; org .eclipse. core.runtime.Platform; org .eclipse. core.runtime.Status; org .eclipse. jface.preference.IPreferenceStore; org .eclipse. ui.plugin.AbstractUIPlugin; import... plugin="org .eclipse. core.resources"/> 4 13 Chapter 13 On the Extension Points page, you need to define... checked for the correct spelling package com.bdaum.SpellChecker.actions; import import import import import import import import import import import import import import import import import import import import org .eclipse. jface.action.IAction; org .eclipse. jface.viewers.ISelection; org .eclipse. swt.custom.StyledText; org .eclipse. swt.events.FocusEvent; org .eclipse. swt.events.FocusListener; org .eclipse. swt.widgets.Control;... support, org .eclipse. help, is required, too, because the spell checker plug-in will offer help to the end user For the plug-ins org .eclipse. core.runtime, org .eclipse. ui, org .eclipse. jface.text, and org .eclipse. help mark the option Re-export the Dependency This will make these plug-ins available to all plug-ins that specify com.bdaum.SpellChecker as a required plug-in ... CheckSpellingActionDelegate class that acts as a proxy for the Check Spelling action and the SpellCheckingTarget class that acts as an umbrella class for the various concrete targets of the action 424 Project Three: A Spell Checker as an Eclipse Plug-in The SpellCheckingTarget Class The Eclipse platform hosts a wide variety of editors such as simple text editors and the Java editor but also more complex editors... as an Eclipse Plug-in may select individual plug-ins for inclusion into the test platform If you want to use the minimum number of plug-ins for running your plug-in, proceed as follows: 1 2 3 Press the Deselect All button Now mark the Workspace Plug-ins check box (or only the plug-ins that you want to test) Press the Add Required Plug-ins button This will mark all plug-ins that are required for running... Extension Points page, you need to define a new extension point, documentTokenizer This extension point will allow you and others to add extensions for specific text formats later, such as a plugin for Java source code spell checking (see the section “A Plug-in for Java Properties”) The name of this extension point is chosen on the basis that later extensions will consist more or less of specific tokenizers . example. 405 Developing Your Own Eclipse- Based Products 14_020059_ch12.qxd 10 /8/ 04 11 :31 AM Page 405 14_020059_ch12.qxd 10 /8/ 04 11 :31 AM Page 406 Project Three: A Spell Checker as an Eclipse Plug-in The third. the toolbar of the Eclipse workbench ❑ Association of actions with keyboard shortcuts ❑ Implementation of a workbench view (for correction proposals) 13 13 15_020059_ch 13. qxd 10 /8/ 04 12:49 PM Page. com.swabunga.spell.engine and com.swabunga.spell.event. 4 08 Chapter 13 15_020059_ch 13. qxd 10 /8/ 04 12:49 PM Page 4 08 Overview Figure 13. 1 shows the most important classes in the spell checker