Graphical Modeling Framework/Models/GMFGen

• Documentation
• FAQ
• Troubleshooting
• Get Involved
• Contributors Area
• Ecosystem

GMF

Website

Download

Dev Builds

Update Site releases milestones

Community

Mailing List • Newsgroup • IRC

Bugzilla

Open

Help Wanted

Bug Day

Source

GMF Notation: View CVS repo GMF Runtime: View CVS repo GMF Tooling: View Git Repo, GitHub

The .gmfgen files is used as the configuration file for the generator. This file should not be used for conception of your editor, but rather to tweak the Java code that will be generated.

GMF GenModel is a data model used by GMF to generate diagramming code. The intention of this model is pretty similar to the EMF GenModel. GMF GenModel could be treated as a set of parameters for Xpand/JET templates used to generate code.

This page contains a list of GMF GenModel parameters designed to be changed by the toolsmith. Generated code could be fine-tuned by adjusting corresponding values. If any of these parameters is modified by the toolsmith and stored in a GMF GenModel, the new value should be preserved on next transformation from GMF MapModel to GMF GenModel.

Metamodel

GMF Generation metamodel

Mapping Model to Generator Model

The transformation from the mapping model to the generator model is described here. If you have looked at the *.gmfgen model that was produced in the tutorial, you'll notice that a quite a few things were created in the process. A general overview of the transformation can be seen in the diagram below, which is followed by detail on each step.

From this diagram, you can see that the selected mapping model is first opened and validated. The canvas is processed, followed by each node, and then each link. Finally, the new generator model is saved and validated.

During the processing of the canvas, a GenModelMatcher is created and the EMF genmodel for the domain model is located. If you look at the generator model itself, you will see a large number of properties related to the canvas need to be set, in addition to the plug-in used to deploy our editor. The names given to these properties are determined by a naming mediator. A DiagramRunTimeClass is selected and is the bridge we need to the GMF runtime notation model. In fact, if you open the *.gmfgen model in the EMF editor, you will see the notation model loaded, along with the domain model and ECore model.

During the processing of the nodes, another set of Gen* classes are initialized, in addition to *ModelFacet classes, which hold a reference to the domain model element represented by the node. Runtime notation model counterparts are selected, and if the node has an edit feature, the appropriate facet, GenNodeLabel, etc. are added. One of the more interesting aspects of the genmodel creation is found in how figures are generated by the FigureGenerator. At this stage, JET is used to produce the content of an inner class viewmap, contained in the *EditPart. Finally, tooling for the node is processed, as are child nodes and compartments.

Metamodel contents

GenEditorGenerator

Copyright Text - multi-line text property. Specified text will be included as a top-level comment in the generated .java and plugin.xml files. Be careful – due to the current Java merge settings, top-level comments will not be changed for existing files - only newly generated .java files will be adorned with this comment. To change copyright text in existing .java files, we suggest removing all source files and re-generating code from GMF GenModel.

Diagram File Extension - string property used for the extension of the diagram file. This property should be unique among the generated diagram editors.

Domain File Extension - string property used for the extension of the domain model file.

Dynamic Templates - boolean property used to enable user-defined templates for generating code from this model (see Template Directory property).

Model ID – string property identifying generated diagram. Value of this property will be derived from EMF meta-model name by default. This value should be unique among the generated diagramming plug-ins existing in any Eclipse installation. To create several GMF GenModels (diagrams) for the same meta-model, this string should be changed to make it unique for each GMF GenModel instance.

Package Name Prefix – string property representing valid Java package. This is a common super-package for all the generated Java classes.

Same File For Diagram And Model – boolean property indicating that model elements should be stored in a diagram file, default value == false. GMF allows for generated code to store model elements in two ways:

1. Single file keeping diagram visual information together with model structure (value == true)
2. Two different files - first for model contents and second for diagram-specific visual information (value == false). The structure of model file in this situation will correspond to the file structure created by standard generated EMF editor for this domain model.

It is recommended to use separate file for storing diagram information (default value of this option) to utilize most of the GMF features, for example - creating several diagrams for the same domain model.

Template Directory – string property indicating the path to the root directory with user-defined code generation templates. This property will be used only if Dynamic Templates property was set to true. Value of this property could be either valid EMF URI specifying location of the folder with templates or platform-relative path written in a form: /project-name/path.

GMF is using Xpand templates for code generation. Original templates are located in a template directory inside org.eclipse.gmf.codegen plug-in. To customize generated code user can copy necessary template file(s) from this plug-in into the folder specified as Template Directory and change template(s) content. Modified template(s) will be used on next code generation. Keep in mind that the templates use instructions that are only available in Java 5.0 and later versions. If your default workspace setting for the Java compiler compliance level isn't set to 5.0, you'll have to adjust the project specific setting to 5.0, otherwise the code generation will abort.

GenDiagram

Diagram group

Contains Shortcuts To – multi-value string property specifying a set of domain model file extensions. Generated code will show corresponding files while browsing workspace in dialog available via Create Shortcut… diagram popup menu action. This dialog allows for expanding the visible model files to browse model contents, selecting model element and creating shortcut to it on diagram.

It is necessary to specify at least one file extension in this property to get Create Shortcut… action generated.

It will be possible to create shortcut on a diagram of this type to the model elements from another model during runtime only if:

1. Executed Eclipse instance contains generated GMF diagramming plug-in able to visualize this element as a top-level diagram element.

2. That diagramming plug-in was generated with Shortcuts Provided For property set to allow shortcuts creation on the diagram of this type (see Shortcuts Provided For).

Example1: If two diagrams for two different domain models (domain1 and domain2) should be generated and domain1 diagram should allows shortcutting elements from the domain2 models, then Contains Shortcuts To of the domain1 diagram should contains domain2ModelFileExtension string.

Example2: If diagram should be generated for the domain1 domain model and this diagram should allows shortcutting elements from other domain1 models, then Contains Shortcuts To property of this diagram should contains domain1ModelFileExtension string.

Shortcuts Provided For – multi-value string property specifying a set of Model ID properties of GenDiagrams. Generated code will supply shortcuts for model element if:

1. It is an element of this diagram domain model.
2. Model ID of the diagram asking for a shortcut for this element present in Shortcuts Provided For values (see Model ID).

Example1: If two diagrams for two different domain models (domain1 and domain2) should be generated and domain1 diagram should allows shortcutting elements from the domain2 models, then Shortcuts Provided For property of the domain2 diagram should contains domain1 diagram Model ID.

Example2: If diagram should be generated for the domain1 domain model and this diagram should allows shortcutting elements from other domain1 models, then Shortcuts Provided For property of this diagram should contains its Model ID.

Synchronized – boolean property indicating that synchronized diagram code should be generated (another option is non-synchronized diagram).

Content of the synchronized diagram will always reflect actual state of the model. For example, if the diagram visualizes some part of the model (package), then content of this diagram should be updated on adding/removing element to/from this package.

non-synchronized diagram contains only those elements which were explicitly created on this diagram by user. Synchronization with the model will be performed for such a diagram only once - on creation time if Initialize Diagram File Action was used. This means, Initialize Diagram File Action will populate a diagram with all valid model elements below the model element selected as diagram root on creation time. Due to the specification, UML diagrams are views to the shared model, so could be implemented as non-synchronized diagrams in this case diagram content will not be updated on adding/removing any elements to/from the model, but user will be able to add/remove some elements to these diagrams manually.

Known issue: For synchronized diagrams GMF does not generate the code handling external changes. So, if the model was changed outside of the diagram EditingDomain, then user should take care of triggering the update process for this diagram. The easiest way is to reopen it.

Units – string property holding the name of the constant from MeasurementUnit class described in notation.ecore model (see org.eclipse.gmf.runtime.notation. MeasurementUnit). Valid values: Himetric, Pixel. Default value is Pixel – size of the diagram nodes will be measured in pixels.

In case of Himetric units, diagram element dimensions will be measured in some logical coordinates. One Himetric unit is equal to 1/100 mm on any screen, so diagram elements will have equal visible bounds on different kind of monitors with different resolution. Usually, one display pixel is equal to several logical units, but actual coefficient depends on screen resolution, i.e. for my display this coefficient is about 20 logical unit = 1 pixel.

Validation Decorators – boolean property indicating that ValidationDecoratorProvider should be generated for this diagram. Generated provider will handle the creation of validation violation decorators for diagram elements. (see Validation Enabled)

Validation Enabled – boolean property indicating that ValidationProvider and MarkerNavigationProvider should be generated. These classes are responsible for the execution of EMFT validation process for an instance of user domain model and collecting all the validation rules violations. Violations are represented as diagram resource problem markers.

Editor group

Creation Wizard Category ID – string property holding the identifier of the category where the generated NewDiagramFileWizard will be registered. Default value is org.eclipse.ui.Examples.

Note: the generator assumes that the specified category is already registered from some other plugin.xml, so take care when registering a category from another plug-in, or patch the generated plugin.xml by adding the category registration.

Creation Wizard Icon Path – string representing the relative path to the icon for NewDiargamFileWizard. An icon for diagram domain model file from EMF editor will be used if {reuseEMFIcon} was specified as a value.

Editing Domain ID – string identifier of an EditingDomain attached to this type of the diagram. To make a generated diagram work properly, Editing Domain ID should be unique – i.e. there should be no other diagramming plug-ins working with an editing domain with the same ID.

Providers group

Edit Part Provider Priority, Icon Provider Priority, Marker Navigation Provider Priority, Metric Provider Priority, Modeling Assistant Provider Priority, Notation View Provider Priority, Palette Provider Priority, Parser Provider Priority, Property Provider Priority, Shortcuts Decorator Provider Priority, Validation Decorator Provider Priority, Validation Provider Priority.

These properties hold provider priorities for the corresponding type of the generated providers. Priority could be one of the following enumeration literals: Lowest, Low, Medium, High, Highest. By specifying the correct provider priority, a user can override the generated provider functionality by providing a hand-written one with a higher priority.

GenPlugin

ID - string id of the generated plug-in. The same string will be used as a name of the corresponding plug-in project created in the workspace with all the generated code, so this string should be valid Eclipse plugin project name (unique among the rest of plugins).

Name – string name of the generated plug-in, and can contain any character.

Printing Enabled – boolean property reflecting the fact that Print and Print Preview actions should be generated for this diagram.

Provider – string description of the generated plug-in manufacturer.

Version - string property reflecting the version of generated plugin.

GenEditorView

Icon Path - string representing relative path to the icons for the generated DiagramEditor. An icon for diagram domain model file from EMF editor will be used if {reuseEMFIcon} is specified as the value.

ID - generated DiagramEditor id.

GenPropertySheet

GenEditorGenerator may optionally specify GenPropertySheet. TBD categories, tabs and sections of original extension-point and related to the elements of genmodel

Package name - all property sheet generated classes target this package.

Label Provider Class Name - name of the label provider class to show the property sheet's title (not generated unless needsCaption attribute set to true). Generated code shows the name of the underlaying domain element, if any, by default.

Needs Caption - whether or not you'd like to have a caption in the property sheet.

Read Only - whether properties presented in the property sheet should be modifiable or not.

GenPropertySheet owns tabs, each tab has the following properties:

• id - identifier, non-visible in UI. There are few predefined values that are processed in a specific way.
• label - visual name of the tab.

GenStandardPropertyTab

Indicates use of predefined tab in the property sheet. There are a few at the moment, with ids diagram, advanced and appearance.

GenCustomPropertyTab

Generates a skeleton property tab you are free to modify. There's a special case if the ID of a custom tab is domain, which leads to generating code that tries to get the property source for a domain element associated with the selection. You can have as many tabs as you like.

Tuning property sheet

Note, not all changes to GenPropertySheet and sub-elements are being reconciled. Sorry. We do reconcile label, isReadOnly, needsCaption, class and package names.

I don't need property sheet at all

Just don't add GenPropertySheet to GenEditorGenerator, and that's it. Generated editor class will adapt to IPropertySheetPage and return null. Unfortunately, we don't keep this change between transformations.

Add new page

Create new GenCustomPropertyTab and you'll get a subclass of PropertySection class generated and registered. You'll need to modify it because we have no idea how your properties should appear. Read article with general guidelines on working with tabbed property pages.

Remove predefined page

Look for the page among GenPropertySheet descendants, remove it and regenerate the code. You may need to remove class for old page (unless the page removed was of GenStandardPropertyTab kind) Note, this change is not preserved during gmfmap to gmfgen transformation.

Adding section to predefined page

There's no explicit support for several sections at the same tab in GMF. You could define GenCustomPropertyTab as usuall and the only thing you'll need to change in the generated code is a section registration in the plugin.xml (//propertySections/propertySection/@tab). Refer to the tabbed property sheet article

Alternatively, in case you'd like to add a section to your own GenCustomPropertyTab, you may try to keep the ID of all the tabs the same. In this case section registration code will use the same IDs automatically. However, using same IDs is generally a bad idea.

Another tab name for standard page =

It's easy, just change label of GenStandardPropertyTab to whatever title you like and regenerate. Note, you might need to remove tab.<tab id> key from plugin.properties first.

Prohibit properties editing

Piece of cake! Just set read only of GenPropertySheet to true. It's possible to have individual pages protected, although unless you file a bugzilla you'll need to do it manually (using generated code as an example). BTW, there's a known bug about the appearance page ignoring the read-only setting.

Property sheet title

If Need Caption attribute is set to true, a LabelProvider gets generated and registered. Generated code shows plain name of selected element by default. You can modify it as you see fit for your needs

Adding a column to the standard properties view

Actually, this is not GMF question. Start with PropertySheetPage and PropertySheetViewer. You'll need to provide your own viewer implementation with Tree or Table control (or any other you find suitable). Take a look at PropertySheetViewer#addColumns() method. AdvancedPropertySection#createControls() hints how to install your own PropertySheetPage. For each GenCustomPropertyTab there's a sub-class of AdvancedPropertySection generated, which is the class to modify.

Customizing Property Sheet

In org.eclipse.gmf.gmfgraph.editor we have customized the property sheet supplied by this editor by customizing gmf.genmodel templates to work with our joint propsheet.ecore metamodel. This actually provided a framework to customize your property sheets. So customizing templates together with providing a joint metamodel for the gmfgen is actually a good example of customizing gmf for making frameworks for it! See our tutorial for How To Customize Property Sheet For Your GMF Editor if you want to know more.

GenNavigator

GenEditorGenerator may optionally contain GenNavigator.

Content Extension ID, Content Extension Name, Content Extension Priority - string properties specifying id, name and priority for generated navigatorContent extension, respectively.

Abstract Navigator Item Class Name, Content Provider Class Name, Label Provider Class Name, Navigator Group Class Name, Navigator Item Class Name - properties for customizing generated class names.

Package Name - string property holding the name of the package for generated navigator functionality.

GenNavigatorChildReference

Group Icon - string representing relative path to the icon for associated logical group.

Group Name - string name of associated logical group. If empty then all child elements will be visible directly below parent element without any additional grouping. See GMF Diagram Navigator Use Cases for a details.

Hide If Empty - boolean property. Associated logical group should not be visible in corresponding place of Project Explorer if empty.

Reference Type - see GMF Diagram Navigator Use Cases for a details.

Custom Behaviour

GenCommonBase (parent of GenDiagram, GenNode and GenLink) owns behaviors. The concept of behavior is basically a representation of GEF's EditPolicy. There are few at the moment, though we might add more in the future. The one I'd like to draw your attention to is CustomBehaviour, which is the way for toolsmith to plug any arbitrary editing behavior in. Just put key and fully-qualified class name of your EditPolicy and generator makes sure it gets installed withou any additional typing/@generated NOT from your side. Though, it's not the full story of CustomBehaviour. It's capable not only of adding behaviour, but also may be handy if you decide to remove already installed editpolicy. Put editpolicy's key and leave class name blank, and generator uninstalls that editpolicy. As an example, if you're among those frustrated with (hard to hit) connection handles that pop up while mouse travels through your diagram, it's easy to turn them off - all you need is CustomBehaviour with key = org.eclipse.gmf.runtime.diagram.ui.editpolicies.EditPolicyRoles.CONNECTION_HANDLES_ROLE.

Code Generation

Currently, GMF uses a forked Xpand to generate source files from its EMF models. The templates are located in the org.eclipse.gmf.codegen plug-in, under the templates directory. They are arranged in commands, editor, parts, policies, and providers folders. Each is loaded by the EmitterFactory and utilized by the main Generator class. Some refactoring is expected in this area, as is the potential to leverage an alternative template technology.

Targeting the Runtime

As GMF provides a large, extensible runtime, many options exist for generation. The extent to which the generation framework leverages runtime extension-points and APIs is expected to vary according to the toolsmith's needs and option settings. What follows below is a description of how the generation framework targets the runtime at the present time, although improvements are ongoing. The tutorial's Mindmap example will be used to provide the context of the discussion.