The current copy-paste format (layout and style) between diagrams relies on semantic target elements to find out which target element (paste) matches the source element (copy).
This new API allows to perform this copy-paste format based on a semantic source to semantic target map.
As for the standard copy-paste format, only visible elements are concerned by the copy. So if elements are not visible in the source diagram, their styles and layouts will not be copied.
A new API in
org.eclipse.sirius.diagram.ui.tools.api.format.MappingBasedSiriusFormatManagerFactory has been added to make it possible to apply a copy-paste format to an existing or a new diagram with different semantic targets.
The target diagram should have the same description (same definition in the VSM) than the source one.
These methods update the models and need to have access to UI thread. According to these constraints, the methods must be called into a RecordingCommand and run in the UI Thread.
/**
* Apply format on {@code targetDiagram} based on the {@code sourceDiagram}. Format data are applied only for
* diagram elements whose semantic object is provided in the {@code correspondenceMap}.
*
* Calls to this API shall be embedded in a command.
*
* @param sourceSession
* The {@link Session} for the source diagram. Must not be null.
* @param sourceDiagram
* The source diagram. Must not be null.
* @param correspondenceMap
* The mapping function between source diagram elements and target diagram elements Must not be null. In
* the case where {@code sourceDiagram} is a Sequence diagram, must provide a mapping for each semantic
* element of {@code sourceDiagram}.
* @param targetSession
* The {@link Session} for the target diagram. Must not be null.
* @param targetDiagram
* The target diagram. Must not be null.
* @param copyNotes
* Whether or not to copy source diagram notes to target diagram.
* @return The target diagram.
*/
public DDiagram applyFormatOnDiagram(Session sourceSession, DDiagram sourceDiagram, final Map<EObject, EObject> correspondenceMap, Session targetSession, DDiagram targetDiagram, boolean copyNotes)
This first method will perform the copy-paste format from a source diagram to an existing target diagram. The target elements on which the layout and style will be applied are retrieved by using the source-target correspondence map.
Note that if an element in the target diagram has no corresponding source element in the source diagram, this element will keep its current style and layout.
Elements not visible in the source diagram (hidden by user, because of a deactivated layer or because of a filter) are not considered by the copy-paste.
/**
* Apply format on a new {@link DDiagram} for name {@code targetDiagramName} based on the {@code sourceDiagram}.
* Format data are applied only for diagram elements whose semantic object is provided in the
* {@code correspondenceMap}.
*
* Calls to this API shall be embedded in a command.
*
* @param sourceSession
* The {@link Session} for the source diagram. Must not be null.
* @param sourceDiagram
* The source diagram. Must not be null.
* @param correspondenceMap
* The mapping function between source diagram elements and target diagram elements. Must not be null. In
* the case where {@code sourceDiagram} is a Sequence diagram, must provide a mapping for each semantic
* element of {@code sourceDiagram}.
* @param targetSession
* The {@link Session} for the target diagram. Must not be null.
* @param targetDiagramName
* The target diagram name. Must not be null or equal to "".
* @param targetDiagramRoot
* The root EObject for the new diagram. Must not be null.
* @param copyNotes
* Whether or not to copy source diagram notes to target diagram.
* @return The created target diagram.
*/
public DDiagram applyFormatOnNewDiagram(Session sourceSession, DDiagram sourceDiagram, final Map<EObject, EObject> correspondenceMap, Session targetSession, String targetDiagramName,
EObject targetDiagramRoot, boolean copyNotes)
This method will create a new diagram, based on the correspondence map. The new diagram will be created only if the same source diagram description can be applied on the new semantic target. Once the new target diagram is created, the format from the source diagram is applied in the same way than the first method.
Only diagram elements for which an entry exists in the correspondence map will be created. If the new target diagram description has synchronized mapping (that means graphical elements are automatically created according to the mappings defined in the VSM), new graphical elements might appear. If those new graphical elements semantic targets have no entry in the correspondence map, they will not be formatted and will keep their default style and layout.
Elements not visible in the source diagram (hidden by user, because of a deactivated layer or because of a filter) are not considered by the copy-paste.
Filters and layers activated in the source diagram are automatically activated in the target diagram.
If the corresponding option is activated (
copyNotes parameter), existing notes and texts in the source diagram are copied in the target diagram. If a note attachment exists in the source diagram, this one is also created in the target diagram, if the graphical target exists.
The label of Note/Text and target of attachment are used to retrieve a potential existing Note/Text in the target diagram. In other words, if the label is different or if the target of attachment is different, a new Node/Text will be created.
The sequence diagram layout is linked to the semantic model: the vertical or horizontal graphical ordering perfectly match the semantic ordering.
Because of this constraint, this feature can only be applied between sequence diagrams with a perfect match between their semantic models. That means the target semantic model, on which the existing target sequence diagram or the new one are based on, has to be the exact copy of the source semantic model. All target semantic elements have to be present in the corresponding map and all source semantic elements have to be present in the map.