8.1. Editor Declaration

There are two steps involved in creating a new editor:

• Define the editor in the plug-in manifest file (see Figure 8-2).

Figure 8-2. Editor declaration in plug-in manifest

[View full size image]

• Create the editor part containing the code.

One way to do all this at once is to create the editor when the plug-in is being created, similar to the way that views can be created (see Section 2.2.3, Define the view, on page 69). If the plug-in already exists, then this becomes a two-step process.

The first step in creating an editor is to define the editor in the plug-in manifest (see Figure 8-2). On the Extensions page of the plug-in manifest editor, click the Add... button in the upper right corner, select org.eclipse.ui.editors, and finally click Finish. Next, right-click on org.eclipse.ui.editors and select New > editor to add an editor extension. Select the new editor extension to display the properties on the right and then enter the following values.

class"com.qualityeclipse.favorites.editors.PropertiesEditor" The fully qualified name of the class defining the editor and implementing org.eclipse.ui.IEditorPart (see Section 8.2, Editor Part, on page 330). Click the Browse... button to the right of the field to open a dialog and select an existing editor part. Click the class label on the left to generate a new one. The attribute's class, command, and launcher are mutually exclusive. The class is instantiated using its no argument constructor, but can be parameterized using the IExecutableExtension interface (see Section 20.5, Types Specified in an Extension Point, on page 723).

contributorClass"com.qualityeclipse.favorites.editors. PropertiesEditorContributor" The fully qualified name of a class that implements org.eclipse.ui. IEditorActionBarContributor and adds new actions to the workbench menu and toolbar, reflecting the features of the editor type (see Section 8.5.2, Editor contributor, on page 357). This attribute should only be defined if the class attribute is defined. Click the Browse... button to the right of the field to open a dialog for selecting an existing editor contributor. Click the contributorClass on the left to generate a new one.

extensions"properties" A string of comma-separated file extensions indicating file types understood by the editor.

icon"icons/sample.gif" The image displayed at the upper left corner of the editor. Similar to action images (see Section 6.2.4, Action images, on page 214), this path is relative to the plug-in's installation directory.

id"com.qualityeclipse.favorites.editors.PropertiesEditor" The unique identifier for this editor.

name"Properties Editor" The human-readable name for the editor.

Other attributes that are not used in this example include:

commandA command to run to launch an external editor. The executable command must be located on the system path or in the plug-in's directory. The attribute's class, command, and launcher are mutually exclusive.

default"true" or "false" (blank = false) If true, this editor will be used as the default editor for the type. This is only relevant in the case where more than one editor is registered for the same type. If an editor is not the default for the type, it can still be launched using the Open with... submenu for the selected resource.

filenamesA string containing comma-separated filenames indicating filenames understood by the editor. For instance, an editor that understands plug-in and fragment manifest files can register plugin.xml, fragment.xml.

launcherThe name of a class that implements org.eclipse.ui. IEditorLauncher and opens an external editor. The attribute's class, command, and launcher are mutually exclusive.

matchingStrategythe name of a class that implements org.eclipse.ui.IEditorMatchingStrategy. This attribute should only be defined if the class attribute is defined and allows the editor extension to provide its own algorithm for matching the input of one of its editors to a given editor input. This is used to find a matching editor during openEditor() and findEditor().

In addition, the editor element can have one or more contentTypeBinding subelements, each specifying a contentTypeId. The contentTypeId references an org.eclipse.core.runtime.contentTypes extension and indicates that the editor can contain that type of content. The contentTypes extension can more accurately define whether a file should be associated with a partiular editor than by file extension alone.

After filtering files by name and extension, the content type uses a describeran instance of IContentDescriber or ITextContentDescriberto scan the content of a file before determining whether a file contains a particular type of content. Eclipse provides several built-in describers including the following:

BinarySignatureDescriberA content describer for binary formats that present some simple signature at a known, fixed offset. There are three parameters: "signature," "offset," and "required"the first one being mandatory.

signaturea sequence of hex codes, one for each byte. For example, "CA FE BA BE" would be a signature for Java class files. offset an integer indicating the offset where the signature's first byte is to be found.

required a boolean (default is TRue) indicating whether the absence of a signature should deem the contents validity status as IContentDescriber.INVALID or IContentDescriber.INDETERMINATE.

XMLRootElementContentDescriberA content describer for detecting the name of the top-level element or the DTD system identifier in an XML file. Two parameters are supported: "dtd" and "element."