Table of Contents

1. How to programmatically open a table
   1. In your own Composite container
2. Table model
3. Table configuration model
   1. Instantiation methods
4. How to add your own cell editors
   1. unary features
   2. n-ary features
   3. model
   4. extension point
   5. example
5. How to register custom Command factories

How to programmatically open a table

First, you must add these plug-ins to your plug-in dependencies:

• org.eclipse.emf.facet.widgets.table.ui
• org.eclipse.emf.facet.widgets.table.ui.nattable
• org.eclipse.emf.facet.widgets.table.ui.workbench
• org.eclipse.emf.facet.widgets.table.metamodel

Use:

ITableEditorFactory.DEFAULT.openOn(elements, editingDomain, description, tableConfiguration, context, parameter);

• elements : a list of model 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 : a descriptive string to be displayed at the top of the table editor
• 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.

ITableWidgetFactory.INSTANCE.createTableWidget(parentComposite, editingDomainProvider, tableInstance, menuManager);

• parentComposite : the SWT Composite in which the table will be created
• editingDomainProvider : provides an editing domain for enabling editing in the table
• tableInstance : an instance of the Table model element, that represents the table's data model
• menuManager : a menu manager used for creating the table's context menu

The ITableWidget returned by the factory proposes many API methods to manipulate the table. Among which:

• addRows : add model elements as new rows to the table
• createNewElement : create a new model element using an instantiation method defined in a table configuration
• save, saveAs : serialize the table into a XMI model file
• removeLine : remove the selected lines
• selectAll : select every cell in the table
• openLoadCustomizationDialog : open the load customizations dialog to let the user choose customizations
• openLoadFacetSetsDialog : open the load facet sets dialog to let the user choose FacetSets
• selectCell : select a given cell
• editSelectedCell : go into edit mode for the currently selected cell
• selectRows : select the given rows
• addColumns : add the given ETypedElements as new columns
• ...

Table model

A table is fully described by its model : see the metaclass Table in org.eclipse.emf.facet.widgets.table.metamodel. This means that when a table is saved, this model is serialized to an XMI file. This model contains all information needed to represent a table:

• the list of rows (each row points to the EObject it represents) with their height
• the list of columns (each column points to the ETypedElement it represents) with their width
• the loaded customizations and FacetSets
• ...

Table configuration model

A second model is used to define a table configuration. The main metaclass is TableConfiguration in org.eclipse.emf.facet.widgets.table.metamodel. TableConfiguration has the following references:

• canBePresentedInTheTable : a Facet element 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).
• forcedCellEditors : 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.
• instantiationMethods : each instantiation method defines a Facet operation that creates and returns an EObject when called.
• defaultColumns : a list of ETypedElements to show as columns by default
• defaultFacets : a list of Facets to load by default (deprecated)
• defaultCustomizations : a list of customizations to load by default

This table configuration can be passed to TableWidgetUtils#createTableInstance to create a table instance with this configuration.

Instantiation methods

An InstantiationMethod has:

• a name
• a description
• a reference to an EOperation that will be called to instantiate a new EObject

To define an instantiation method, you must create a Facet that extends the metaclass that will be the context when creating new model elements.

For example, write a file instantiationExample.efacet that contains:

<eClassifiers xsi:type="efacet:Facet" name="EPackageExt">
  <extendedMetaclass href="http://www.eclipse.org/emf/2002/Ecore#//EPackage"/>
  <facetOperations xsi:type="efacet:FacetOperation" name="createEClass" lowerBound="1">
    <eType xsi:type="ecore:EClass" href="http://www.eclipse.org/emf/2002/Ecore#//EClass"/>
    <eParameters name="data" eType="ecore:EDataType http://www.eclipse.org/emf/2002/Ecore#//EJavaObject"/>
    <eParameters name="editingDomain" eType="ecore:EDataType http://www.eclipse.org/emf/2002/Ecore#//EJavaObject"/>
    <query xsi:type="javaQuery2:JavaQuery" implementationClassName="com.example.CreateEClass"/>
  </facetOperations>
</eClassifiers>

The FacetOperation has to have two EJavaObject parameters : one for the free data parameter, and the other one for the editing domain.

Then you need to write the Java query implementation that does the actual instantiation. The "source" is the Facet's extendedMetaclass, the return type is the FacetOperation's eType, and the "editingDomain" parameter you receive is the one you defined in your FacetOperation. The query should not modify the model directly, but it should instead do all modifications through the editing domain so that changes can be canceled:

public class CreateEClass implements IJavaQuery2<EPackage, EClass> {
  public EClass evaluate(EPackage source, IParameterValueList2 parameterValues, IFacetManager facetManager)
        throws DerivedTypedElementException {
    EClass result = null;
    EditingDomain editingDomain = null;
    ParameterValue editingDomainParam = parameterValues.getParameterValueByName("editingDomain"); //$NON-NLS-1$
    if (source != null && editingDomainParam != null && editingDomainParam.getValue() instanceof EditingDomain) {
      editingDomain = (EditingDomain) editingDomainParam.getValue();
      ICommandFactory cmdFactory = ICommandFactoriesRegistry.INSTANCE.getCommandFactoryFor(editingDomain);
      EClass eClass = EcoreFactory.eINSTANCE.createEClass();
      Command command = cmdFactory.createAddCommand(editingDomain, source,
          EcorePackage.eINSTANCE.getEPackage_EClassifiers(), eClass);
      editingDomain.getCommandStack().execute(command);
      result = eClass;
    }
    return result;
  }
}

Then you can write instantiationExample.tableConfiguration, that contains the instantiation method and references your instantiation operation defined in the above instantiationExample.efacet:

<instantiationMethod name="Create an EClass" description="Create an EClass">
  <instantiationOperation xsi:type="efacet:FacetOperation" href="platform:/plugin/com.example/instantiationExample.efacet#//EPackageExt/createEClass"/>
</instantiationMethod>

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 = ICommandFactoriesRegistry.INSTANCE.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.

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 extension point org.eclipse.emf.facet.widgets.celleditors.commandFactories.

Copyright © 2010, 2012 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)