Last modified by msp on 2025/01/30 12:03
Show last authors
1 This tutorial will introduce another kind of concrete syntax for your models, namely a graphical syntax. Instead of writing models in a textual format, they are created by dragging elements from a palette into a two-dimensional plane. The framework we will employ here is [[Graphiti>>url:http://www.eclipse.org/graphiti/||shape="rect"]], which is based on the [[Graphical Editing Framework>>url:http://www.eclipse.org/gef/||shape="rect"]].
2
3 === Contents ===
4
5
6
7 {{toc maxLevel="2"/}}
8
9 = Defining a Diagram Type =
10
11 The main documentation of Graphiti is found in the [[Eclipse online help>>url:http://help.eclipse.org/juno/nav/23||shape="rect"]], which is also found in the Eclipse application (//Help// → //Help Contents//). If you don't have Graphiti yet, install it from the Juno release update site, //Modeling// category. The first step of this tutorial consists of defining a diagram type for Turing Machines and adding a wizard dialog for the creation of new diagrams.
12
13 1. Read the [[Graphiti Introduction>>url:http://help.eclipse.org/juno/topic/org.eclipse.graphiti.doc/resources/docu/gfw/graphiti-introduction.htm?cp=23_0_0||shape="rect"]].
14 1. Create a new plugin named de.cau.cs.rtprak.login.turing.graphiti (like in previous tutorials, replace "login" by your login name) and add dependencies to the following plugins:\\
15 1*. org.eclipse.core.runtime
16 1*. org.eclipse.core resources
17 1*. org.eclipse.ui
18 1*. org.eclipse.ui.ide
19 1*. org.eclipse.emf.ecore.xmi
20 1*. org.eclipse.emf.transaction
21 1*. org.eclipse.emf.workspace
22 1*. org.eclipse.graphiti
23 1*. org.eclipse.graphiti.ui
24 1*. de.cau.cs.rtprak.login.turingmodel
25 1. Create a class {{code language="none"}}TuringDiagramTypeProvider{{/code}} with superclass {{code language="none"}}org.eclipse.graphiti.dt.AbstractDiagramTypeProvider{{/code}}.
26 1. Open plugin.xml and create an extension for org.eclipse.graphiti.ui.diagramTypes with a //diagramType// element:\\
27 1*. //id: //de.cau.cs.rtprak.TuringDiagramType
28 1*. //type: //turing
29 1*. //name: //Turing Diagram Type
30 1. Create an extension for org.eclipse.graphiti.ui.diagramTypeProviders with a //diagramTypeProvider// element:\\
31 1*. //id~:// de.cau.cs.rtprak.login.TuringDiagramTypeProvider
32 1*. //name~:// Turing Diagram
33 1*. //class~:// name of the {{code language="none"}}TuringDiagramTypeProvider{{/code}} class
34 1. Add a //diagramType// element to the //diagramTypeProvider// with id de.cau.cs.rtprak.TuringDiagramType.
35 1. Create a class {{code language="none"}}TuringFeatureProvider{{/code}} with superclass {{code language="none"}}org.eclipse.graphiti.ui.features.DefaultFeatureProvider{{/code}}.
36 1. (((
37 Add the following constructor to {{code language="none"}}TuringDiagramTypeProvider{{/code}}:
38
39 {{code theme="Eclipse" language="java"}}
40 /**
41 * Create a Turing diagram type provider.
42 */
43 public TuringDiagramTypeProvider() {
44 setFeatureProvider(new TuringFeatureProvider(this));
45 }
46 {{/code}}
47 )))
48 1. Copy [[attach:GraphitiNewWizard.java]] and [[attach:CreationWizardPage.java]] to your plugin, adapting the package name accordingly. These files implement a generic wizard dialog for creating Graphiti-based models.
49 1. Create a subclass of {{code language="none"}}GraphitiNewWizard{{/code}} for specifying a concrete wizard dialog for your models.\\
50 1*. (((
51 Add a constructor that calls a super-constructor with according parameters for configuration:
52
53 {{code theme="Eclipse" language="java"}}
54 super("Turing Machine", "tudi", "turing", "turing",
55 org.eclipse.graphiti.ui.editor.DiagramEditor.DIAGRAM_EDITOR_ID);
56 {{/code}}
57
58 Diagrams are stored in two separate files, one containing the actual Turing Machine model and one containing the specific graphical elements used to represent the model. Here it is assumed that {{code language="none"}}"turing"{{/code}} is the file extension for Turing Machine models (this depends on how you configured your EMF model), while {{code language="none"}}"tudi"{{/code}} will be the file extension for diagrams. //Hint~:// by selecting {{code language="none"}}"tuxt"{{/code}} as domain model file extension your models will be stored in the textual format instead of XMI. However, this requires the created models to always be in a serializable state.
59 )))
60 1*. Implement the {{code language="none"}}createModel{{/code}} method by creating and returning an instance of the top-level element of your Turing Machines, e.g. {{code language="none"}}TuringMachine{{/code}}.
61 1*. Register the new wizard class in your plugin.xml using a //wizard// extension for org.eclipse.ui.newWizards (you only need to choose an id and name and set the correct class name).
62 1. Include the new plugin in your Eclipse run configuration and start it. Create a Turing Machine diagram with your new wizard: //File//→ //New//→ //Other...//→ //Other//→ //Turing Machine//. This opens a Graphiti diagram editor for the new file, but you cannot do anything in that editor, since the palette is still empty.
63 1. In order to open a previously created {{code language="none"}}tudi{{/code}} file, right-click it → //Open With//→ //Other...//→ //Graphiti Diagram Editor//. This setting for {{code language="none"}}tudi{{/code}} files will be saved in your workspace preferences.
64
65 = Creating and Adding Shapes =
66
67 The next step is to write so-called //features// for creating and adding elements to the diagrams. Each type of graphical element requires a //create// feature for the creation of corresponding meta model (//business model//) elements, and an //add// feature for adding a specific graphical representation to the diagram. A graphical representation is modeled with a so-called //pictogram element//, which contains a structure of //graphics algorithms// that specify how the element is rendered.
68
69 1. (((
70 Add the following feature class to your plugin, adapting references to meta model elements to your Turing Machine definition:
71
72 {{code theme="Eclipse" language="java"}}
73 import java.util.List;
74 import org.eclipse.emf.ecore.EObject;
75 import org.eclipse.graphiti.features.IFeatureProvider;
76 import org.eclipse.graphiti.features.context.ICreateContext;
77 import org.eclipse.graphiti.features.impl.AbstractCreateFeature;
78 import org.eclipse.graphiti.mm.pictograms.Diagram;
79
80 import de.cau.cs.rtprak.login.turingmodel.State;
81 import de.cau.cs.rtprak.login.turingmodel.TuringFactory;
82 import de.cau.cs.rtprak.login.turingmodel.TuringMachine;
83
84 /**
85 * A create feature for Turing Machine states.
86 *
87 * @author msp
88 */
89 public class StateCreateFeature extends AbstractCreateFeature {
90
91 /**
92 * Constructor for a state create feature.
93 *
94 * @param fp the feature provider for which the feature is created
95 */
96 public StateCreateFeature(IFeatureProvider fp) {
97 super(fp, "State", "Create a State");
98 }
99
100 /**
101 * {@inheritDoc}
102 */
103 public boolean canCreate(ICreateContext context) {
104 return context.getTargetContainer() instanceof Diagram;
105 }
106
107 /**
108 * {@inheritDoc}
109 */
110 public Object[] create(ICreateContext context) {
111 // get the container business element
112 List<EObject> containerObjects = context.getTargetContainer().getLink().getBusinessObjects();
113 if (containerObjects.isEmpty() || !(containerObjects.get(0) instanceof TuringMachine)) {
114 throw new IllegalStateException("The diagram does not contain a Turing Machine.");
115 }
116 TuringMachine machine = (TuringMachine) containerObjects.get(0);
117
118 // create a new state
119 State state = TuringFactory.eINSTANCE.createState();
120 machine.getStates().add(state);
121
122 // add the corresponding graphical representation
123 addGraphicalRepresentation(context, state);
124
125 return new Object[] { state };
126 }
127
128 }
129 {{/code}}
130 )))
131 1. (((
132 Add the following method to TuringFeatureProvider{{code language="none"}}{{/code}}, defining the content of the diagram editor's palette:
133
134 {{code theme="Eclipse" language="java"}}
135 /**
136 * {@inheritDoc}
137 */
138 @Override
139 public ICreateFeature[] getCreateFeatures() {
140 return new ICreateFeature[] { new StateCreateFeature(this) };
141 }
142 {{/code}}
143 )))
144 1. (((
145 Add the following feature class to your plugin and implement the {{code language="none"}}add{{/code}} method at the TODO note:
146
147 {{code theme="Eclipse" language="java"}}
148 import org.eclipse.graphiti.features.IFeatureProvider;
149 import org.eclipse.graphiti.features.context.IAddContext;
150 import org.eclipse.graphiti.features.impl.AbstractAddShapeFeature;
151 import org.eclipse.graphiti.mm.pictograms.ContainerShape;
152 import org.eclipse.graphiti.mm.pictograms.Diagram;
153 import org.eclipse.graphiti.mm.pictograms.PictogramElement;
154 import org.eclipse.graphiti.services.Graphiti;
155 import org.eclipse.graphiti.services.IGaService;
156
157 import de.cau.cs.rtprak.login.turingmodel.State;
158
159 /**
160 * An add feature for Turing Machine states.
161 *
162 * @author msp
163 */
164 public class StateAddFeature extends AbstractAddShapeFeature {
165
166 /**
167 * Constructor for a state add feature.
168 *
169 * @param fp the feature provider for which the feature is created
170 */
171 public StateAddFeature(IFeatureProvider fp) {
172 super(fp);
173 }
174
175 /**
176 * {@inheritDoc}
177 */
178 public boolean canAdd(IAddContext context) {
179 return context.getNewObject() instanceof State
180 && context.getTargetContainer() instanceof Diagram;
181 }
182
183 /**
184 * {@inheritDoc}
185 */
186 public PictogramElement add(IAddContext context) {
187 // create a pictogram element for the state
188 ContainerShape containerShape = Graphiti.getPeCreateService().createContainerShape(
189 context.getTargetContainer(), true);
190  
191 // TODO specify the concrete representation by adding at least one graphics algorithm to the shape
192  
193 Graphiti.getPeCreateService().createChopboxAnchor(containerShape);
194 link(containerShape, context.getNewObject());
195 return containerShape;
196 }
197
198 }
199 {{/code}}
200
201 Use {{code language="none"}}Graphiti.getGaService(){{/code}} to get a service class for creating graphics algorithms and modifying their properties. You are free to design your model elements as you like. Find more information on how to solve this task in the official [[Graphiti Tutorial>>url:http://help.eclipse.org/juno/nav/23_1||shape="rect"]].
202 )))
203 1. (((
204 Add the following method to TuringFeatureProvider{{code language="none"}}{{/code}}:
205
206 {{code theme="Eclipse" language="java"}}
207 private IAddFeature stateAddFeature = new StateAddFeature(this);
208
209 /**
210 * {@inheritDoc}
211 */
212 @Override
213 public IAddFeature getAddFeature(IAddContext context) {
214 if (stateAddFeature.canAdd(context)) {
215 return stateAddFeature;
216 }
217 return super.getAddFeature(context);
218 }
219 {{/code}}
220 )))
221 1. Test the features in the diagram editor. You should now be able to select "State" in the editor's palette. Use this to create a few states. Note that if you create a state and later change the graphical representation in {{code language="none"}}StateAddFeature{{/code}}, the previously created state will still look the same, since the add feature code is only applied to new states created from the palette.
222
223 = Creating and Adding Connections =
224
225 While states can be represented as simple shapes, transitions are connections between two shapes. The process of creating such connections is similar to that for shapes.
226
227 1. (((
228 Add the following feature class to your plugin, adapting references to meta model elements to your Turing Machine definition and implementing the TODO part:
229
230 {{code theme="Eclipse" language="java"}}
231 import org.eclipse.graphiti.features.IFeatureProvider;
232 import org.eclipse.graphiti.features.context.ICreateConnectionContext;
233 import org.eclipse.graphiti.features.context.impl.AddConnectionContext;
234 import org.eclipse.graphiti.features.impl.AbstractCreateConnectionFeature;
235 import org.eclipse.graphiti.mm.pictograms.Anchor;
236 import org.eclipse.graphiti.mm.pictograms.Connection;
237
238 import de.cau.cs.rtprak.login.turingmodel.State;
239 import de.cau.cs.rtprak.login.turingmodel.Transition;
240 import de.cau.cs.rtprak.login.turingmodel.TuringFactory;
241
242 /**
243 * A create feature for Turing Machine transitions.
244 *
245 * @author msp
246 */
247 public class TransitionCreateFeature extends AbstractCreateConnectionFeature {
248
249 /**
250 * Constructor for a transition create feature.
251 *
252 * @param fp the feature provider for which the feature is created
253 */
254 public TransitionCreateFeature(IFeatureProvider fp) {
255 super(fp, "Transition", "Create a Transition");
256 }
257
258 /**
259 * Retrieve the state linked with the given anchor's parent.
260 *
261 * @param anchor an anchor for the source or target of the new connection
262 * @return the corresponding state, or {@code null} if there is none
263 */
264 private State getState(Anchor anchor) {
265 if (anchor != null) {
266 Object object = getBusinessObjectForPictogramElement(anchor.getParent());
267 if (object instanceof State) {
268 return (State) object;
269 }
270 }
271 return null;
272 }
273
274 /**
275 * {@inheritDoc}
276 */
277 public boolean canStartConnection(ICreateConnectionContext context) {
278 return getState(context.getSourceAnchor()) != null;
279 }
280
281 /**
282 * {@inheritDoc}
283 */
284 public boolean canCreate(ICreateConnectionContext context) {
285 return getState(context.getSourceAnchor()) != null
286 && getState(context.getTargetAnchor()) != null;
287 }
288
289 /**
290 * {@inheritDoc}
291 */
292 public Connection create(ICreateConnectionContext context) {
293 State source = getState(context.getSourceAnchor());
294 State target = getState(context.getTargetAnchor());
295 if (source == null || target == null) {
296 throw new IllegalStateException("Cannot retrieve the source or target.");
297 }
298
299 // TODO create new transition with the specified source and target state
300
301 AddConnectionContext addContext = new AddConnectionContext(context.getSourceAnchor(),
302 context.getTargetAnchor());
303 addContext.setNewObject(transition);
304 return (Connection) getFeatureProvider().addIfPossible(addContext);
305 }
306
307 }
308 {{/code}}
309 )))
310 1. (((
311 Add the following method to {{code language="none"}}TuringFeatureProvider{{/code}}, adding more content to the diagram editor's palette:
312
313 {{code theme="Eclipse" language="java"}}
314 /**
315 * {@inheritDoc}
316 */
317 @Override
318 public ICreateConnectionFeature[] getCreateConnectionFeatures() {
319 return new ICreateConnectionFeature[] { new TransitionCreateFeature(this) };
320 }
321 {{/code}}
322 )))
323 1. (((
324 Add the following feature class to your plugin and implement the {{code language="none"}}add{{/code}} method at the TODO note:
325
326 {{code theme="Eclipse" language="java"}}
327 import org.eclipse.graphiti.features.IFeatureProvider;
328 import org.eclipse.graphiti.features.context.IAddConnectionContext;
329 import org.eclipse.graphiti.features.context.IAddContext;
330 import org.eclipse.graphiti.features.impl.AbstractAddFeature;
331 import org.eclipse.graphiti.mm.pictograms.Connection;
332 import org.eclipse.graphiti.mm.pictograms.PictogramElement;
333 import org.eclipse.graphiti.services.Graphiti;
334 import org.eclipse.graphiti.services.IGaService;
335
336 import de.cau.cs.rtprak.login.turingmodel.Transition;
337
338 /**
339 * An add feature for Turing Machine transitions.
340 *
341 * @author msp
342 */
343 public class TransitionAddFeature extends AbstractAddFeature {
344
345 /**
346 * Constructor for a transition add feature.
347 *
348 * @param fp the feature provider for which the feature is created
349 */
350 public TransitionAddFeature(IFeatureProvider fp) {
351 super(fp);
352 }
353
354 /**
355 * {@inheritDoc}
356 */
357 public boolean canAdd(IAddContext context) {
358 return context instanceof IAddConnectionContext
359 && context.getNewObject() instanceof Transition;
360 }
361
362 /**
363 * {@inheritDoc}
364 */
365 public PictogramElement add(IAddContext context) {
366 IAddConnectionContext addConnContext = (IAddConnectionContext) context;
367 Connection connection = Graphiti.getPeCreateService().createFreeFormConnection(getDiagram());
368 connection.setStart(addConnContext.getSourceAnchor());
369 connection.setEnd(addConnContext.getTargetAnchor());
370
371 // TODO specify the concrete representation by adding at least one graphics algorithm to the connection
372
373 link(connection, context.getNewObject());
374 return connection;
375 }
376
377 }
378 {{/code}}
379
380 Use {{code language="none"}}Graphiti.getGaService(){{/code}} to get a service class for creating graphics algorithms and modifying their properties. You are free to design your model elements as you like. Find more information on how to solve this task in the official [[Graphiti Tutorial>>url:http://help.eclipse.org/juno/nav/23_1||shape="rect"]].
381 )))
382 1. Register the {{code language="none"}}TransitionAddFeature{{/code}} in the {{code language="none"}}getAddFeature{{/code}} method of the {{code language="none"}}TuringFeatureProvider{{/code}} in the same way as done before for the {{code language="none"}}StateAddFeature{{/code}}.
383 1. Test the features in the diagram editor. The palette should now contain an entry for creating transitions.
384
385 = Handling Text Labels =
386
387 The last section of this tutorial is about text labels in the graphical editor. We will use such labels for displaying state names. The steps required for these tasks are given only coarsely here, since you should now be able to find out yourself about the details using the [[Graphiti documentation>>url:http://www.eclipse.org/graphiti/documentation/||shape="rect"]].
388
389 1. Add a {{code language="none"}}Text{{/code}} element to states in the  {{code language="none"}}StateAddFeature{{/code}} in order to display the name of each state.
390 1. Create a new class {{code language="none"}}StateDirectEditingFeature{{/code}} extending {{code language="none"}}AbstractDirectEditingFeature{{/code}} and register it by overriding {{code language="none"}}getDirectEditingFeature{{/code}} in the {{code language="none"}}TuringFeatureProvider{{/code}}. This new feature is responsible for connecting the name attribute of states with the in-diagram text editing box, i.e. retrieving the current text from the attribute and updating it after the user has entered a new value.
391 1. Create a new class {{code language="none"}}StateUpdateFeature{{/code}} extending {{code language="none"}}AbstractUpdateFeature{{/code}} and register it by overriding {{code language="none"}}getUpdateFeature{{/code}} in the {{code language="none"}}TuringFeatureProvider{{/code}}. This new feature is responsible for updating the displayed text when the corresponding attribute in the domain model is changed outside the Graphiti editor. For example you could open the Turing Machine model with the //Sample Reflective Ecore Model Editor //in order to modify attributes. You can activate automatic updates of the diagram by extending {{code language="none"}}isAutoUpdateAtRuntime{{/code}} (resp. {{code language="none"}}Startup{{/code}} / {{code language="none"}}Reset{{/code}}) in the {{code language="none"}}TuringDiagramTypeProvider{{/code}} and returning {{code language="none"}}true{{/code}}. The update feature can be invoked explicitly in other features by calling the superclass method {{code language="none"}}updatePictogramElement{{/code}}.
392 1. Create a new class {{code language="none"}}StateLayoutFeature{{/code}} extending {{code language="none"}}AbstractLayoutFeature{{/code}} and register it by overriding {{code language="none"}}getLayoutFeature{{/code}} in the {{code language="none"}}TuringFeatureProvider{{/code}}. This new feature is responsible for updating the position and size of graphics algorithms of a state when the state is resized in the graphical editor or when the displayed text for the state name is updated. The layout feature can be invoked explicitly in other features by calling the superclass method {{code language="none"}}layoutPictogramElement{{/code}}.
393
394 Implement all created feature classes such that the editor behaves correctly when state names are modified or states are resized. You should aim for a good look-and-feel of your Turing Machine editor. If you like, you may also implement transition labels for displaying triggers and actions of transitions (not required for finishing the tutorial).

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage