Papyrus/Papyrus Developer Guide/Papyrus Embedded Editors Documentation/Value Specification Xtext editor

General Presentation

The Value Specification XText editor uses the XText technology.

The textual editor allow to create/edit some types of Value Specification:

• org.eclipse.uml2.uml.LiteralBoolean
• org.eclipse.uml2.uml.LiteralUnlimitedNatural
• org.eclipse.uml2.uml.LiteralInteger
• org.eclipse.uml2.uml.LiteralReal
• org.eclipse.uml2.uml.LiteralNull
• org.eclipse.uml2.uml.LiteralString
• org.eclipse.uml2.uml.InstanceValue
• org.eclipse.uml2.uml.OpaqueExpression

This fonctionnality is implemented through several plugins:

• org.eclipse.papyrus.uml.textedit.valuespecification.XText which contains the grammar of the Value Specification, the generated XText classes and the created class UmlValueSpecificationScopeProvider for the custom scoping of org.eclipse.uml2.uml.InstanceValue displaying the org.eclipse.uml2.uml.InstanceSpecification available in the model.
• org.eclipse.papyrus.uml.textedit.valuespecification.XText.ui which contains the generated XText ui classes and the implementation of DefaultXTextDirectEditorConfiguration for the Value Specification edition.
• org.eclipse.papyrus.uml.textedit.valuespecification.XText.utils which contains the utils classes for the XText edition of Value Specification and especially the SetCommand of the Value Specification in its container.
• org.eclipse.papyrus.uml.nattable.XText.valuespecification which contains the cell editor, the default cell editor configuration and the default cell manager for editing the Value Specification with the XText parser.
• org.eclipse.papyrus.infra.widgets which contains the created class StyledTextReferenceDialog that allows do define the component to edit the Value Specification in a widget in the properties view.
• org.eclipse.papyrus.uml.properties.XText which allow to define the editor for the XText parser in the properties view.
• org.eclipse.papyrus.uml.textedit.valuespecification.tests which contains all the JUnit tests for the XText parser.

Parser definition

The default grammar of the XText parser for the Value Specification is the following:

(visibility)? (name'=')? value

The values accepted for the differents attributes are the following:

Attribute	Required	Values accepted
visibility	No	+ (public) # (protected) ~ (package) - (private)
name	No	String representing an ID (i.e. XText grammar: '^'?('a'..'z'|'A'..'Z'|'_') ('a'..'z'|'A'..'Z'|'_'|'0'..'9')*)
value	Yes	true or false (LiteralBoolean) positive integer or *(LiteralUnlimitedNatural) negative integer (LiteralInteger) double (LiteralReal) null (LiteralNull) String with quote (LiteralSting). The quote (') is essential for 2 reasons: The XText parser cannot define the difference between the name representing an InstanceSpecification and a simple string value A Non-valid value won't be defined as an OpaqueExpression without quote but always as a LiteralString value Instance Specification name (InstanceValue) <Undefined> or empty (null)

If the text filled is not compatible with the grammar of XText parser, an OpaqueExpression will be created.

The XText parser for Value Specification is not restrictive with the text filled, i.e. the different features setted on an existing Value Specification will be kept if possible.

For example: If an existing Value Specification is a LiteralBoolean named 'testBoolean' with the visibility 'public' and the value setted to true, the text +testBoolean=false and false have the same result: the value of LiteralBoolean existing will pass to false (the name and the visilibity don't change).

The XText parser reacts differently instead of the type of the Value Specification's container:

Without defined type on Value Specification's container

If the type of Value Specification's container is not defined, the default behaviour will be applied.

Here, some examples:

Text filled	Namely	Created ValueSpecification
		Type	Visibility	Name	Value
+testInstanceValue=InstanceSpec1	'InstanceSpec1' is an InstanceSpecification existing in the model	InstanceValue	public	testInstanceValue	'instance' attribute of InstanceValue is a reference to the existing InstanceSpecification named 'InstanceSpec1'
	No InstanceSpecification exist in the model	OpaqueExpression	public	+testInstanceValue=InstanceSpec1
+testBoolean=true		LiteralBoolean	public	testBoolean	true
#testUnlimitedNatural=5		LiteralUnlimitedNatural	protected	testUnlimitedNatural	5
~testInteger=-8		LiteralInteger	package	testInteger	-8
-testReal=12.34		LiteralReal	private	testReal	12.34
~testNull=null		LiteralNull	package	testNull	null
-testString="foo"		LiteralString	private	testString	foo
##testString="foo"		OpaqueExpression	public	##testString="foo"

With defined type on Value Specification's container

If the type of Value Specification's container is setted, the same text filled will be have different behaviour depending to the type. In fact, the value filled must be consistent to the type, otherwise an OpaqueExpression will be created.

The different types corresponding to LiteralSpecification are the following:

LiteralSpecification	Types corresponding
LiteralBoolean	JavaPrimitiveTypes::boolean EcorePrimitiveTypes::EBoolean EcorePrimitiveTypes::EBooleanObject PrimitiveTypes::Boolean XMLPrimitiveTypes::Boolean XMLPrimitiveTypes::BooleanObject
LiteralUnlimitedNatural	PrimitiveTypes::UnlimitedNatural
LiteralInteger	JavaPrimitiveTypes::int EcorePrimitiveTypes::EInt EcorePrimitiveTypes::EIntegerObject PrimitiveTypes::Integer XMLPrimitiveTypes::Int XMLPrimitiveTypes::Integer XMLPrimitiveTypes::IntObject
LiteralReal	JavaPrimitiveTypes::double EcorePrimitiveTypes::EDouble EcorePrimitiveTypes::EDoubleObject PrimitiveTypes::Real XMLPrimitiveTypes::Double XMLPrimitiveTypes::DoubleObject
LiteralString	EcorePrimitiveTypes::EString PrimitiveTypes::String XMLPrimitiveTypes::String

Here, some examples:

Text filled	Value Specification's container type	Created ValueSpecification
		Type	Visibility	Name	Value
+testBoolean=true	PrimitiveTypes::Boolean	LiteralBoolean	public	testBoolean	true
	PrimitiveTypes::Integer	OpaqueExpression	public	+testBoolean=true
-testUnlimitedNatural=8	PrimitiveTypes::UnlimitedNatural	LiteralUnlimitedNatural	private	testUnlimitedNatural	8
	PrimitiveTypes::Integer	LiteralInteger	private	testUnlimitedNatural	8
	PrimitiveTypes::Real	LiteralReal	private	testUnlimitedNatural	8.0
	PrimitiveTypes::Boolean	OpaqueExpression	public	-testUnlimitedNatural=8
#testInteger=-6	PrimitiveTypes::UnlimitedNatural	OpaqueExpression	public	#testInteger=6
	PrimitiveTypes::Integer	LiteralInteger	protected	testInteger	6
	PrimitiveTypes::Real	LiteralReal	protected	testInteger	6.0
	PrimitiveTypes::Boolean	OpaqueExpression	public	#testInteger=6
-testReal=4.5	PrimitiveTypes::Integer	OpaqueExpression	public	-testReal=4.5
	PrimitiveTypes::Real	LiteralReal	private	testReal	4.5

Papyrus integration

Direct editor configuration

The Direct Editor Condiguration allow to define a new cirect editor for Papyrus. This define the object type to edit and the editor configuration class used for the integration of editor. For the Value Specification XText editor, a default Direct Editor Configuration is already defined: ValueSpecificationXTextDirectEditorConfiguration which allow to manage the type org.eclipse.uml2.uml.ValueSpecification.

Manage the default languages of created OpaqueExpression

To redefine the default languages used by created OpaqueExpression by the properties widget, a class extending the ValueSpecificationXTextDirectEditorConfiguration must be created and the method getDefaultLanguages() must be override.

Then, this created direct editor configuration must be referenced in the org.eclipse.papyrus.extensionpoints.editors.DirectEditor extension point with a higher priority than the default (Lowest).

Properties integration

Define the context and the xwt files

The context file allow to define the field available in the properties view. To define the field which will be displayed in the properties view with XText parser and completion, the UMLStyledTextReferenceDialog will be used.

This class contains a UMLXTextReferenceValueEditor which contains a StyledText for the text fill and StyledTextXTextAdapter to manage the XText parser and completion.

Here, an example of context and xwt file for the default value of property object:

In the PropertyEditor created, an attribute directEditorConfiguration will be implemented to define the direct editor configuration class to use for the edited object:

The context file must be referenced in the org.eclipse.papyrus.views.properties.context extension point:

Cell of NatTable integration

Define the cell editor configuration

A default cell editor configuration already exists for the Value Specification: ValueSpecificationCellEditorConfiguration. But to get the possible XText parser and completion in cell of NatTable, the cell editor configuration must be extended and the created class must be referenced in the org.eclipse.papyrus.infra.nattable.celleditor.configuration extension point with an inferior order than the others.

Here, an example:

Define the cell manager

A default cell manager already exists for the Value Specification: ValueSpecificationCellManager. But to get the possible XText parser and completion in call of NatTable, the cell manager must be extended and the created class must be referenced in the org.eclipse.papyrus.infra.nattable.cellmanager extention point with an inferior order than the others.

Here, an example:

Manage the default languages of created OpaqueExpression

To redefine the default languages used by created OpaqueExpression by the cell editor, the method getDefaultLanguages() must be overridden in the class extended from ValueSpecificationCellManager.

Example

• The plugin org.eclipse.papyrus.uml.textual.editors.example provide an example of integration of this editor in the table and in the property view to edit the default value of a property.
• A video is available here https://www.youtube.com/watch?v=OERg0BUZmyU&feature=youtu.be