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.
Papyrus/Mars Work Description/Improvments/Stereotype support
Contents
Enhancement of the support for the stereotypes in Papyrus
This page presents the improvments that will be pushed in the Mars version of Papyrus regarding the stereotypes support in the tool.
Introduction
The starting point of this study is due to concomitant issues around the stereotype display:
- The first whished improvement is to display the stereotypes when dragged and dropped from the model explorer.
- The second whish would be to use the Named Styles instead of EAnnotation in order to be aligned with the Papyrus point of view and be based on GMF layer.
- The third point is the user interface to display the Stereotype that doesn’t fulfil the user expectation in terms of intuitiveness.
State of art
Concepts in place
The Stereotype feature contains two types of display, which are more or less independent.
- The stereotype name label
- Can be displayed or hidden
- With a short name or a Qualified Name
- The stereotype properties
- Can be displayed or hidden
- Can be shown in a compartment, as a comment or in braces
On top of that, there are several actions taking part in the stereotype display:
- When displaying or hiding an item (stereotype Label or property label) from the appearance property view.
- When a new stereotype is applied or unapplied from the profile tab into the property view.
Those different cases should be part of the solution. But as there are quite independent, they can be treated as such.
Conception
In Papyrus, Stereotypes are stored into UML model. But the information related to the manner to display stereotypes is stored through the EAnnotation. EAnnotation is an EMF concept that is attached to an object of type EModelElement. The EAnnotation details is a Map of type EMap<String,String>. In the case of “Stereotype”, the EAnnotation name is “Stereotype_Annotation”, the related map contains the following list of properties and values:
KEY (String) | VALUE (String) | Description |
---|---|---|
Stereotype_Presentation_Kind | TextIconStereotype | The kind of presentation for stereotype |
IconStereotype | ||
ImageStereotype | ||
HorizontalStereo | ||
VerticalStereo | ||
StereotypeList | Block, Allocated | The list of stereotype to display |
StereotypeWithQualifiedNameList | SysML::Allocations::Allocated, SysML::Blocks::Block | The list of stereotype to display with Qualified Name |
PropStereoDisplay | SysML::Blocks::Block.isEncapsulated | List of properties to display |
StereotypePropertyLocation | Compartment | Location of Stereotype Properties |
In Brace | ||
Comment |
Property View
The profile and stereotypes applied are available under the tab “Profile” of the property view of the diagram or of the object. All the information about the display of those stereotypes is available under the “Appearance” tab.
- What information should be displayed (Text, icon, image, text and Icon)
- How the stereotypes should be aligned (Horizontal or vertical )
- Location of the stereotype information to be displayed (in a specific compartment, as a comment, or between bracket )
- The selection tree of the applied stereotypes with their properties
- Pair of buttons to display either short stereotype name, or the whole qualified name.
Architecture
Here is the general overview of the Stereotypes architecture with EAnnotation.
Here is the class diagram of the Stereotype EAnnotation concept:
Observations
Several observations can be done from this conception:
- EAnnotation is difficult to maintain, it is string based only, and a lot of classes, constants and methods are required to put EAnnotation in place.
- EAnnotation is not well designed for a CSS compatibility. It is then difficult to have a good customization.
- The user interface into the “Appearance” Tab is not clear. The two buttons to display qualified name and short name are ambiguous.
- The property view is directly in charge of creating Commands to manage the EAnnotation, instead of separated responsibilities between graphical interface, user actions, and command creations.
For those reasons, the entire Stereotype display mechanism must be improved.
Requirements ( Draft )
Req ID | Category | Description |
---|---|---|
STO_01 | Default display | The stereotypes are display by default (during the creation, when DnD, when applied). |
STO_02 | New Stereotype | The stereotypes displayed should be automatically updated when applied stereotypes list changes or property value changes. |
STO_03 | Qualified Name | Each Stereotype can be either displayed with a short name or with the Qualified Name. |
STO_04 | Qualified Name | The displayed qualified name depth can be defined for each stereotype. |
STO_05 | Location | Properties can be displayed in a compartment, in a comment and/or between braces. |
STO_06 | Location | The user should be able to choose the location of each stereotype's property (In compartment, in braces, as a comment). |
STO_07 | Hide | Each stereotype and property can be displayed or hidden independantly. |
STO_08 | CSS | Visibility, qualified name depth and location can be defined by CSS. |
STO_09 | CSS | A CSS file can be added for each Stereotype to manage its display. |
STO_10 | Qualified Name | The user must be able to chose the depth of the QN to be displayed |
STO_11 | Qualified Name | The user should be able to chose if the Qualified Name depth is calculated automatically. |
STO_12 | Qualified Name | The user should be able to chose if the Qualified Name is fully displayed or not at all. |
Solutions
Different solutions have been studied to find the best soution. First suggestion is to translate all the Eannotation properties into NamedStyle properties. Second soltution would be to define one label by stereotype. This chapter will describe the different solutions.
Named Styles
Based on the previous analysis, the Named Styles seems to be a good approach. This chapter explains how Named Styles work and how it can be integrated into the code to display stereotypes. Named Style is a GMF concept based on the Notation file. Named Styles define typed properties as a Style into the notation file. Types for Named Styles are the primitive ones: int, boolean, string, list, double… Notation file can be overridden by the CSS that is also accessible by the Named Style.
Architecture
Here is the general overview of the new solution for the Stereotypes to be displayed with Named Styles.
Note: method’s name is informative and not definitive.
The direct edition of the stereotypes from the appearance property view is now done through the Edit Part which centralizes the different actions to be executed to display, hide, and update the stereotypes to be displayed.
CSS and Named Styles
In order to keep as many liberty degrees to the user as for the present solution, the same set of parameters is required. To allow the user to define the list of Stereotypes to hide from CSS and from the user interface, different list should be used for the CSS and the notation file. Then the lists can be merged instead of being overriden.
Those means that a lot of lists should be implemented as a parameter:
- stereotypesToHide
- stereotypesToDisplayAsQN
- stereotypePropertiesToHide
- stereotypesToDisplay
- CSSStereotypesToHide
- CSSStereotypesToDisplayAsQN
- CSSStereotypePropertiesToHide
Pro & Cons
The advantage of this solution is that the mechanism is quite close from the initial one. The CSS can be used as a user preference. It is based on GMF as required. And the intelligent part is done by a controller instead of via the interface directly.
In a other hand, this solution won't work if there are several CSS files used at the same level ( for example for each stereotype) . By default, the CSS mechanism will choose the CSS file with higest priority and ignore the other ones. On top of this, the list management between CSS and Notation file would be difficult to maintain and is a source of troubles.
Label for Each Stereotype
Another solution would be to change the architecture and specify one label for each stereotype. The difficulty here would be that the list of stereotypes that can be applied is not exhaustive. So it is not possible to create an UML object for each type of stereotype. The solution would be then, to create the label directly when the stereotype is applied. This solution avoid the use of lists and with the parameter "isVisible" can be shown or hidden from the CSS file without duplicating properties.
Architecture
The Architecture is quite similar to the NamedStyle solution, except the new Label element with the following properties:
- Type
- Stereotype
- isVisible
- QNDepth
- Properties
CSS and NamedStyles
NamedStyles will also be used in this solution for the properties that are not designed by default (like the QNDepth) and required into the CSS. The stereotypes would be shown or hidden through the CSS thanks to the following command:
Label[type=StereotypeLabel][name="SysML::Blocks::Block"]{ isVisible : false; depth: "full"; }
Pros & Cons
- Pros : Using one label for each stereotype allows several CSS at the same level. The solution avoids lists of String management. Simple to maintain.
- Cons: The stereotype label is added dynamically into the notation file, and not into the UML model. It could generate refresh issues.
Property View Interface
to be edited
Conclusion
The retain solution will be the Single Label for each stereotype applied. An will be put in place as explained in a further chapter.
Solution Implementation
Architecture
Technically, the DecorationNode will be extended to create StereotypeLabel element into notation file. As well as for the stereotype properties.
Notation Model Structure
Structure into Notation file would be:
Label [type=StereotypeLabel][stereotype ="SysML::Allocations::Allocated"] Compartment [type=StereotypeCompartment][stereotype="SysML::Allocations::Allocated"] Label [type=StereotypeProperty][property ="allocatedFrom=0..*" ] Label [type=StereotypeProperty][property ="allocatedTo=0..*" ]
Structure for the stereotype name Label:
DecorationNode (type = StereotypeLabel) name (String: "SysML::Allocations::Allocated") Stereotype (Stereotype: "SysML::Allocations::Allocated") isVisible (Boolean) depth (String: None, Full, Auto, -1,-2,-3,...)
Structure of the property (to be defined):
DecorationNode (type = StereotypeProperty) inCompartment (Boolean) inBrace (Boolean) inComment (Boolean) isVisible (Boolean)
EditPolicies Hierarchy
Here is the Class diagram that could be the solution for the new architecture:
+Image
To be completed
Intermediate Objectives
To plan the several steps of this whole improvement, it will be splitted into sub-goals.
All the objectives will be first fulfill for the Named Elements (like the Classes, Packages, ...) Once the new structure in place for those elements, it will be done for the other types of elements.
- Objective 1: Display all the stereotypes thanks to DecorationNode with one Label by stereotype.
- Objective 2:
- 2a. Hide stereotypes thanks to CSS.
- 2b. Display Qualified Name of some stereotypes thanks to CSS.
- Objective 3: Display all the properties into the compartment thanks to the DecorationNode into the notation file.
- Objective 4:
- 4a. Hide the properties thanks to the CSS
- 4b. Display properties into braces thanks to the CSS
- 4c. Display properties into comment thanks to CSS.
- Objective 5: Create the graphical user interface into the Appearence Tab
- Objective 6: Propage objectives 1 to 5 to the other element throught their own edit policied.
- Objective 7: Plan a model transformation for a compatibility with old models using EAnnotation.
The following section details the progression of each Objective.
Objective 1
- Display all the stereotypes thanks to DecorationNode with one Label by stereotype.
To fulfill this objective, the following steps should be completed:
- Create and Delete StereotypeLabel through a Recording Command
- Done
- Create / Delete objects when stereotype is applied or deleted.
- Done
- Display the Label through the different EditPolicies
- For Node Label: AppliedStereotypeNodeLabelDisplayEditPolicy
- Done
- For Node Label: AppliedStereotypeNodeLabelDisplayEditPolicy
- Delete all usage of EAnnotation for the Stereotypes (Optionnal at this stage)
- In Progress
Note: Done , means that the task is done but not already comitted. The entire Objective 1 will be committed at once when completed.
Objective 2
- 2a. Hide stereotypes thanks to CSS
- Manage the isVisible parameter into the display of the Stereotype Label
- Done
- Retrieve the "isVisible" value from the CSS
- Not required
- Edit the CSS DOM Tree to match the NamedStyle Value
- Done
- Manage the isVisible parameter into the display of the Stereotype Label
- 2b. Display Qualified Name of some stereotypes thanks to CSS
- Manage the QualifiedName depth into the display of the Stereotype Label
- Done
- Retrieve the "depth" value from the CSS
- Done
- Manage the QualifiedName depth into the display of the Stereotype Label
Objective 3
- Display all the properties into the compartment thanks to the DecorationNode into the notation file.
To fulfill this objective, the following steps should be completed:
- Create and Delete StereotypeProperty through a Recording Command
- Done
- Create / Delete objects when stereotype is applied or deleted.
- Done
- Display the Properties through the different EditPolicies
- For Node Label: AppliedStereotypeNodeLabelDisplayEditPolicy
- Done
- For Node Label: AppliedStereotypeNodeLabelDisplayEditPolicy
Objective 4
- 4a. Hide the properties thanks to the CSS
- Modify the CSS DOM tree to match the NamedStyle Selectors For "StereotypeProperty".
- Done
- Catch the CSS value to hide the corresponded Property.
- Done
- Modify the CSS DOM tree to match the NamedStyle Selectors For "StereotypeCompartment".
- Done
- Catch the CSS value to hide the corresponded Compartment.
- Done
- Modify the CSS DOM tree to match the NamedStyle Selectors For "StereotypeProperty".
- Encounter issue:
- StereotypeProperties Labels are not created when CSS doesn't show the compartment
- Solution: Notify "AppliedStereotypePropertyEditPolicy" when stereotype is applied. Using StereotypeElementListener instead of PapyrusStereotypeListener
- Done
- Solution: Notify "AppliedStereotypePropertyEditPolicy" when stereotype is applied. Using StereotypeElementListener instead of PapyrusStereotypeListener
- Error when refresh figure with an empty Property textFlow
- Solution: Add condition on Text value during TextFlow creation into the AppliedStereotypeMultilinePropertyEditPart
- Done
- Solution: Add condition on Text value during TextFlow creation into the AppliedStereotypeMultilinePropertyEditPart
- StereotypeProperties Labels are not created when CSS doesn't show the compartment
- Encounter issue:
- 4b. Display properties into braces thanks to CSS.
- Add The Location NamedStyle into Notation File
- Done
- Catch the CSS Value for the Location
- Done
- Calculate the New Text to display with Braces
- Done
- Add The Location NamedStyle into Notation File
- 4c. Display properties into a comment thanks to CSS.
- Create the Comment Object.
- In Progress
- Create the link between Comment and EditPart
- Not Started
- Calculate the text to display into the Comment
- Not Started
- Manage CSS property to display or hide properties into Comment
- Not Started
- Edit the Comment text content with the new text value
- Not Started
- Update Content when Stereotypes Applied or unapplied
- Not Started
- Delete Comment when empty
- Not Started
- Create the Comment Object.
Objective 5
- Create the Graphical Interface to display Labels and Properties to override the CSS.
- 5a. Create the graphical user interface into the Appearence Tab
- 5b. Add the selection tree with appropriate collumn
- 5c. Add combo box with QN choices
- 5d. Add Tree commands to Expand / Collapse
- 5e. Add Tree commands to Select All / Deselect All
- 5f. Add Management rules (to be defined )
Objective 6
- Propage objectives 1 to 5 to the other element throught their own edit policied.
- For External Node : AppliedStereotypeExternelNodeEditPolicy
- Not Started
- For External Node label: AppliedStereotypeExternelNodeLabelEditPolicy
- Not Started
- For Icon: AppliedStereotypeIconDisplayEditPolicy
- Not Started
- For Link Label: AppliedStereotypeLinkLabelDisplayEditPolicy
- Not Started
- For External Node : AppliedStereotypeExternelNodeEditPolicy
Objective 7
- Plan a model transformation for a compatibility with old models using EAnnotation.
Open Points and Lessons learned
Open Points
- How an EditPolicy can be called when the Refresh (F5) of the EditPart is executed? It is required to refresh visual after applying a CSS.
- It appears that the super Class GraphicalEditPolicy doesn't implement a refresh method, contrary to the internal class GraphicalEditPolicyEx
- But this class is internal to GMF, so how make the refresh working for the Papyrus editPolicies.
- With CSS, how select a notation element with a specific StringValueStyle? For example with a StringValueStyle "name" with the value "Blocks"?
Lessons learned
- How a CSS selector can match on Notation Element likes [type="StereotypeLabel"] where "StereotypeLabel" is the type of a DecorationNode.
- Clue : The class CSSDOMSemanticElementHelper defines rules to match the sementic Element of a notation view.
- How to define the way the CSS selector match elements?
- Clue: The method doGetAttribute in the class GMFUMLElementAdapter return the corresponding element.
Tasks and Bugs
The bugzilla items tracking progress of this improvments are: