# Migration Guide

## From 0.7.0 to 1.0.0

- API changes If in your custom ControlFactory you were using the field edbc you should now use the getter getDatabindingContext(). Similarly for the field domain: use getEditingDomain().

## From 0.6.0 to 0.7.0

- Multiple DSL files in the same project: thanks to the radical change to the structure of EMF Parsley projects, detailed in the following, it is now possible to define several .parsley files in the same project.
- Structure of projects: the structure of EMF Parsley projects has radically changed (see The structure of an EMF Parsley project). If you have existing projects you need to perform these steps to adjust the compilation errors you will get:
  1. Remove the executable extension factory class from the src folder (the DSL will now generate it in the emfparsley-gen source folder)
  2. Remove the guice module from the src folder, in the example above, it is FirstexampleGuiceModule
  3. Modify the activator: instead of extending EmfParsleyAbstractActivator it must extend the standard AbstractUIPlugin; then remove the method

     public EmfParsleyGuiceModule createModule()

  4. Manually remove all the contents of the emfparsley-gen folder (the name of the generated classes are now prefixed with the module name, but the previously generated ones might still be there)
  5. Perform a "clean" on the project (so that the contents of emfparsley-gen are generated)
  6. Read the next part about plugin.xml
- The plugin.xml and the new EMF Parsley builder: the way we handle the plugin.xml has improved, and we also automatically merge subsequent changes in the DSL file parts section. Please have a look at How the DSL handles the plugin.xml for the details. IMPORTANT: This merging takes place ONLY if your project has the EMF Parsley builder nature. Since version 0.6.1 this nature is automatically applied to the projects created with our wizard. In existing projects, you have to enable the nature yourself by right-clicking on the project, then "Configure" and then "Enable EMF Parsley builder. Once you added this new nature, please remove the plugin.xml_emfparsley_gen from the root of your project, and perform a clean of the project.
- InjectorProvider: the activator generated by the project wizard does not provide anymore a means to retrieve the injector. This functionality is now implemented by an InjectorProvider class which is automatically generated for each DSL module (see Obtaining the Injector). For example, in the first example, First Example, instead of doing

  FirstexampleActivator.getDefault().getInjector();

  you need to do

  FirstexampleInjectorProvider.getInjector();

## From 0.5.0 to 0.6.0

- The way we handle the EditingDomain (src) is changed and improved to some extent. In standard scenarios this should not require any modifications. In advanced scenarios this will provide complete control on the editing domain. We refer to the new section in the documentation, Editing Domain.
- Tree With Columns: a new component has been added: The Tree With Columns Component provides a tree representation just like Tree Component, but it also shows table columns representing the features of the specified EClass (src). IMPORTANT: the EClass (src) is used to retrieve the features to be shown, and NOT to filter elements to be shown (as opposite to the Table Component). If a given row in the tree represents an object whose class does not have the feature for a given column, then the corresponding table cell for that object will be empty. For example, the following screenshot shows a tree with columns representing a library; the specified EClass (src) is the Writer so the columns show the features of the Writer's class. Some of these features, e.g., address, firstName and lastName, are defined in the superclasses of Writer. The objects of class Employee have these features as well, while they don't have features that are specific of Writer, e.g., name and books, thus the corresponding cells for employees will be empty.
  EMF Parsley provides a factory that can be used to create such a component, like in the code below:

  @Inject ViewerFactory viewerFactory;
  (...)
  treeViewer = createTreeViewerWithColumns(parent, getEClass(), getContents());

  Since this component mixes the features of a tree and a table, the customizations are basically the same shown in the subsections of section TreeComponent and section TableComponent.
- EmfSelectionHelper only deals with selection element; utility methods for events is now delegated to EmfEventHelper.
- label provider for trees and table label providers for tables can now specify declaratively custom fonts, foreground and background colors. For tables, you can customize the font, foreground and background color for the entire row or for a single cell. Here are some examples:

  labelProvider{
  ...
  font {
  Book -> // must return a org.eclipse.swt.graphics.Font
  }
  foreground {
  Book -> // must return a org.eclipse.swt.graphics.Color
  }
  background {
  Book -> // must return a org.eclipse.swt.graphics.Color
  }
  }

  tableLabelProvider {
  ...
  font {
  Library : name -> JFaceResources.getFontRegistry().getBold(JFaceResources.DEFAULT_FONT)
  }
  foreground {
  Library : books -> Display.getCurrent().getSystemColor(SWT.COLOR_BLUE)
  }
  background {
  Library : address -> Display.getCurrent().getSystemColor(SWT.COLOR_GREEN)
  }
  rowFont {
  Library -> JFaceResources.getFontRegistry().getBold(JFaceResources.DEFAULT_FONT)
  }
  rowForeground {
  Library -> Display.getCurrent().getSystemColor(SWT.COLOR_BLUE)
  }
  rowBackground {
  Library -> Display.getCurrent().getSystemColor(SWT.COLOR_GREEN)
  }
  }

## From 0.4 to 0.5

- ViewerInitializer has been removed: all creation and initialization of viewers is performed using ViewerFactory (src); its API has been revised and simplified.
- the packages factories and builders have been removed and their classes have been moved to other packages. If you get compiler errors, a simple "Organize Imports" should fix the imports. If you use the DSL a simple regeneration should fix things.
- IViewerMouseListener has been moved from the listeners package to the viewers package.
- classes in editor.outline have been moved into editors package.
- The creation of caption labels for forms and dialogs has slightly changed, concerning the default behavior (https://bugs.eclipse.org/bugs/show_bug.cgi?id=472691): we take the text from IItemPropertyDescriptor (src) if the EObject provides it. (This does not happen for table column headers, since we don't have any EObject when we build the table columns). If you used to call this method on a FormFeatureCaptionProvider (src) or DialogFeatureCaptionProvider (src)

  public Label getLabel(Composite parent, EClass eClass, EStructuralFeature feature)

  be warned that this method has changed its signature into

  public Label getLabel(Composite parent, EObject o, EStructuralFeature feature)

  and of course also its semantics, since you need to pass an EObject not its EClass.
- a new method is available in EditingMenuBuilder (src), actionChange: If you want to implement more complex menu commands that do not only add elements to a container, you can use the method actionChange, specifying the label for the menu, the model's element that will be affected by the changes specified as a lambda expression (the third argument). The lambda expression will also get the specified model's element as argument. (This is related to https://bugs.eclipse.org/bugs/show_bug.cgi?id=475188). Please also have a look at the updated documentation of section Contextual Menu: the already existing actionAdd should be used with care, since it might leave the model with dangling references -- with that respect we also updated the first example First Example, so that it uses actionChange to implement correctly what we used to achieve with actionAdd.
- Adding context menu to a viewer has been extremely simplified (https://bugs.eclipse.org/bugs/show_bug.cgi?id=455727): A context menu can be added to any StructuredViewer by using an injected ViewerContextMenuHelper (src). This provides some methods for adding the context menu

  @Inject ViewerContextMenuHelper contextMenuHelper;
  (...)
  // simplest form
  contextMenuHelper.addViewerContextMenu(viewer);
  // if you have an AdapterFactoryEditingDomain already
  contextMenuHelper.addViewerContextMenu(viewer, editingDomain);
  // if you're inside an IWorkbenchPart
  contextMenuHelper.addViewerContextMenu(viewer, editingDomain, part);

- Drag and drop support has been separated from context menu support (https://bugs.eclipse.org/bugs/show_bug.cgi?id=475914): thus, adding context menu does NOT automatically add drag and drop. Drag and drop can be added to any StructuredViewer by using an injected ViewerDragAndDropHelper (src), using its methods addDragAndDrop.
- Saveable table views and table views reacting on selection do not require an implementation of the method getContents(), which has also been removed from the API, from the Configurator (src) methods, and from the configurator section in the DSL: contents retrieval is completely delegated to the new TableViewerContentProvider (src), whose default implementation is able to automatically retrieve all the contents of a given type (i.e., EClass) automatically. The DSL provides the new tableViewerContentProvider specification, see the new section Table Viewer Content Provider.
- Similarly, table views reacting on selection do not require an implementation of the method getEStructuralFeature(): they require an implementation of getEClass() which specifies the type of the objects to be shown in the table. getEStructuralFeature() has also been removed from the API, from the Configurator (src) methods, and from the configurator section in the DSL: contents retrieval is not performed using a feature (which is limitative): it is completely delegated to the new TableViewerContentProvider (src), whose default implementation is able to automatically retrieve all the contents of a given type (i.e., EClass) automatically.

## From 0.3 to 0.4

- EmptyResourceInitializer has been removed: you should now use ResourceManager (src), see section Resource Manager
- ResourceSaveManager has been removed: you should now use ResourceSaveStrategy (src), see section Resource Save Strategy
- Project wizards have been redesigned: they generate a module.parsley that uses the configurator for specifying required information (see section Configurator and the updated first example, section First Example)