Table of Contents

1. How to programmatically open a table
   1. In an editor
   2. In a view
   3. In your own Composite container
      1. Adding a row to the table
      2. TableInstance
2. How to configure a table
   1. Create a tableconfiguration model
   2. Instantiation methods
3. How to add your own cell editors
   1. unary features
   2. n-ary features
   3. model
   4. extension point
   5. example
4. Derived FacetReference and Derived FacetAttribute Edition
5. How to register custom Command factories

How to programmatically open a table

First, you should add org.eclipse.emf.facet.widgets.nattable.workbench to your plug-in dependencies.

In an editor

Use:

NatTableEditorFactory.getInstance().openOn(elements, editingDomain, tableConfiguration, context, parameter);

• elements : a list of EObject elements to show as rows in the table
• editingDomain : pass an EMF EditingDomain if you want the table to be editable, or null otherwise
• description : to be displayed at the top of the editor
• tableConfiguration, context, parameter : for configuring the table (see section about table configurations). Can be null.

In a view

Use:

NatTableView.openOn(elements, editingDomain, tableConfiguration, context, parameter);

• elements : a list of EObject elements to show as rows in the table
• editingDomain : pass an EMF EditingDomain if you want the table to be editable, or null otherwise
• tableConfiguration, context, parameter : for configuring the table (see section about table configurations). Can be null.

In your own Composite container

The NatTableWidget can be used in any Composite. If the widget is not provided with an IEditingDomainProvider, a default one will be used.

public NatTableWidget(final Composite parent, // The Parent Composite
final IEditingDomainProvider editingDomainProvider, // An Editing domain provider
final TableInstance tableInstanceParam) // An instance of TableInstance

Several actions are already implemented in the NatTableWidget to be called from your composite, such as :

• show/hide actions : setSortColumnsByType(Boolean), setHideEmptyColumns(Boolean) and setOnlyShowCommonColumns(Boolean).
• show/hide selected columns : hideColumns() (opens a selection dialog).
• save/saveAs actions : save(), saveAs().
• Customization loading : loadCustomizations(List<MetamodelView>).
• Facet loading : loadFacet(Facet).

Other actions are implemented direclty in the widget itself, such as :

• actionAddQueryColumn : contextual action to add a query column
• actionCopyToClipboard : action to activate the copy/paste feature on the table
• actionDeleteElement : action to delete a persisted element from the table AND its model
• actionRemoveLine : action to only remove an object from the table ( not the model)

You need to call the menuAboutToShow(IMenuManager) method to use those actions.

Adding a row to the table

You can easily add a row by using the method addRows(List<EObject>).

TableInstance

All the informations contained in a table can be serialized thanks to an EMF metamodel. TableInstance keep several table attributes such as :

• Column with and row height
• References to the EObject contained in the table
• Whether a column is hidden or not
• The list of query columns added to the table

How to configure a table

As a prerequisite, you need to create an EMFFacet project :

Create a tableconfiguration model

• Do New > Other, and select Tableconfiguration model
• Open the model with the Tableconfiguration model editor, which is customized to help you edit this kind of models
• Set the following features on the TableConfiguration root element:
  • Can Be Presented In The Table : an EMF Facet query that takes an EObject and returns a boolean to decide whether this table accepts the EObject. If it doesn't, then the user won't be able to add this element to the table (using the drag and drop feature).
  • Forced Cell Editors : references cell editors from a model of cell editors (see the section about cell editors). These cell editors will take precedence over any other cell editors defined elsewhere.
  • Instantiation Methods : each instantiation method defines an EMF Query that creates and returns an EObject when called.

Instantiation methods

• The query used for the instantiation method takes the context parameter that was passed when opening the table.
• The parameterValues parameter contains a value that you can retrieve using the key InstantiationMethodParameters.getEditingDomainParameter().getName().
• The query should not modify the model directly, but it should instead do all modifications through the editing domain so that the changes could be canceled.

Here is an example of a query that creates a UML Class in a Package that is passed as context:

public Class evaluate(final org.eclipse.uml2.uml.Package context,
    final ParameterValueList parameterValues) throws ModelQueryExecutionException {

  EditingDomain editingDomain = (EditingDomain) parameterValues.getParameterValueByName(
      InstantiationMethodParameters.getEditingDomainParameter().getName()).getValue();

  ICommandFactory commandFactory = CommandFactoriesRegistry.getInstance()
      .getCommandFactoryFor(editingDomain);

  Class newClass = UMLFactory.eINSTANCE.createClass();
  Command command = commandFactory.createAddCommand(editingDomain, context,
      UMLPackage.eINSTANCE.getPackage_PackagedElement(), newClass);
  editingDomain.getCommandStack().execute(command);
  return newClass;
}

How to add your own cell editors

unary features

Cell editors for unary features must be defined in classes that implement the IModelCellEditor interface. You must implement two methods:

• activateCell(…) : This method must create a SWT Control under the given parent Composite.
• getValue() : This method must return the value currently in the control. This is the value that will be assigned to the feature.

When the user accepts the change, you must call the commit() method on IModelCellEditHandler so that the value is set on the feature.

If the user cancels the edition, you should simply call dispose() on your cell editor control.

n-ary features

Cell editors for n-ary features must be defined in classes that implement the INaryFeatureCellEditor interface.

You must implement the activateCell(…) method, to create the SWT Control for the cell editor under the given parent Composite.

For editing n-ary features, you don't call the commit() method. Instead, you should directly execute commands on the given EditingDomain to edit the feature. The commands should be created using the command factory. For example:

ICommandFactory commandFactory = CommandFactoriesRegistry.getInstance().getCommandFactoryFor(editingDomain);
Command removeCommand = commandFactory.createRemoveCommand(editingDomain, eObject, feature, element);

model

Once you have implemented your cell editors, you can reference them in a celleditors model:

• Do New > Other, and select ModelCellEditors model
• Open the model with the ModelCellEditors model editor, which is customized to help you edit this kind of models
• Add definitions for your cell editors:
  • Basic Cell Editor for editing attributes
  • Unary Reference Cell Editor for editing attributes
  • Nary Feature Cell Editor for editing n-nary references or attributes
• For each definition, you must set:
  • the cell id is a unique identifier for the cell editor
  • the cell type is an EClassifier (EClass or EDataType), that defines which type this cell editor can edit. You can set it to EObject if you want it to edit all references, or EDataType if you want it to edit all attributes.
  • cell editor impl is the full qualified name of a Java class that implements the cell editor.

extension point

Then, use the celleditors extension point to register a model of cell editors. For example:

<extension point="org.eclipse.emf.facet.widgets.celleditors.celleditors">
  <cellEditorsModel path="my.modelcelleditors"/>
</extension>

example

For a full working example, you can look at plug-in org.eclipse.emf.facet.widgets.celleditors.ecore.

Derived FacetReference and Derived FacetAttribute Edition

Derived FacetReference and Derived FacetAttribute can be edited as any other editable cells.

However it is necessary to create a "SetQuery" so that the query framework knows what to do with the new value. This "SetQuery" should implements IJavaModelQueryWithEditingDomain interface instead of the usual IJavaModelQuery one, so that every model modification could be performed using EMF Command.

The query framework takes care of retrieving the setQuery, if any, when the cell is being edited. If so, it passes the editing domain to the query and call the basicEvaluate() method.

This query has to be added to every Derived FacetReference or Derived FacetAttribute needed, using the "setQuery" reference of FacetStructuralFeature.

Example :

public Object evaluate(final EObject context, final ParameterValueList parameterValues,
			final EditingDomain editingDomain) throws ModelQueryExecutionException {

		ModelQueryParameterValue parameterValue = parameterValues.getParameterValueByName("newValue");
		Object newValue = parameterValue.getValue(); // Get the new value
		// Here we should create a command like an add one : 
		// Command command = new AddCommand(editingDomain, context, newValue)
		editingDomain.getCommandStack().execute(command);
		return null;
	}

How to register custom Command factories

If you are using a specific editing domain that requires custom Commands, you can register a Command factory:

• Create a class that implements ICommandFactory
• The handles(…) method should return true if the Command factory should handle the given editing domain.
• All the create*Command(…) should be implemented, and return a Command that does the same thing as the original EMF.Edit command of the same name (see DefaultCommandFactory for an example).
• Then register the command factory using the commandFactories extension point.

Copyright © 2010, 2011 CEA LIST. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html. Contributors: Nicolas Bros (Mia-Software) ; Nicolas Guyomar (Mia-Software)