chapter:MigrationGuide[Migration Guide]

section:VersionOne[From 0.7.0 to 1.0.0]

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

section:SixSeven[From 0.6.0 to 0.7.0]

ul[

item[e[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
e[.parsley] files in the same project.]

item[e[Structure of projects]: the structure of EMF Parsley projects has radically changed
(see ref:DslProjectStructure[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:

ol[
item[Remove the executable extension factory class from the e[src] folder (the DSL will now generate it in the
e[emfparsley-gen] source folder)
img[images/project-migration-exec-ext-fact.png][][ ][]
]
item[Remove the guice module from the e[src] folder, in the example above, it is e[FirstexampleGuiceModule]]
item[Modify the activator: instead of extending e[EmfParsleyAbstractActivator] it must extend the
standard codeRef[org.eclipse.ui.plugin.AbstractUIPlugin]; then remove the method

code[Java][
public EmfParsleyGuiceModule createModule()
]
]
item[Manually remove all the contents of the e[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)
img[images/project-migration-clean-gen.png][][ ][]
]
item[Perform a "clean" on the project (so that the contents of e[emfparsley-gen] are generated)]
item[Read the next part about e[plugin.xml]]
]
]

item[e[The plugin.xml and the new EMF Parsley builder]: the way we handle the
e[plugin.xml] has improved, and we also automatically merge subsequent changes in the
DSL file e[parts] section.  Please have a look at ref:PluginXml[How the DSL handles the plugin.xml] for
the details.

IMPORTANT: This merging takes place ONLY if your project has the e[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 e[plugin.xml_emfparsley_gen] from the root
of your project, and perform a clean of the project.
]

item[e[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 e[InjectorProvider]
class which is automatically generated for each DSL module (see ref:InjectorProvider[Obtaining the Injector]).

For example, in the first example,
ref:FirstExample[First Example], instead of doing

code[Java][
FirstexampleActivator.getDefault().getInjector();
]

you need to do

code[Java][
FirstexampleInjectorProvider.getInjector();
]
]

]

section:FiveMinors[From 0.5.0 to 0.6.0]

ul[

item[The way we handle the codeRef[org.eclipse.emf.edit.domain.EditingDomain] 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,
ref:EditingDomain[Editing Domain].]

item[e[Tree With Columns]: a new component has been added:

The e[Tree With Columns Component] provides a tree representation just like ref:TreeComponent[Tree Component],
but it also shows table columns representing the features of the specified codeRef[org.eclipse.emf.ecore.EClass].

IMPORTANT: the codeRef[org.eclipse.emf.ecore.EClass] is used to retrieve the features to be shown, and
NOT to filter elements to be shown (as opposite to the ref:TableComponent[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
codeRef[org.eclipse.emf.ecore.EClass] is the e[Writer] so the columns show the features of the
e[Writer]'s class.  Some of these features, e.g., e[address], e[firstName] and e[lastName], are defined
in the superclasses of e[Writer].  The objects of class e[Employee] have these features as well, while
they don't have features that are specific of e[Writer], e.g., e[name] and e[books], thus the corresponding
cells for employees will be empty.

img[images/03-components-treecolumns.png][][ ][]

e[EMF Parsley] provides a factory that can be used to create such a component, like in the code below:

code[Java][
@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 ref:TreeComponent[] and ref:TableComponent[].
]

item[e[EmfSelectionHelper] only deals with selection element; utility methods for events is now
delegated to e[EmfEventHelper].]

item[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:

code[EmfParsley][
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
	}
}
]

code[EmfParsley][
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)
	}
}
]
]
]

section:FourFive[From 0.4 to 0.5]

ul[
item[e[ViewerInitializer] has been removed: all creation and initialization of viewers
is performed using codeRef[org.eclipse.emf.parsley.viewers.ViewerFactory]; its API has been
revised and simplified.]
item[the packages e[factories] and e[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.]
item[e[IViewerMouseListener] has been moved from the e[listeners]
package to the e[viewers] package.]
item[classes in e[editor.outline] have been moved into e[editors]
package.]
item[The creation of caption labels for forms and dialogs has slightly
changed, concerning the default behavior
(link[https://bugs.eclipse.org/bugs/show_bug.cgi?id=472691][https://bugs.eclipse.org/bugs/show_bug.cgi?id=472691]):
we take the text from codeRef[org.eclipse.emf.edit.provider.IItemPropertyDescriptor] 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
codeRef[org.eclipse.emf.parsley.ui.provider.FormFeatureCaptionProvider] or
codeRef[org.eclipse.emf.parsley.ui.provider.DialogFeatureCaptionProvider]

code[Java][
public Label getLabel(Composite parent, EClass eClass, EStructuralFeature feature)
]

be warned that this method has changed its signature into

code[Java][
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.
]
item[a new method is available in codeRef[org.eclipse.emf.parsley.edit.action.EditingMenuBuilder],
e[actionChange]: If you want to implement more complex menu commands that do not
only add elements to a container, you can use the method
e[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
link[https://bugs.eclipse.org/bugs/show_bug.cgi?id=475188][https://bugs.eclipse.org/bugs/show_bug.cgi?id=475188]).
Please also have a look at the updated documentation of section ref:ContextualMenu[Contextual Menu]:
the already existing e[actionAdd] should be used with care, since it might leave the model
with dangling references -- with that respect we also updated the first example
ref:FirstExample[First Example], so that
it uses e[actionChange] to implement correctly what we used to achieve with e[actionAdd].
]
item[Adding context menu to a viewer has been extremely simplified
(link[https://bugs.eclipse.org/bugs/show_bug.cgi?id=455727][https://bugs.eclipse.org/bugs/show_bug.cgi?id=455727]):
A context menu can be added to any codeRef[org.eclipse.jface.viewers.StructuredViewer] by using an
injected codeRef[org.eclipse.emf.parsley.menus.ViewerContextMenuHelper]. This provides some
methods for adding the context menu

code[Java][
@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);
]
]
item[Drag and drop support has been separated from context menu support
(link[https://bugs.eclipse.org/bugs/show_bug.cgi?id=475914][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 codeRef[org.eclipse.jface.viewers.StructuredViewer] by using an
injected codeRef[org.eclipse.emf.parsley.edit.ui.dnd.ViewerDragAndDropHelper],
using its methods e[addDragAndDrop].
]
item[
Saveable table views and table views reacting on selection
do not require an implementation of the method
e[getContents()], which has also been removed from the API, from the
codeRef[org.eclipse.emf.parsley.config.Configurator] methods, and from
the e[configurator] section in the DSL: contents retrieval is completely
delegated to the new codeRef[org.eclipse.emf.parsley.edit.ui.provider.TableViewerContentProvider],
whose default implementation is able to automatically retrieve all the
contents of a given type (i.e., EClass) automatically.
The DSL provides the new e[tableViewerContentProvider] specification,
see the new section ref:TableViewerContentProvider[Table Viewer Content Provider].
]
item[
Similarly, table views reacting on selection
do not require an implementation of the method
e[getEStructuralFeature()]: they require an implementation of
e[getEClass()] which specifies the type of the objects to be
shown in the table.
e[getEStructuralFeature()] has also been removed from the API, from the
codeRef[org.eclipse.emf.parsley.config.Configurator] methods, and from
the e[configurator] section in the DSL: contents retrieval is not
performed using a feature (which is limitative): it is completely
delegated to the new codeRef[org.eclipse.emf.parsley.edit.ui.provider.TableViewerContentProvider],
whose default implementation is able to automatically retrieve all the
contents of a given type (i.e., EClass) automatically.
]
]

section:ThreeFour[From 0.3 to 0.4]

ul[
item[e[EmptyResourceInitializer] has been removed: you should now use
codeRef[org.eclipse.emf.parsley.resource.ResourceManager],
see section ref:ResourceManager[Resource Manager]]
item[e[ResourceSaveManager] has been removed: you should now use
codeRef[org.eclipse.emf.parsley.resource.ResourceSaveStrategy],
see section ref:ResourceSaveStrategy[Resource Save Strategy]
]
item[Project wizards have been redesigned: they generate a e[module.parsley]
that uses the e[configurator] for specifying required information
(see section ref:Configurator[Configurator] and the updated
first example, section ref:FirstExample[First Example])]
]