# Differences between the RAP Widget Toolkit and SWT

RAP generally follows the rule “If it compiles, it works”. That means that all SWT API implemented in RWT is working within the requirements set by SWT. If an SWT feature is not implemented, the corresponding API is also missing. In some cases, SWT classes and methods are implemented as empty stubs in RWT to enable single-sourcing, but only where this is a valid implementation of the API. Examples are the Accessibility API or some SWT constants that are marked as HINT.

RWT also provides some additional features that are not part of SWT. Partly, these are features related to web clients such as the browser history, partly enhancements of SWT widgets such as the HTML markup support in widgets. However, RWT does not add any new API to the classes adopted from SWT. All RWT features are accessible by API in the package `org.eclipse.rwt`. Many of the additional features are activated using the widget's `setData` method with a constant from the `RWT` class as the key, for example `table.setData( RWT.MARKUP_ENABLED, Boolean.TRUE )`.

## Notable Additional Features

- HTTP File Upload: `FileUpload`
  Unlike SWT, RWT can not simply access the user's file system and read data from it. As an alternative, the `FileUpload` widget can be used. The widget looks like a button and will open the filepicker dialog of the user's browser. After a file has been selected, it can programmatically be send to any HTTP server.
  Important: The widget only allows sending the file to a given URL, it does not handle receiving it. If you require a complete solution for uploading and opening the file in your application, consider using the FileDialog implementation based on the FileUpload widget.
- External Browser Windows: `ExternalBrowser`
  This widget allows opening (and closing) a new browser window or tab to display content from a given URL. Note that depending on the browser configuration, this may be prevented by a popup-blocker.
- Markup in Widgets: `Label`, `CLabel`, `List`, `Tree` and `Table`
  Several widgets in RWT support a subset of HTML in their text property. The feature has to be activated using the constant `RWT.MARKUP_ENABLED`. This may require a custom item height, which can be set using `RWT.CUSTOM_ITEM_HEIGHT`. To achieve similar effects in SWT, the application would have to draw on the widget using a `PaintListener`, which is not supported in RWT except on Canvas.
- Fixed Columns: `Tree` and `Table`
  When a table or tree displays many columns, the user often has to scroll horizontally to see specific data. Doing so means losing sight of the first columns, which may contain vital information that should be visible at all times. Using `RWT.FIXED_COLUMNS`, it is possible to exclude any number of leftmost columns from scrolling, so that they always stick on the left border of the tree or table.
- Theming: All Widgets
  In SWT, the default visual representation of an widget is determined by the operating system. In RAP this is done by the theming which can be adjusted by the developer using CSS. Since the RAP theming has more options to change the look of an widget than the SWT API offers, specific widget instances can also be themed with CSS using custom variants.
- Browser History Support: `IBrowserHistory`
  RWT supports navigating within an application using the browser's back and forward buttons. Use `RWT.getBrowserHistory()` to access it. Note that there are known issues when using the browser history and the `Browser` widget in the same application.
- Multi-User Environment: `ISettingsStore`, `IApplicationStore`, `ISessionStore`, `IServiceStore`, `SessionSingletonBase`
  Not directly related to the UI aspects of RWT, but a very important difference to SWT is that RWT operates in a multi-user environment. This topic has its own article.

## Notable Limitations

- Unimplemented Features: Touch Events, Accessibility
  While the API for touch event handling and accessibility configuration is present in RWT, it does not natively support either. This is a valid implementation according to the SWT documentation.
- Unimplemented Widgets: `StyledText`, `Tracker`, `TaskBar`, `Tray`
  These widgets are currently not available in RWT.
- Drawing Limitations: `GC`, `Canvas` and `PaintListener`
  SWT can paint on any widget or image, while RAP currently only allows painting on the `Canvas` widget. In some cases the `drawText`, `drawString` and `drawImage` methods may disregard the drawing order and overlap elements that are drawn later. Some methods are unimplemented, including `copyArea`, `drawPath`, `setClipping`, `setTransform`, `setInterpolation` `setLineDash` and `setXORMode`. Performance and results of a drawing operations can differ depending on the browser.
- Limitations in Dialogs: `Dialog`, `ColorDialog`, `FontDialog`, `MessageBox`
  When using the JEE compatibility mode, opening a dialog does not block program execution. To obtain their return value, a callback must be registered using the RWT-specific class `DialogUtil`.
- Limitations of the Browser widget: `Browser`
  Since the `Browser` widget is based on the HTML iframe element, all security restrictions regarding cross-frame-scripting apply. This means for `execute()`, `evaluate()` and `BrowserFunction` to work, the document loaded in the `Browser` widget has to come from the same domain and port that the RAP application is loaded from. This is automatically given if the `setText` method is used.
  Also, when using the JEE compatibility mode, the `executeScript` and `evaluate` methods will not block program execution. Like with dialogs, a workaround is possible using the class `BrowserUtil`.
- Limitations in Mouse and Key Events: `MouseEvent` and `KeyEvent`
  See Mouse and Key Event Handling in RAP.
- Limitations in Verify and Modify Events: `ModifyEvent`, `VerifyEvent`
  Modify and Verify events are not fired instantaneously, but with a small delay, possibly combining a number of changes into one event. Also, the values of the `VerifyEvent` fields `text`, `start` and `end` currently always report the entire text to have changed. The ClientScripting was created specifically to provide an alternative.
- Limitations in Drag and Drop: `DragSourceEvent`, `DropTargetEvent`
  In `DragSourceEvent`, the fields `image`, `offsetX` and `offsetY` have no effect. `DropTargetEvent`s may be omitted while the mouse cursor is still in motion.
- Limitations of syncExec and asyncExec: `Display`
  When calling `Display#syncExec()` or `Display#asyncExec()` from a background-thread, the UI may not be updated immediately. This is due to the client-server architecture of RAP, in which only the client can send requests to the server. There is a solution for this provided by the class `UICallBack`. Read more about it here. Note that as of RAP 1.5, `timerExec` does not require a UICallBack anymore (it uses UICallBack internally).