Issue #145 - Modifications to support NatTable in RAP

[fipro78]

Introduced a new helper class org.eclipse.nebula.widgets.nattable.util.PlatformHelper that contains methods to handle situations that differ between platforms.

This class contains the following:

• Special handling for getting IDialogConstants values, because in SWT you access those constants directly from the IDialogConstants interface, in RAP/RWT you first need to get an instance before you can access the contants.
  IDialogConstants are used in the NatTable ExceptionDialog which is mainly used in the NatExporter.
• Methods to get information about the platform, isRAP() and isMAC() to be able to handle situations where processing needs to be skipped completely (e.g. when trying to trigger printing) or to handle situations differently when in RAP or running on a MAC.
• Methods to call methods in SWT and JFace implementations via reflection. This is needed because RAP/RWT does not implement several methods that are defined in SWT and therefore a direct call to this methods works in SWT but fails with an error in RAP.

Following methods are missing in RWT:

• FontMetrics#getDescent()
• FontMetrics#getAscent()
• FontMetrics#getLeading()

These methods are used in AbstractTextPainter, GraphicsUtils and VerticalTextPainter. Without these there are no textdecorations (underline, strikethrough) available in NatTable with RAP. And the location of the text in vertical text representation might be not 100% accurate.

• FileDialog#getFilterIndex()
• FileDialog#setFilterPath(String)
• FileDialog#setOverwrite(boolean)
• FileDialog#setFileName(String)
• FileDialog#setFilterNames(String[])

Used in FileOutputStreamProvider that opens a FileDialog to select the target on exporting a NatTable and in the FileDialogCellEditor.
Note that the FileDialog in RAP can only be used to select a file for upload (SWT.OPEN) and not for saving (SWT.SAVE).
Therefore the FileOutputStreamProvider was modified to create the export with the default filename in a temp directory, which can then be downloaded via RAP API as described in Service Handler and Downloads

• ScrollBar#getIncrement()
• ScrollBar#getPageIncrement()
• ScrollBar#setIncrement(int)
• ScrollBar#setPageIncrement(int)

Used in ScrollBarScroller and is called by ScrollBarHandlerTemplate (only setIncrement(int) and setPageIncrement(int)). As RAP/RWT does not support ScrollBar on a Canvas, this should not have direct effect in RAP, despite that it does not break on opening a NatTable with scrolling in RAP.
Note that to support scrolling in NatTable, there need to be a workaround implementation in a RAP specific NatTable fragment.

• Control#addPaintListener(PaintListener)
• Control#removePaintListener(PaintListener)
• ControlDecoration#showHoverText(String)

These methods are used in the ControlDecorationProvider. The PaintListener methods are used to position the error decoration correctly with the default positioning, because the cell bounds are only available after activateCell().
This means, the SWT.DEFAULT decoration position does not work in RAP.
The PaintListener methods are also used to correct the position of the filter combobox in case filtering removes the scrollbar and the table would therefore be moved. This does also not work on RAP, but is more like a small visual glitch in a special case.

• NatTable/Canvas#addMouseMoveListener(MouseMoveListener)
• NatTable/Canvas#addMouseTrackListener(MouseTrackListener)
• NatTable/Canvas#addMouseWheelListener(MouseWheelListener)

Mouse move and mouse track events are not supported in RAP because of performance reasons. The support for mouse move in NatTable, for example to support column and row resizing or reordering, needs to be implemented in a RAP specific NatTable fragment using Javascript.
The hover styling on the other hand will not be supported in NatTable with RAP. To support this the mouse move events needs to be transported from the browser client to the server side, which will be a performance and networking issue.
The mouse wheel events are not supported for Canvas, although there should be no performance issue. But probably it is not supported because in RAP Canvas does not support scrollbars, so the mouse wheel support doesn't seem to be necessary.
Therefore the ScalingMouseWheelListener can not be used in NatTable with RAP and the instantiation and registration is suppressed in case of RAP.
Note that the ScalingUiBindingConfiguration doesn't seem to affect NatTable in RAP anyway, because the key bindings and the mouse wheel binding is used to zoom in and out via the browser and the interactions doesn't seem to be tracked in the UiBindingRegistry afterwards.

• The packages org.eclipse.swt.printing and org.eclipse.swt.program are not available in RAP and therefore now defined as optional package dependencies in the MANIFEST.

RAP does not support printing, so all print related classes are not available. All print related actions in NatTable are encapsulated in org.eclipse.nebula.widgets.nattable.print.LayerPrinter.
To avoid the instantiation of a LayerPrinter with RAP, the PrintCommandHandler now only triggers the instantiation and printing if the platform is not RAP.
In places where the printing is customized in downstream projects, such a guard needs to be added there in case the rendering with RAP is planned.
As org.eclipse.swt.program.Program is not available in RAP, it is not supported that a generated Excel export is directly opened after the export finishes.

• org.eclipse.jface.window.ToolTip
• org.eclipse.jface.window.DefaultToolTip

Therefore the NatTable tooltip support via NatTableContentTooltip and subclasses like FormulaTooltipErrorReporter are not supported in NatTable in RAP.
As these classes can not even be instantiated in RAP, downstream projects need to add a guard to avoid that in their own code.

• org.eclipse.jface.viewers.StyledCellLabelProvider
• org.eclipse.jface.viewers.StyledString
• org.eclipse.jface.viewers.StyledString.Styler

These classes are used in the PersistenceDialog to render the default view configuration italic.
To support the PersistenceDialog also in RAP, a new SimpleViewConfigurationNameLabelProvider was added that does not support the italic rendering.
This SimpleViewConfigurationNameLabelProvider will be used in case the platform is RAP.

• org.eclipse.swt.graphics.Pattern
• org.eclipse.swt.graphics.Region

Without the support of these two classes, the NatTable painter BackgroundImagePainter and PercentageBarDecorator are not supported in NatTable in RAP.
They need to be removed or programmatically conditionally replaced by something else if the NatTable configuration should be used in SWT and RAP.

• SWT.MeasureItem

As this event is not available in RAP, it is not possible to configure a fixed sub cell height in a TableCellEditor.

• Cursor constructors

RAP does not support custom Cursor. The necessary constructors in the Cursor class are missing.
As the custom Cursor implementations in NatTable are registered in handlers of the mouse move events, which by default are not supported in RAP (see above), this should not be an issue for NatTable in RAP.

• GC instantiation on an Image

RAP only allows painting on the Canvas widget.
In NatTable there are several places where such GC instances are created to render the NatTable in memory for example and directly disposed to avoid resource leaks.
In places that are not usable in RAP anyway (e.g. drag modes and AutoResizeHelper in memory rendering on print) the codes stays untouched. The NatExporter now has a guard to avoid the in memory rendering for auto resize on export too, as this leads to an exception.
Also the code in GraphicsUtils stays untouched. The methods in charge are only used by the VerticalTextImagePainter. If vertical text rendering is required, switch to the VerticalTextPainter which directly renders the transformed text on NatTable and does not create a temporary image that gets rotated.
In places that are reachable in RAP (e.g. ImageExporter, ) the usage in RAP is not supported and guarded to avoid runtime issues.

As of now the Nebula Extension and the E4 Extension are not usable with RAP. This is mostly due to dependency issues, e.g. there are versioned package imports that can not be satisfied by RAP/RWT or there are Require-Bundle dependencies on org.eclipse.swt which can not be resolved.

There is an issue related to redrawing NatTable in case of visual changes. NatTable is collecting IVisualChangeEvents and triggers a redraw by default only every 20ms.
This is to avoid that too many redraw operations are handled, which for example could happen on sorting or filtering when using GlazedLists.
The reason why this is not working in RAP is, that UI updates from a background thread are not automatically processed. This is described in more detail in RAP Developer's Guide - Server Push.
To fix this a ServerPushSession needs to be created and started for a NatTable instance. As this is RAP specific API, this issue needs to be addressed in a RAP specific NatTable fragment.

NatTable adds a ResizeListener to close an open editor if the parent Composite is resized. This is to keep the editor position and size in synch with the NatTable presentation. Unfortunately RAP is triggering strange resize events for unknown reasons in several places.
This leads to suddenly closed editors. To avoid this, the ResizeListener are not registered if the platform is RAP.

In RAP there is a difference in the event processing compared to SWT. The order in which for example key events are processed differs, for example if a TextCellEditor is opened in a dialog, pressing ENTER in SWT will first trigger a push on the OK button in the dialog, then key event in the Text control.
But in RWT the key event is first processed in the Text control and then in the dialog. Therefore the commit on enter is disabled when the platform is RAP and the editor is opened in a dialog.

The NatCombo needed a modification to be usable as cell editor in NatTable. The #notifyListener() method needs to call the super implementation, which is necessary in RAP in order to manage the lifecycle correctly. This was not necessary in SWT.
With some additional checks this change does not seem to affect the NatCombo in SWT and now works correctly in RAP.

A collection of limitations in RAP/RWT can be found in the RAP Developers Guide