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.
EMF Compare/Specifications/EMF Compare UI
THIS PAGE IS ARCHIVED. IT IS PROBABLY OUTDATED AND WILL NOT BE UPDATED
EMF Compare UI Specifications [ARCHIVED]
In this document we will present the different functionalities and specifications that will be provided by the EMF Compare UI tool. The UI will contain two principal parts : the first one will present the structural differences between the given files, while the second part will display the input documents and highlight the detected differences in an editor (tree, graphical...), or optionally as a textual representation. The UI will contain other functionalities such as merging documents, saving the actual comparison state, visualizing differences by categories and filtering them.
EMF compare is a part of the Eclipse Modeling Tools and can be integrated as a plug-in into any Eclipse installation. It works for any kind of EMF-based artifact. It provides two/three-way comparison and merging functionality and, to use it, two (or three) documents need to be selected from the Eclipse workspace. With the right-click command “Compare With each other” and according to the selected files' type, the differences and conflicts (in case of three-way comparison) are visualized in a comparison editor. The input documents are presented as trees and the differences are visualized between the edited model versions into three separate parts representing Ancestor (optional, and can be hidden from the view), V0 and V1 of the documents highlighted with colors (blue for changes, yellow for removals, green for the additions and red for conflicts). The result of a comparison can be saved as “emfdiff”, a format specific to EMF Compare, but not as text file by default. New export options can be provided through an extension point. The changes can be “copied” from the left model artifact (V0) to the right one (V1) and vice-versa. Here is the suggested User Interface of the EMF compare tool :
User Interface decomposition
The EMF compare UI can be divided into two parts : the first one is a viewer on top that gives structural textual description of the changes and guides the user through them, and the second part is a side by side approach with two version of the selected files/diagrams. As it’s very useful to provide the comparison tool with means to easily navigate through the changes, merging documents from left to right or vice-versa. The UI is also interactive and responds to the user selections : whenever clicking on an element in any of the viewers –including also the top one with the textual description of the changes— the other viewers scroll and zoom to the corresponding position in the file/diagram.
Part 1 - Structural Differences -
As indicated before, the first part of EMF Compare UI is a viewer at the top of the editor that represents the structural differences between a given set of files. Here is the decomposition of this view :
- Button ‘Export diff model’ : Export the actual diff state with “.emfdiff” extension. New export options can be provided through extension points.
- Combo Box ‘Filters’ : Allows users to filter the displayed differences in the tree view . New filters can be provided through extension points and, by default, four options are provided :
- Changed Elements,
- Added Elements,
- Moved Elements,
- Removed Elements.
- Combo Box ‘Groups’ : Provides the users with the possibility of grouping the diff. New groups can be provided through extension points and, by default, three choices are provided :
- Default : no grouping function to apply,
- Per Kind of change : group the diff according to their type : [others, removed, moved, changed, added],
- Per metamodel element : list the metamodel elements that contain a modified attribute or property.
- Tree View : This component will be dedicated to displaying the structural differences between the input files and it will interact with the selected option in  and . Selecting an element in this tree view will highlight the changed element(s) with a corresponding color in the documents displayed in the bottom part of the UI.
Part 2 - Visualizing Structural Differences -
In order to visualize the structural differences a side-by-side approach is adopted in order to have a global view of the selected documents. On top of exporting, filtering and grouping comparison results, the EMF Compare UI comes with other functionalities which will be detailled in this section.
This second part of the UI is composed as following:
- Combo Box Visualization of Structural Diff : Displays the currently selected comparison type, ans allows users to select another (textual, model ... new comparison engines can be provided through extension points),
- Button Hide Ancestor Pane : This button is hidden by default and displayed only when comparing files that share a common ancestor (three-way comparisons). It can be used in order to show/hide the ancestor pane,
- Button Copy All from left to right : Allows the user to merge all non-conflictual changes from the left to the right,
- Button Copy All from right to left : Allows the user to merge all non-conflictual changes from the right to the left,
- Button Copy Current Change from left to right : Copy the currently selected change from the left to the right,
- Button Copy Current Change from right to left : Copy the currently selected change from the right to the left,
- Button Select Next/Previous Change : Gives users the possibility to navigate between the different changes and conflicts detected for these files.
- Viewer Ancestor Pane : Displays the common ancestor of left and right compared files in the viewer selected through the bottom tabs of this pane.
- Viewer Representation of the selected documents : These two viewers are used to display the two compared versions of the document in the viewer selected through the bottom tabs of this pane.
- Tabbed-Pane : Provides the capability of switching from one viewer to the next. New viewers can be contributed through extension points. By default, EMF Compare provides two different viewers, "differences" and "properties", displaying for the first a tree-based representation of the models, and for the second the properties of a selected model element (if any).