GMF Diagram Navigator Use Cases

This page contains main use cases for generated model navigator visualizing diagram file contents and some details concerning current implementation of this functionality.

Use Cases

In addition to diagram surface, GMF should take care on providing diagram file contents for standard eclipse Project Explorer view (visible under General/Project Explorer category). This task consists of generating content, label, action providers and d&d interchange with diagram surface to operate on provided sub-tree below the diagram file node in Project Explorer.

Content Provider

Diagram contents should be provided below the diagram file node selected based on diagram file extension. Provided structure should corresponds with the diagram file content (notation model stored there) with some extensions described below. Generated code should be based on gmfgen model structure, so all the features described below should have a reflection in gmfgen model. Then we are talking about “selected set” of Views, this set should be selected based on visualID attribute attached to each View using an information stored in gmfgen.

It should be possible to provide modified notation model structure into the navigator, with following modifications:

- Show only selected subset of the Views existing in notation model.

hide Views representing labels on diagram.

- Introduce additional group (category) below any View containing some set of child views. This additional group should has own name and icon specified in gmfgen model.

should be able to create artificial group with name “classes” 
below package diagram and show all the classes from this package
only below this group.

- Hide some Views existing in underlying notation model from the navigator tree, show all their child elements directly below their parents.

Do not show compartments in navigator - show all the attributes 
just below the class node.

- Show selected subset of the Edges below any node in navigator. All Edges visible on diagram are stored in Diagram node inside notation model.

All generalization links should be visible just below the Diagram
node in navigator.

Group called “association links” should be created below the Diagram
node in navigator, all association links should go to this group.

- Show incoming/outgoing links below the corresponding View representation in navigator or in additional logical group.

All outgoing association links should be located below the class node in 
navigator (/below the special group “association links”).

- Show child elements of the links. Edge contains sub-nodes in notation model so, corresponding child elements should be represented in a same way as for normal node.

- Show source/target elements of the links. Should be possible to show source/target node connected with the link either directly below the link node or below the group (something like “outgoing links”/“incoming links”).

- Show link destination as a child element of link source.

If containment reference is visualized as link on diagram, user could ask 
to show two nodes connected with this link as parent and child in model navigator.

Label Provider

Each node provided into Project Explorer view below diagram file should has label and icon.

Label

Should be created based on the corresponding underlying node type and associated semantic element using the following rules:

- for views representing GenNode or GenLink having some labels associated first label text should presented as Project Explorer label.

- GenLabel/GenChildLabelNode - label should be the same as on diagram

- GenCompartment – compartment title should be used

- GenNode/GenLinks without labels and GenDiagram – label feature of underlying semantic model element should be used.

- For Logical Groups the name of the group should be used as a label

User should be able to easily customize labels by specifying "@generated NOT" java-doc comment for the corresponding method and override label creation logic.

Icon

Underlying View type should be used to choose correct icon for Project Explorer. All icons should be cached inside singleton ImageRegistry for diagramming plugin. Default icon should be used if there was no image cached in ImageRegistry yet. This icon should be selected based on View type (ElementType) from generated ???ElementTypes class and will be same as an image returned by generated ???IconProvider.

User should be able to show custom icons in navigator by putting desired ImageDescriptors using corresponding key into plugin ImageRegistry. This could be done by implementing custom getImageRegistry() method and initializing returned registry in accordance.

An icon of Logical Groups should be specified in gmfgen model.

Properties View

Standard Eclipse Properties view should be used to display properties of diagram elements provided into Project Explorer. Properties view should reflect underlying domain element properties. Properties view should be read-only.

Implementation details

GMF GenModel modifications

Following classes was added to GMF GenModel to cover requested use cases:

GenEditorGenerator could optionally contain one GenNavigator instance.

GenNavigator was introduces to hold all necessary properties for generating extension to the Project Explorer view and as a container for GenNavigatorChildReferences describing navigator structure.

Each GenCommonBase instance could be connected with a number of GenCommonBase instances using GenNavigatorChildReferences. This is a way to describe child-parent relationship for Project Explorer tree elements: for each View visible in Project Explorer (parentView) there is corresponding GenCommonBase genmodel element (parentGenModelElement). This parentGenModelElement could be connected with some other GenCommonBase elements (childGenModelElements) via GenNavigatorChildReferences. Generated code will traverse Notation Model tree starting from the selected parentView and look for the View instances (childViews) corresponding to childGenModelElements. ChildViews collected by this traversal process will be visualized as a children of this parentView in Project Explorer tree viewer. All GenNavigatorChildReferences without specified parent are representing root elements of the diagram tree – used to select View instances to visualize as direct children of diagram file.

referenceType attribute of GenNavigatorChildReference used to specify the mode of traversing Notation Model tree. There are four available options:

- children means that View instance corresponding to GenCommonBase referenced as a child from this GenNavigatorChildReference should be one of the direct or indirect (grand-) Notation Model children of parentView.

- out_target - outgoing links and link targets should be traversed while looking for childViews.

parent is GenCommonBase representing EClass on Ecore diagram,
child is GenCommonBase representing EReference -> all outgoing 
EReferences should be visible as a childViews of corresponding
parentView

parent is GenCommonBase representing EReference, child - 
EClass -> type of this EReference should be a childView.

parent is GenCommonBase representing diagram node-1,
child is GenCommonBase representing diagram node-2. 
These two diagram nodes can be connected with diagram link 
representing containment reference in EMF model -> in Project Explorer
node-2 should be childView of node-1.

- in_source – incoming links and link source should be traversed while looking for childViews.

parent is GenCommonBase representing EClass on Ecore diagram,
child is GenCommonBase representing EReference -> all incoming
EReferences should be visible as a childViews of corresponding
parentView

parent is GenCommonBase representing EReference, child -
EClass -> container class of this EReference should be a childView.

- default – referenced childView should be taken from the default storage: For Diagram referenced as child - Resource.getContents() should be examined, in case of Link – Diagram.getEdges(), for top-level Node - Diagram.getChildren().

GenNavigatorChildReferences could hold groupName and groupIcon attribute. If groupName was specified then all the childViews achieved using this GenNavigatorChildReferences should be logically grouped below additional Project Explorer node with corresponding name and icon. childViews achieved by different GenNavigatorChildReferences with the same groupName will be visible below the same logical navigator group.