Introduction to the RAP Widget Toolkit

At the core of RAP operates the RAP Widget Toolkit (RWT), which largely implements the same API as the Standard Widget Toolkit (SWT). That is why many projects that build upon SWT (like JFace) can run on RWT with little or no modifications. It can also be used with or without the Eclipse 3.x workbench layer.

NOTE: “RWT“ refers to this toolkit specifically, while “RAP” refers to the project in its entirety, including its ports of JFace, Workbench and Forms, OSGI integration, add-ons, Branding and Interaction Design API, tooling, demos and custom themes.

RWT implements most (40+) SWT Widgets, including their events and layout manager. It also supports SWT-like key and mouse event handling, drag and drop and painting (on Canvas). If you are not already familiar with SWT, we recommend to first learn the SWT basics (almost all valid for RWT) by reading the official documentation and snippets provided by the SWT project homepage. A full reference specific to RWT can be found here.

Differences between the RWT 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. If this is the case, it is likely because it's hard or impossible to implement in RWT. In some cases, SWT classes and methods are implemented as empty stubs to enable single-sourcing, but only where this is a valid according of the SWT documentation of the API. Examples are the Accessibility API and some SWT constants that are marked as HINT.

SWT was developed for desktop applications, but RWT is used to build web applications. For this reason, there are some features that SWT supports that RWT does not, while RWT adds some features that are tailored to the specific requirements of web application development. However, RWT does not add any new API to the classes adopted from SWT. All RWT-specific features are accessible by API in the namespace org.eclipse.rap.rwt. Many are activated using a widget's setData method with a constant from the RWT class as the key. Example:

table.setData( RWT.MARKUP_ENABLED, Boolean.TRUE )

Other additional features may be accessed via client services.

Notable Additional Features

• Client Class and Client Services
  All features specific to the RAP client (which is exchangeable as of RAP 2.0) are handled by the client class and the client services. This includes support for browser history, JavaScript execution and retrieving the clients time zone offset. The Client interface and client services are documented in more detail here.
• HTTP File Upload
  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, but when clicked will open the file picker 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.
• Markup in Widgets
  Several widgets in RWT support a subset of HTML in their text property. Detailed information can be found here.
• Fixed Columns
  It is possible in RWT to exclude some columns from Tree or Table from scrolling. Find out more about it here.
• Theming
  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.
• Multi-User Environment
  RAP operates in a multi-user environment and provides some additional API that helps dealing with the consequences. An detailed introduction can be found here.

Notable Limitations

• Unimplemented Features
  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.
• Painting Limitations
  SWT can paint on any widget or image using a GC, 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. See also Self-Drawing custom widgets.
• 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
  Since the Browser widget is based on the HTML iframe element, there are some restrictions. Detailed information can be found here.
• Limitations in Mouse and Key Events
  See Mouse and Key Event Handling in RAP.
• Limitations in Verify and Modify Events:
  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 project was started specifically to provide an alternative.
• Limitations in Drag and Drop
  In DragSourceEvent, the fields image, offsetX and offsetY have no effect. DropTargetEvents may be omitted while the mouse cursor is still in motion.
• Limitations when using background threads
  See articles Session access from a background thread and Server Push.