Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Orion/Documentation/Developer Guide/Plugging into the editor"
m (→Examples) |
m (→orion.edit.highlighter) |
||
Line 57: | Line 57: | ||
= orion.edit.highlighter = | = orion.edit.highlighter = | ||
− | The <tt>orion.edit.highlighter</tt> service contributes syntax highlighting rules to the editor. A highlighter service provides a declarative description of the structure of a language | + | The <tt>orion.edit.highlighter</tt> service contributes syntax highlighting rules to the editor. A highlighter service provides a <i>grammar</i>, which is a declarative description of the structure of a language and what CSS classes the different structural pieces correspond to. The service also provides a list of file extensions. When the editor opens a file of a registered extension type, the grammar is applied to the file to obtain the styling. |
== Service methods == | == Service methods == |
Revision as of 10:47, 21 June 2011
Contents
Overview of contributing services to the Orion editor
The built Orion editor defines a number of services for customizing its appearance and behavior. These services will typically be defined by a plug-in providing editing functionality for different programming languages or file extensions. This section will outline the services that are available for editor customization.
orion.edit.command
The orion.edit.command service is the simplest kind of editor extension. A command service simply provides a function that takes some text as input, performs some operation or transformation on the text, and returns a new text value. The command can also optionally receive and return selection information for changing the editor selection.
Service methods
Implementations of orion.edit.command must define the following function:
- run(selectedText, text, selection)
- selectedText is a string containing the text that is currently selected in the editor. The text argument provides the entire editor buffer. The selection argument is a selection object with start and end fields.
Service attributes
Implementations of orion.edit.command may define the following attributes:
- img
- The URL of an icon to associate with the command
- name
- The command text show to the user
- key
- An optional key binding for the command
Examples
The following simple example just converts the selected text to upper case. In this example the function return value is a simple string, so this is interpreted by the editor as replacement for the original editor selection. In the service properties, we see the command provides a key binding of Ctrl+U (or Cmd+U on Mac).
var provider = new eclipse.PluginProvider(); provider.registerServiceProvider("orion.edit.command", { run : function(text) { return text.toUpperCase(); } }, { name : "UPPERCASE", img : "/images/gear.gif", key : [ "u", true ] }); provider.connect();
Here is an example of a slightly more complex run function that takes the selection and wraps it in C-style block comments. In this example the function returns a complex object with both text and selection fields. These are interpreted by the editor as the new editor buffer contents, and the new editor selection.
run : function(selectedText, text, selection) { return {text: text.substring(0,selection.start) + "/*" + text.substring(selection.start,selection.end) + "*/" + text.substring(selection.end), selection: {start:selection.start,end:selection.end+4}}; }
orion.edit.contentAssist
orion.edit.highlighter
The orion.edit.highlighter service contributes syntax highlighting rules to the editor. A highlighter service provides a grammar, which is a declarative description of the structure of a language and what CSS classes the different structural pieces correspond to. The service also provides a list of file extensions. When the editor opens a file of a registered extension type, the grammar is applied to the file to obtain the styling.
Service methods
None.
Service attributes
Implementations of orion.edit.highlighter must define the following attributes:
- type
- String What kind of highlight provider is being registered. For now this should always be "grammar", although future versions may support more.
- fileTypes
- Array An array of file extensions that this provider will be used for.
- grammar
- Object An object giving the grammar to be used to assign style classes. This object is expected to be a JavaScript equivalent of the format described here.
Examples
var provider = new eclipse.PluginProvider(); provider.registerServiceProvider("orion.edit.highlighter", { }, { type : "grammar", fileTypes : ["html", "htm"], grammar: { patterns: [ { begin: "<!--", end: "-->", captures: { "0": "punctuation.definition.comment.html" }, contentName: "comment.block.html" } ] } }); provider.connect();
The above example provides a grammar to be used for .html and .htm files. It will assign the CSS class punctuation-definition-comment-html to the <!-- and --> delimiters, and assign the CSS class comment-block-html to the text inside the delimiters. Consult this reference for a full description of the grammar format.
(Note that some aspects of the grammar format are not supported. See orion.editor.TextMateStyler in the Client API reference for a detailed explanation.)