Xtext / Sirius Integration User Guide

A direct editor is activated by

The editor replaces the label and is sized to fit its contents.

For single-line editors, the editor closes on pressing Enter.

Editor contents are committed to the model when the editor is closed. The editor closes when it loses focus, e.g. by a click outside the editor.

Direct editors are specified as tool in the odesign editor.

We provide the following variants:

They can be added to the tools section the same as a regular Direct Edit Label tool. Accordingly, they need to be selected as Label Direct Edit on the Behavior page of the edited Sirius element.

The label is independent of the edited text, i.e. the label can show a different text than the direct editor.

If the set value operation feature is empty, it is interpreted as to replace var:self.

Direct editors

If the editor contains model contents, it supports to limit the editable features, to ignore some nested features, and to define pre-selected features. If the Sirius element is an edge, the editor requires to select an edgeLabelPosition.

The Eclipse Properties View contains the property editors.

Editor contents are committed when the editor is hidden. This happens when the end-user selects a different property page or a different diagram element.

Property editors are specified as property widgets in the odesign editor.

We provide the following variants:

They can be added as a widget to a Properties Sirius element the same as regular widgets.

Property editors

If the editor contains model contents, it supports to limit the editable features, to ignore some nested features, and to define pre-selected features.

The editor can contain semantic elements from the same model the edited diagram is based on.

A typical use-case may allow the end-user to edit several features of a semantic element in-line with complete Xtext support.

As an example, think of a UML class attribute displayed as + age: int = 0. If the end-user opens the direct editor of the attribute, they can change all these features (visibility, name, type, default value) with complete Xtext support, e.g.

The editor assumes the model of the edited diagram is persisted with the same Xtext grammar as supplied to the editor (except for explicit differences).

Any changes in the editor are applied to the underlying model of the edited diagram (except non-editable features and ignored nested features). The changes are committed to the Sirius edit session, but only persisted if and when the edited diagram is saved.

The editor maintains references between the edited semantic element (and its descendants) and the rest of the model in both directions, if possible. The editor does not prevent the end-user from breaking references, e.g. by changed referenced names or deleting referenced elements.

In order to provide appropriate auto-completion and other Xtext features, the editor maintains a complete copy of the edited diagram’s model (and optionally all other Ecore resources of the Sirius session). However, only the subsection relevant to the selected semantic element (and limited by the editable features, if applicable) is shown to, and editable by, the end-user.

Determining the correct subsection is quite complicated, especially if the subsection borders in grammar terminals or contains unset features. This may lead to incorrectly selected subsections. However, the result should only be affected by the grammar, therefore the developer can test this during development.

The editor reintegrates its contents into the edited diagram’s model on model level, not on text level. This means if the end-user modified any part of the model not contained within the edited semantic element, these changes are not committed. The editor also omits changes to non-editable features or ignored nested features from the commit.

The editor can interpret simple String feature of semantic elements as Xtext models.

A typical use-case may allow the end-user to edit the description feature of a semantic element as markup text with complete Xtext support.

As an example, think of an entity model containing classes that may have descriptions. By its metamodel, the description is merely a String. An Xtext value editor (primed with an Xtext implementation of HTML) for the description allows the end-user to describe the class with complete Xtext support for HTML.

Any changes in the editor are stored in the semantic element’s String feature as-is. The changes are committed to the Sirius edit session, but only persisted if and when the edited diagram is saved.

An injector describes a complete Xtext configuration for a language.

In order to avoid class loading issues, we provide injectors via Eclipse extension point com.altran.general.integration.xtextsirius.runtime.xtextLanguageInjector.

For each injector, we need to define an id (to be referenced from the odesign model) and a class that implements com.altran.general.integration.xtextsirius.runtime.IXtextLanguageInjector.

A typical implementation is provided below.

We refer to the id via the InjectorId property.

The editor can display one single line or several lines.

Effects for single-line editors:

For direct editors, we define this info via the Lines property. It will adjust its size automatically.

For property editors, we define this info by selecting the appropriate widget. For Text Area widgets, we can define the number of lines to be shown via the Line Count property.

In order to provide appropriate auto-completion and other Xtext features, a value editor requires a complete model. However, the String feature may contain only a subsection of a complete model. Therefore, the developer may provide text that should be pre-pended and appended to the String feature’s value in order to complete the model. The end-user still sees and edits only the String feature’s value.

Think of a simplified version of HTML implemented as Xtext language. A complete model might look like this:

This language should be used for the description feature of classes in an entity model.

However, the model may contain several such classes, and the description of all of them should end up in only one HTML file (in a later generation step). Instead of storing a complete model into every class' description (and bothering the end-user with it), the description contains only the following part:

In order to complete the model for Xtext, the developer supplies the editor with

This way, Xtext works on a complete model, but only the relevant parts are available to the end-user.

We provide these infos via the prefixTextExpression / suffixTextExpression properties. As hinted by the name, these fields accept both a simple string as well as any expression supported by Sirius.

The editor can limit which features of a semantic element are editable by the end-user.

A typical use-case hides the feature defining the source and/or target of an edge from being edited textually.

Assume the following Xtext grammar snippet defining an UML-like Association, to be displayed as edge:

Example model:

The label would show driver 23.

The end-user should not be able to change the source and/or target of the association, but use an Xtext editor for the label to edit the other features.

Therefore, the developer supplies the following list of editableFeatures:

Limiting the editable features works by finding the first and last of the features in the text stream, and limit the editable area of the model to this subpart.

Therefore, if the model looks like

and the editableFeatures are limited to

the editor would still include the code subpart, because it’s in between the name and guard subpart.

If the list of editableFeatures is empty, all features are considered to be editable.

If the list of editableFeatures is not empty, we omit all features not contained in the list from committing back to the original model.

The Editable Features property contains a read-only list of features. Edit it by activating the …​ button. This opens a pop-up window listing all available and currently selected features.

The editor can omit some nested features from committing back to the original model.

Typically, this is combined with a specialized edit grammar to also hide the ignored nested features from the end-user. It might also be necessary to declare these features transient.

Assume the following Xtext grammar snippet defining an UML-like Association, to be displayed as edge:

Example model:

The end-user should not be able to change the target type of the Association, but use an Xtext editor for the label to edit the other features.

Therefore, the developer supplies the following (single-entry) list of ignoredNestedFeatures:

Thus, the editor ignores all end-user changes to target.type.

The end-user would probably be very annoyed about changing something in the editor, and being ignored. We can remove this annoyance by using a specialized grammar to remove the type part:

Only changing the grammar would not be sufficient, as this would delete typeRef.type on every edit.

The Ignored Nested Features property contains a read-only list of strings. Edit it by activating the …​ button. This opens a pop-up window listing all current entries on the right, and a text box on the left to add new ones. Unfortunately, we cannot provide a list of all possible entries, as they depend on the structure of the actually edited model at run-time.

Each entry is a dot-separated concatenation of EStructuralFeature names. the first segment is a feature of the edited semantic element.

The editor can set the initial text selection to defined features.

A typical use-case pre-selects the name of the edited semantic element.

Assume the following Xtext grammar snippet defining a statemachine event:

Most of the time, the end-user wants to change the name of the event.

Therefore, the developer supplies the following (single-entry) list of selectedFeatures:

Thus, when the end-user presses F2 on the Event shape, the editor selects the bold text in this example:

event MyEventName 23

Pre-selecting features works by finding the first and last of the features in the text stream, and set the initial text selection to this subpart. Thus, if the developer selected two features, but a third one is in between them, all of the three features will be selected.

The Selectable Features property contains a read-only list of features. Edit it by activating the …​ button. This opens a pop-up window listing all available and currently selected features.

Unfortunately, we cannot assign different Direct Edit Label tools to different edge labels (begin, center, end).

Therefore, if the developer attaches a direct editor to an edge, the developer needs to specify which edge label should be equipped with Xtext powers. This info is contained in the Edge Label Mappings property. The read-only list is edited by activating the …​ button. This opens a pop-up window listing all available and currently selected edge labels.

By default, the editor uses some heuristics to determine which terminals should be included at the beginning and end of the edited text.

This behavior can be overridden by the developer. For all value editors, the developer may define a prefixTerminalsExpression and/or a suffixTerminalsExpression in the odesign file.

For both of them, the following rules apply:

Thus, if we want to disable the heuristics and don’t include any preceding terminals, our prefixTerminalsExpression looks like:

Assume the following grammar as example. It uses the usual C-like whitespace and comment rules:

Example model contents:

For editing Event, assume:

The resulting editor contents for all three Events will look like:

We discuss the terminals matching process for suffixTerminalsExpression below. It works accordingly for prefixTerminalsExpression.

We ignore all whitespace and comment contents, as defined by the editor grammar. Terminals matching starts at the last editable feature in the text. From there, we look at all following tokens, and include them as long as their combined text matches the resulting string of suffixTerminalsExpression. As soon as we find a non-terminal token, we quit terminals matching.

The example would work the same way if the suffixTerminalsExpression was:

Explanation: For event ford, it would successfully match ] but quit terminals matching afterwards, because the next token would not be a terminal (in this case, it would be the following Event rule).