Jump to: navigation, search

Difference between revisions of "GMF Diagram Navigator Use Cases"

(Label Provider)
(GMF GenModel modifications)
 
(9 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
== Use Cases ==
 
== Use Cases ==
 
In addition to diagram surface, [[Graphical Modeling Framework|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.
 
In addition to diagram surface, [[Graphical Modeling Framework|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 ===
 
=== 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 [[GMF GenModel|gmfgen]] model structure, so all the features described below should have a reflection in [[GMF GenModel|gmfgen]] model. Then we are talking about “selected set” of ''View''s, this set should be selected based on visualID attribute attached to each ''View'' using an information stored in [[GMF GenModel|gmfgen]].
 
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 [[GMF GenModel|gmfgen]] model structure, so all the features described below should have a reflection in [[GMF GenModel|gmfgen]] model. Then we are talking about “selected set” of ''View''s, this set should be selected based on visualID attribute attached to each ''View'' using an information stored in [[GMF GenModel|gmfgen]].
 
  
 
It should be possible to provide modified notation model structure into the navigator, with following modifications:
 
It should be possible to provide modified notation model structure into the navigator, with following modifications:
 
  
 
- Show only selected subset of the ''View''s existing in notation model.
 
- Show only selected subset of the ''View''s existing in notation model.
  
'''''Example''''': hide ''View''s representing labels on diagram.
+
hide ''View''s 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 [[GMF GenModel|gmfgen]] model.  
 
- Introduce additional group (category) below any ''View'' containing some set of child views. This additional group should has own name and icon specified in [[GMF GenModel|gmfgen]] model.  
  
'''''Example''''': 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.
+
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 ''View''s existing in underlying notation model from the navigator tree, show all their child elements directly below their parents.
 
- Hide some ''View''s existing in underlying notation model from the navigator tree, show all their child elements directly below their parents.
  
'''''Example''''': Do not show compartments in navigator - show all the attributes just below the class node.
+
Do not show compartments in navigator - show all the attributes  
 
+
just below the class node.
  
 
- Show selected subset of the ''Edge''s below any node in navigator. All ''Edge''s visible on diagram are stored in ''Diagram'' node inside notation model.  
 
- Show selected subset of the ''Edge''s below any node in navigator. All ''Edge''s visible on diagram are stored in ''Diagram'' node inside notation model.  
  
'''''Example''''': All generalization links should be visible just below the ''Diagram'' node in navigator.
+
All generalization links should be visible just below the ''Diagram''
 
+
node in navigator.
'''''Example''''': Group called “association links” should be created below the ''Diagram'' node in navigator, all association links should go to this group.
+
  
 +
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.
 
- Show incoming/outgoing links below the corresponding ''View'' representation in navigator or in additional logical group.
  
'''''Example''''': All outgoing association links should be located below the class node in navigator (/below the special group “association links”).
+
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 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 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.  
 
- Show link destination as a child element of link source.  
  
'''''Example''''': 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.
+
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 ===
 
=== Label Provider ===
Each node provided into Package Explorer view below diagram file should has label and icon.  
+
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.
  
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 Package Explorer label.
 
 
- ''GenLabel''/''GenChildLabelNode'' - label should be the same as on diagram
 
- ''GenLabel''/''GenChildLabelNode'' - label should be the same as on diagram
 +
 
- ''GenCompartment'' – compartment title should be used
 
- ''GenCompartment'' – compartment title should be used
 +
 
- ''GenNode''/''GenLinks'' without labels and ''GenDiagram'' – label feature of underlying semantic model element 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.
 
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 ''ImageDescriptor''s 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 ===
 
=== 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 ==
 
== Implementation details ==
 +
 +
=== GMF GenModel modifications ===
 +
Following classes was added to [[GMF GenModel]] to cover requested use cases:
 +
 +
[[Image:gmfgen.jpg]]
 +
 +
''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'' - Re''source.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.

Latest revision as of 15:18, 25 September 2006

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:

Gmfgen.jpg

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 LinkDiagram.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.