Difference between revisions of "Table Developer Documentation"

Revision as of 08:55, 26 September 2014

WORK IN PROGRESS

The Papyrus Table uses the NatTable widget. Its documentation is available here and here. These new table are available since the Papyrus Release 0.10 in June 2013.

The NatTable source code can be downloaded with git http://git.eclipse.org/gitroot/nattable/org.eclipse.nebula.widgets.nattable.git

Label Providers

For the label provider, we divided the tables into 2 areas :

1. Headers
   
2. Body
   

for each areas we declared a label provider context (using the Papyrus Label Provider extension point):

1. org.eclipse.papyrus.infra.nattable.full.labelprovider : the context to use to find the label provider used in the table. This one calls the others label providers according to the region for which we are looking for the text/image to display.
   
2. org.eclipse.papyrus.infra.nattable.body.labelprovider : the context to use to find the label provider used to get the text in the body of the table
   
3. org.eclipse.papyrus.infra.nattable.header.labelprovider : the context to use to find the label provider used to get the text in the header of the table (display icon, display label)
4. org.eclipse.papyrus.infra.nattable.header.feature.labelprovider : the context to use to find the label provider used to display feature in a header. This label provider allows to define the text to display according to the configuration of the axis ( display icon, display label, display multiciplicity, display type, display a "/" for the derived feature)

These contexts are declared into the plugin org.eclipse.papyrus.infra.nattable.

All label provider declared on these context must accept elements implementing ILabelProviderCellContextElement. This object encapsulate the cell for which we want display a text AND useful elements which can be used to define the text/image/color/... to display in the cell.

Papyrus Extension Point For Table :

1. Axis Manager
2. Cell Manager
3. Cell Editor Configuration

Selection synchronization

Some changes have been applied to the code in order to allow a selection synchronization between the tables and the model explorer. The affected classes are the following :
In these changes, IRevealSemanticElement and its associated method revealSemanticElement is at the core of the modifications.

1. org/eclipse/papyrus/infra/nattable/common/editor/AbstractEMFNattableEditor.java
   • where we implement the interface and add the call for the newly created revealSemanticElement method in AbstractNattableWidgetManager and giving it the list of selected objects.
     
2. org/eclipse/papyrus/infra/nattable/manager/table/AbstractNattableWidgetManager.java
   • the method goes through the lines and columns of the tables to find all the elements contained in the list and then proceed to select them graphically in the table.
   • the method used for this is org.eclipse.nebula.widgets.nattable.selection.SelectionLayer.doCommand(ILayerCommand command)
     
3. org/eclipse/papyrus/infra/gmfdiag/common/SynchronizableGmfDiagramEditor.java
   • in the original method the selection only allowed the first selected element found to show. we now collect all found IGraphicalEditParts and proceed to set the selection in the graphicalViewer.
     
4. org/eclipse/papyrus/views/modelexplorer/ModelExplorerView.java
   • in the handleSelectionChangedFromDiagramEditor method the principal problem was that, if revealSemanticElement was called, it shunned the model explorer as it was not an IEditPart and the redundacy of the IAdaptable verification crashed the process.
   • when we are in an IIeditorPart, as we were interested in the Eobject for the contruction of the list of selected elements and that org.eclipse.papyrus.infra.emf.utils.EMFHelper.getEObject(Object source) already checked for the IAdaptability, the direct replacement of the verification was done.
   • as for the selection in the model explorer, we went through org.eclipse.ui.navigator.LinkHelperService.getLinkHelpersFor(Object anObject) to get the list of LinkHelpers and used the LinkHelper in org.eclipse.papyrus.views.modelexplorer.LinkHelper.activateEditor(IWorkbenchPage aPage, IStructuredSelection aSelection) to handle the selection with revealSemantiElement.
     

Modifying the graphical representation of the tables

Resizing Axis and Headers

Three listeners have been added to the AbstractNattableWidgetManager class in order to capture the graphical changes and edit the model.

1. addAxisResizeListener(final BodyLayerStack bodyLayerStack) that listens to the BodyLayerStack
2. addColumnHeaderResizeListener(final ColumnHeaderLayerStack columnHeaderLayerStack) that listens to the ColumnHeaderLayerStack
3. addRowHeaderResizeListener(final RowHeaderLayerStack rowHeaderLayerStack) that listens to the RowHeaderLayerStack

Those methods verify the model in order to know if the graphical values are already present and if not create them and write them using a CompositeCommand and executing it.

The major change introduced in order to accomplish this is the modification of the table's model by adding new Styles, more particularly intValueStyles that are used to carry this specific information. These styles are introduced in the Axis elements, if the changes of size modify axis, or to a newly, or existing, LocalHeaderAxisConfiguration if the changes modify headers. Of course, both of them are now StyledElements and therefore can call on the method getNamedStyle().

• NamedStyle org.eclipse.papyrus.infra.nattable.model.nattable.nattablestyle.StyledElement.getNamedStyle(EClass eClass, String name)
  

Two init methods will also be called when refreshing or opening the table in order to show the modified table.

1. initTableAxis() that gets the list of the displayed axis and check their styles
2. initTableHeaders() that gets the AbstractHeaderAxisConfigurationUsedInTable, allowing the method to get around the invertAxis configuration, and check their styles

Both have a default behavior, in case no styles were attached to an element, to apply its default size to its graphical representation.

Merging cells inside their Axis

The merge is based on nebula's AutomaticSpanningDataProvider (org.eclipse.nebula.widgets.nattable.data.AutomaticSpanningDataProvider) allowing us to apply a spanProvider to the table's BodyLayerStack and, with minor modification of the method valuesNotEqual(), triggering the desired span (i.e. merge) throughout the layer.
To accomplish this four new merge handlers were created, piloted by a menu constituted of exclusive choices.

1. org.eclipse.papyrus.infra.nattable.handler.MergeColumnsHandler
2. org.eclipse.papyrus.infra.nattable.handler.MergeRowsHandler
3. org.eclipse.papyrus.infra.nattable.handler.MergeSelectedRowsHandler
4. org.eclipse.papyrus.infra.nattable.handler.MergeSelectedColumnsHandler

The handlers' model modification behavior are similar to the resize listeners' one, where the style's value is researched in the model and created, or modified, depending on the case, set inside a CompositeCommand and executed inside the core AbstractMergeHandler. The merge boolean will then be carried by the LocalHeaderAxisConfiguration if the user chose to merge all the columns/rows inside the table or by the Axis if the user chose to merge only selected Axis.

To access these handlers, new extensions have been added in the form of a new menu to call on the handlers and a property tester to check the availability of the menu's options or not depending on the merge state of the table; and to update the toggles of each menu, new updateToggleCommandState() have also been added to NattableModelManager, calling on the getToggleState[...]() methods in AbstractNattableManager.
One init method and two Listeners, one for the resourceSet and another for the Layer, are used to update the graphical view throughout the changes.

1. initTableMerge() in wich the list of the displayed axis is obtained and their styles checked
2. resourceSetListener inside the updateCellMap() method in wich the notifications due to the modification of the resourceSet are filtered to keep the ones we want and apply or unapply the styles depending on the user's choices and enabling the use of the undo/redo behavior