Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Papyrus/Papyrus Developer Guide/Papyrus diagram generation"

m (Label Visibility Preference)
(16 intermediate revisions by 7 users not shown)
Line 3: Line 3:
 
== How to generate a diagram for Papyrus  ==
 
== How to generate a diagram for Papyrus  ==
  
The generation has to be run in a runtime application.
+
=== Prerequisites ===
  
=== Setup your runtime application  ===
+
Install following Eclipse environment:
 +
* GMF tooling see version http://download.eclipse.org/modeling/gmp/gmf-tooling/updates/releases-3.3.1a
 +
* the xtend2 extensions of GMF tooling.
 +
* xtend editor (to manage file encoding problem) http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/
  
It is strongly recommended to setup your runtime application before running a generation in order to avoid Java Heap Space error.  
+
It is recommended to run the generation in a second Eclipse Application launched from your running Eclipse instance.
 +
Add the following developer plugins to your workspace (first instance).
  
In the ''Run configuration'' menu, you can
+
* org.eclipse.papyrus.gmfgenextension
 +
* org.eclipse.papyrus.codegen
 +
* org.eclipse.papyrus.def
 +
* org.eclipse.papyrus.dev.assistants.codegen (optional, needed in case of generating a diagram assistant, as shown below)
  
*Add specific vm arguments (''-Dosgi.requiredJavaVersion=1.5 -XX:MaxPermSize=256M -Xms40m -Xmx512m -XX:PermSize=64M''):
+
Now use the "debug/run configurations" dialog to create a new Eclipse Application instance and launch it.
  
[[Image:Capture-Run Configurations.gif|400px]]
+
=== Setup your runtime application  ===
  
*Use the arguments define in a *.ini file (for instance the eclipse.ini of your Eclipse)
+
This step is executed in the 2nd Eclipse instance that includes executable versions of the three Papyrus developer plugins that have been added to the workspace of the first instance (see preceding step).
  
[[Image:Capture-Run Configurations Configuration.gif|400px]]
+
Go to Preferences / Java / Code Style. '''Use the code formatter "papyrus_formatter.xml" (in doc/DevelopperDocuments/templates).
  
 
=== Import the required project  ===
 
=== Import the required project  ===
Line 23: Line 30:
 
You will need to import from your workspace the following project into your runtime application (do not copy them) :  
 
You will need to import from your workspace the following project into your runtime application (do not copy them) :  
  
*org.eclipse.papyrus.codegen
+
* the plugin of the diagram you will generate (like org.eclipse.papyrus.diagram.clazz)
*org.eclipse.papyrus.def
+
*the plugin of the diagram you will generate (like org.eclipse.papyrus.diagram.clazz)
+
  
 
=== Update the GMFGen  ===
 
=== Update the GMFGen  ===
  
In your GMFGen, you have to update two properties to take into account the specific Papyrus templates. In the node ''GenEditor'' of your gmfgen files, you have to setup the following properties&nbsp;:<br> '''Dynamic Templates''' to ''true''<br> '''Template Directory''' to ''/org.eclipse.papyrus.def/dynamic-templates3.5/codegen''<br>  
+
In your GMFGen, you have to update two properties to take into account the specific Papyrus templates. If you are extending an existing Papyrus diagram, the setup has (of course) already been done and this step can be skipped.
 +
 
 +
In the node ''Gen Editor Generator'' of your gmfgen files, you have to setup the following properties, as shown in the screenshot below for the example for the state-machine diagram:<br>
 +
'''Template Directory''' to ''/org.eclipse.papyrus.def/xtend''<br>
 +
'''Use Dynamic Templates''' to ''true''
 +
 
 +
[[Image:gmfgen-setup.png]]
  
 
=== Run the generation  ===
 
=== Run the generation  ===
  
To run the transformation, rigth click on your gmfgen file and select the menu '''Generate Papyrus Diagram'''.  
+
To run the transformation, right click on your gmfgen file and select the menu '''Generate Papyrus Diagram'''.
 +
 
 +
== How to Generate the Diagram Assistants Model ==
 +
 
 +
To fit in with the other UML diagrams provided by Papyrus, you will want to provide Diagram Assistants (the pop-up bar and connection handles) in your diagram.  Since the Feb 9 2015 nightly build towards Mars M6, Papyrus has supported modelled diagram assistants.  To get started defining your diagram assistants, generate a <tt>*.assistants</tt> model from the '''GMFGen''':
 +
 
 +
[[Image:generate-assistants-from-gmfgen.png]]
 +
 
 +
In the resulting model, you will want to stream-line the assistants so as not to overwhelm users with too many options in the pop-up bar and connection menus:
 +
 
 +
* delete '''PopupAssistant'''s and '''ConnectionAssistant'''s for element types that are less commonly used
 +
* customize the filters specified by the assistants to restrict the elements on which they are presented to the most appropriate and common scenarios
 +
 
 +
The assistants model depends on the element types described by the diagram's <tt>*.elementtypesconfigurations</tt> model, so be sure to generate that, too.
 +
 
 +
When you are happy with the model (you can hot-deploy it from the workspace for testing as described in the Papyrus User Guide in the on-line help), deploy it on the extension point in your diagram plug-in:
 +
 
 +
[[Image:papyrus-assistants-extension.png]]
 +
 
 +
=== Enabling the Pop-up Bar Assistant in your Diagram ===
 +
 
 +
Most shape nodes in the diagram should inherit the <tt>PapyrusPopupBarEditPolicy</tt> by default from the Papyrus diagram infrastructure.  However, most shape compartments (for package contents, activity contents, etc.) will not have this edit policy.  To enable the pop-up bar assistant on these compartments, a context-menu action is contributed to the GMFGen editor by the Papyrus Developer Tools plug-ins:
 +
 
 +
[[Image:add-popupbar-assistant-menu.png]]
 +
 
 +
Select any number of '''GenCompartment'''s in the diagram generator model and invoke this action to generate the required edit policy registration.
  
 
== How to add your own template to the custom Papyrus generator  ==
 
== How to add your own template to the custom Papyrus generator  ==
Line 132: Line 168:
  
 
TODO
 
TODO
 +
 +
[[Category:Papyrus]]

Revision as of 05:09, 26 January 2018

Papyrus editor add some new features to GMF, and needs specific generation. Here is a little guide explaining how to deal with the Papyrus generation stuff.

How to generate a diagram for Papyrus

Prerequisites

Install following Eclipse environment:

It is recommended to run the generation in a second Eclipse Application launched from your running Eclipse instance. Add the following developer plugins to your workspace (first instance).

  • org.eclipse.papyrus.gmfgenextension
  • org.eclipse.papyrus.codegen
  • org.eclipse.papyrus.def
  • org.eclipse.papyrus.dev.assistants.codegen (optional, needed in case of generating a diagram assistant, as shown below)

Now use the "debug/run configurations" dialog to create a new Eclipse Application instance and launch it.

Setup your runtime application

This step is executed in the 2nd Eclipse instance that includes executable versions of the three Papyrus developer plugins that have been added to the workspace of the first instance (see preceding step).

Go to Preferences / Java / Code Style. Use the code formatter "papyrus_formatter.xml" (in doc/DevelopperDocuments/templates).

Import the required project

You will need to import from your workspace the following project into your runtime application (do not copy them) :

  • the plugin of the diagram you will generate (like org.eclipse.papyrus.diagram.clazz)

Update the GMFGen

In your GMFGen, you have to update two properties to take into account the specific Papyrus templates. If you are extending an existing Papyrus diagram, the setup has (of course) already been done and this step can be skipped.

In the node Gen Editor Generator of your gmfgen files, you have to setup the following properties, as shown in the screenshot below for the example for the state-machine diagram:
Template Directory to /org.eclipse.papyrus.def/xtend
Use Dynamic Templates to true

Gmfgen-setup.png

Run the generation

To run the transformation, right click on your gmfgen file and select the menu Generate Papyrus Diagram.

How to Generate the Diagram Assistants Model

To fit in with the other UML diagrams provided by Papyrus, you will want to provide Diagram Assistants (the pop-up bar and connection handles) in your diagram. Since the Feb 9 2015 nightly build towards Mars M6, Papyrus has supported modelled diagram assistants. To get started defining your diagram assistants, generate a *.assistants model from the GMFGen:

Generate-assistants-from-gmfgen.png

In the resulting model, you will want to stream-line the assistants so as not to overwhelm users with too many options in the pop-up bar and connection menus:

  • delete PopupAssistants and ConnectionAssistants for element types that are less commonly used
  • customize the filters specified by the assistants to restrict the elements on which they are presented to the most appropriate and common scenarios

The assistants model depends on the element types described by the diagram's *.elementtypesconfigurations model, so be sure to generate that, too.

When you are happy with the model (you can hot-deploy it from the workspace for testing as described in the Papyrus User Guide in the on-line help), deploy it on the extension point in your diagram plug-in:

Papyrus-assistants-extension.png

Enabling the Pop-up Bar Assistant in your Diagram

Most shape nodes in the diagram should inherit the PapyrusPopupBarEditPolicy by default from the Papyrus diagram infrastructure. However, most shape compartments (for package contents, activity contents, etc.) will not have this edit policy. To enable the pop-up bar assistant on these compartments, a context-menu action is contributed to the GMFGen editor by the Papyrus Developer Tools plug-ins:

Add-popupbar-assistant-menu.png

Select any number of GenCompartments in the diagram generator model and invoke this action to generate the required edit policy registration.

How to add your own template to the custom Papyrus generator

To add a new template to the mechanism of generation, you have to :

  1. Add your template xpt to the plugin org.eclipse.papyrus.def under a subfolder of "dynamic-templates3.5/codegen/xpt"
  2. In the plugin org.eclipse.papyrus.codegen, edit the class org.eclipse.papyrus.codegen.PapyrusCodegenEmitters by adding a get method for your template :
public TextEmitter getyourTemplateNameEmitter() {
return newXpandEmitter("xpt::yourTemplatePath::yourTemplateName::yourStartingDefine"); //$NON-NLS-1$
}

where
yourTemplateName is the name of your template
yourTemplatePath is the path to access to your template from the folder xpt. Subfolder has to be separated by ::
yourStartingDefine the define that will start the generation

  1. Edit the class org.eclipse.papyrus.codegen.PapyrusGenerator
  2. Add a method generateXXXPage() :
private void generateDiagramPreferencePage() throws InterruptedException, UnexpectedBehaviourException {
doGenerateJavaClass(emitters.getyourTemplateNameEmitter(), PackageName,
ClassName, Input);
}

where
getyourTemplateNameEmitter() : is the new TextEmitter defined before
PackageName : is the name of the package the class will be contained in. It has to match with the one specified in the template.
ClassName : is the name of the class. It has to match with the one defined in the template.
Input : is the input element. It has to match with the type defined with FOR in your first xpt define.

  1. Call this method in the method customRun().


You just now have to run your transformation as explained before in this page. Be careful to refresh your projects in your runtime application if you generate in this mode.

Papyrus Extension Root Node Description

TODO


Compartment Visibility Preference

Description : This extension allows to define the default visibility for the compartments. The compartments not referenced by this node are visible by default.

Fields for this node:

  • Comment : a comment
  • Visible By Default : true or false, allows to define the visibility preference for the compartments

Warning : Often you have the same preference page for Top Node and Child Node, in this case, you should define your preference for the top node. Currently, we generate in first the Child Node Preference Page, then the Top Node Preference Page erases the Child Node Preference Page.

Compartment Title Visibility Preference

Description : This extension allows to define the default visibility for the titles of compartments. The titles not referenced by this node are visible by default.

Fields for this node:

  • Comment : a comment
  • Visible By Default : true or false, allows to define the visibility preference for the compartments titles

Warning : Often you have the same preference page for Top Node and Child Node, in this case, you should define your preference for the top node. Currently, we generate in first the Child Node Preference Page, then the Top Node Preference Page erases the Child Node Preference Page.

Label Visibility Preference

Description : This extension is used to define the default visibility for the labels (Connection Labels and External Node Labels). The information provided by this node are used in two ways :

  • Define which label should be hidden after the element creation (Preference Page)
  • Provide the role of the label in the Manage Labels dialog.

Fields for this node:

  • Comment : a comment
  • External Node Label : the list of the external node labels which have the specified role
  • Icon Path Role : an icon to illustrate the role of the label
  • Link Labels : the list of the link labels which have the specified role
  • Role : the role of the referenced labels
  • Visible By Default : true or false, allows to define the preference for the labels

The LabelEditPart referenced by the Label Role Node implements the interface ILabelRoleProvider.


Warning with the Preferences Pages : for example, Association can be represented in 3 ways in the Class Diagram :

  • Association link
  • AssociationBranch link
  • Association node

Currently the value of the field "Display Name" of these nodes in the genModel, is "Association". Now, we need to have 2 preferences pages (one for link and one for node). Concerning AssociationBranch, it should have the same name as AssociationLink, but it should be located before AssociationLink in the genModel.


If you don't use this node :

  • you can't manage the display of the labels in the preferences pages and all labels are visible by default.
  • the dialog to manage the labels works (if you have the correct EditPolicy), but it doesn't display the role.

Examples of usage:

  • Labels Preferences for Association

Label Preferences for Association

  • Labels Manager (if you EditPart provides ShowHideLabelEditPolicy)

LabelManager

How to overwrite existing GMF template

TODO

Back to the top