Diagram Partitioning Cookbook
This cookbook was moved from the GMF Newsgroup. It is based on work from Norbert Schöpke. Please improve the cookbook if you can.
partitioning element/node - the element/node that should exhibit the "open-new-diagram-on-double-click behaviour" super-diagram - the diagram which contains the partitioning node super-mapping - the .gmfmap that maps everything to be displayed in the super-diagram sub-diagram - the diagram that is opened after double-clicking the partitioning node sub-mapping - the .gmfmap that maps everything to be displayed in the sub-diagram
Afaik there are two usecases for diagram partitioning: 1. The types of the elements associated with the opening diagram and the opened diagram are the same.
Often this occurs if you have some kind of containment hierarchy at the root of your domain model (e.g. UML-style package and sub-packages, like in the ECore editor example).
2. the types differ (e.g. the Aquatory and Port elements from the Taipan editor example)
Usecase 1 "same type"
This seems to be the easier task, since you only need one mapping and one generator model. To learn how to do it, download the ECore editor example. It's not my usecase, so please correct any mistakes you find... >From what I understand you have to do the following:
- in the mapping file (there is only one in this case), locate the node mapping for the partitioning element
(in the ECore editor its the EPackage top node reference mapped as being contained in the eSubpackages)
- look for the "Node Mapping" node's property section "Misc." with a property called "Related Diagrams"
- activate the dialog for "Related Diagrams" and choose the only available Canvas Mapping from the list
- save the mapping and create the .gmfgen generator model
- in the .gmfgen locate the "Gen Top Level Node" corresponding to the partitioning element (under "Gen Diagram xyz") (in the ECore editor its the EPackage2EditPart; as you an also see the "Gen Diagram" node also refers to the same type, thats why it has a "2" in its name)
- there should be an "Open Diagram Behaviour" node; if not you can add one by right-clicking on the gen top level node
- here, the two fields "Diagram Kind" and "Editor ID" should be empty, indicating it's actually the same kind of diagram
editor that should open. Leave the other fields alone unless you know why you have to change them.
Usecase 2 "different type"
This gets more complicated as you need two generator models. I will try to explain what I did to get it working. I don't claim it's the only way to do it or if there is a better way, so comments are appreciated.
1. Derive a pair of .gmfgraph and .gmftool from your .ecore, selecting your model root element as diagram root.
I defined the stuff for both the super-diagram and the sub-diagram in those, but I think it's also possible to create
two separate pairs.
2. Derive a .gmfmap using your .ecore and above 2 files in the dashboard wizard. This is the super-mapping.
Here you should define everything that displayed in the super-diagram, including the partitioning node mapping. But don't waste to much time on configuring all the mappings until you know the editor behaves as you want.
3. Create the generator model for the super-mapping and open it with the GMF editor.
Select the first sub-node called "Gen Plugin" node under "Gen Editor Generator". Set a distinct "ID" and "Name" here that somehow refers to your super-diagram, e.g.
4. Derive a second .gmfmap using your .ecore and the second 2 files in the dashboard wizard. This is the sub-mapping.
Select your partitioning element as diagram root element.
5. Create the generator model for the sub-mapping and open it with the GMF editor.
Select the first sub-node called "Gen Editor Generator". Set your preferred diagram and domain file extensions to the same values as you set for the super-mappings .gmfgen. Important: Make sure the "Model ID" property has a unique value, i.e. different from the one for the super-mapping. Modify the "Package Name Prefix" now if the default doesn't suit you because we need it later.
6. Now comes a "hacky" part. During creation of the generator model for the sub-mapping I selected my one and only .genmodel. The "Model Name" property therein is used to generate the default names of almost every class specified in the generator model. E.g. the "Edit Part Provider Class Name" property is pre-filled with <ModelName>EditPartProvider. So if you want the class names correspond to your sub-diagram root element name (as it should be) you'll have to rename every darn class name in the .gmfgen! That's not very convenient, but maybe there is a workaround for that? I already tried to temporarily change the model name in my .genmodel. If you create the .gmfgen now, the class names look alright. But, here's the catch: they don't get written out to the XML. So if you change the model name in the .genmodel all class names in .gmfgen change but the file doesn't even get dirty! You'd have to activate every property that holds a class name, change it (e.g. by appending a letter) and press enter (now the editor shows the file as dirty with the "*"). Now you edit the property again by reverting your change (but not using Undo!) and then the change is permanent. Rinse and repeat for the dozens of other class names all over the .gmfgen and finally wake from your editing trance.
I just worked around that problem by creating a second .genmodel file as a copy of the original .genmodel. The only change I made was to set the "Model Name" property to the value I needed as prefix for all the class names in the sub-mappings .gmfgen. Of course I also needed to .genmodel references. I did it with find/replace but I guess one could also just load the new resource and drop the old one...
7. This step seems to be optional, since its only purpose is to get GMF to create an "Open Diagram Behaviour" entry in the .gmfgen of the super-mapping. Since I can simply add this myself I didn't bother. But it might be useful in cases where you actually have two .gmfgraph files and two mappings defined and can point to that second "Canvas Mapping"...So here goes:
Go back to the super-mapping and select the top-most node. Right-click and select "Load Resource...". Browse your workspace to locate your sub-mapping .gmfmap file. Now select the node mapping of the to-be-double-clicked element (in my case its under the only top node reference). In the properties there is a "Misc" section having a property called "Related Diagrams". When activated it opens a dialog where you can select from 2 "Canvas Mapping" choices. You can't distinguish between these 2 choices, but don't be scared. They correspond to your 2 mappings. Just try selecting the second choice, save, and open your super-mapping .gmfmap in a text editor. There should be a new tag "relatedDiagrams" referencing your sub-mappings diagram node (in my case: href="ThetaModel.gmfmap#//@diagram")
8. Re-generate the generator model for your super-mapping.
Locate the "Gen Top Level Node" (under "Gen Diagram") corresponding to your partitioning element. If the "Open Diagram Behaviour" entry doesn't exist, add it manually. For the "Diagram Kind" property fill in the name of your partitioning element. You may also look it up in the
sub-mappings .gmfgen file. It's the "Model ID" property under "Gen Editor Generator".
For the "Editor ID" property you also look up the value in the sub-mappings .gmfgen. It's the "ID" property under
"Gen Editor Generator"->"Gen Editor View".
Important: Whenever you change the "Package Name Prefix" of the sub-mappings .gmfgen this ID will change and break
your code! You'll have to adjust the Open Diagram Behaviour accordingly.
9. If all goes well you can now generate two plugins with code for the super-mapping and the sub-mapping.
Both must be checked in your runtime config. The diagram should no open when double-clicking the partitioning node. Now you may complete your mappings and also remove some duplicate parts. For instance, the "Gen Navigator" node may
be deleted from the sub-mappings .gmfgen, because it duplicates all nodes in the diagram content navigator view. Also, you may want to adjust the tool palettes to only hold tools for nodes that make sense for the particular diagram.
I Get a circle (stroken through by a line) when i double click on the concerned element
The cause is that either the wrong editor was loaded on double-click or the editor was out of date. (The circle indicates an element which can't be displayed because the editor has no graphical representation for it.)