# How to Create a Custom Widget for RAP?

Like in SWT, you can also create custom widgets to extend the RAP widget set to your needs. Examples range from simple compositions of existing controls to complex widgets such as custom tab folders, or animated graphs and charts.

There are different types of custom widgets which will be described below. But no matter which type of custom widget you implement, you will end up with a RAP widget that has an SWT-like API and inherits some methods from an SWT super class. Therefore you should make yourself familiar with some important rules of SWT before you get started.
We highly recommend to read this article by the creators of SWT. [1]
The RAP Wiki may cover more recent issues regarding custom widgets.

## Different types of custom widgets

These types differ a lot with regard to the features they support, the dependency on a certain platform, and also the effort and knowledge it takes to create them.

### Compound widgets

These are the simplest ones. Compound widgets are compositions of existing SWT/RAP widgets. These widgets have to extend Composite. There is no fundamental difference between SWT and RAP for compound widgets. Everything that is said about compound widgets in [1] also applies to RAP. If you want to make your compound widget visually distinct, use a custom variants to style the composite and its children.

- Writing a compound widget does not require any JavaScript knowledge.
- Cross-browser compatibility is ensured by RAP.
- The widgets are re-usable in desktop applications with SWT.

### Self-drawing widgets

These are also simple in design. Sometimes you might want a widget that completely draws itself. This can be done by extending Canvas. For writing this kind of widgets, you can also follow [1]. Please note that the drawing capabilities of RAP are limited compared to SWT. Especially in Internet Explorer 7 and 8, the performance degrades with the number of drawing operations.

- Writing a canvas widget does not require any JavaScript knowledge.
- Cross-browser compatibility is ensured by RAP.
- The widgets are re-usable in desktop applications with SWT.

Hint: If performance becomes an issue and your custom widgets has layers or areas that need to be redrawn less often than others, you should consider combining this with the compound approach. Either stack multiple canvases on top of each other (use SWT.INHERIT_FORCE on the parent background to make their background transparent), or put them in any layout as you would other widgets. This can reduce the number of operations by calling "redraw" only on the canvases that need to be updated.

### Browser-based widgets

These can still be rather simple. The SWT `Browser` widget lets you place any HTML into your application. See Embedding Web-Components.

- Writing a Browser-based widget requires only minor-to-moderate JavaScript knowledge, unless you write the client component from scratch.
- Cross-browser compatibility is ensured by RAP only for the Browser widget itself, but not for the code that is running inside it.
- The widgets are re-usable in desktop applications with SWT when all resources are either inlined or provided externally. (See the Google Maps Widget for RCP/RAP [3] as an example for the former.)

### Scripting-enhanced widgets

RWT Scripting allows adding client-side behavior to existing RAP widgets. When your custom-widget can graphically be represented by one or more existing SWT/RAP-widgets, but cannot be reasonably well implemented as a compound widget because of the latency of the HTTP-requests involved, RWT Scripting may be the best solution. It can also help in some cases where certain SWT events are not implemented in RAP (MouseEnter/MouseExit), or are limited compared to SWT (Verify). RWT Scripting is not to be confused with developing a Remote-API based custom widget. While it also runs partially on the client, the difference is that RWT Scripting does not require registering any JavaScript resources and does not need to interact with DOM in any way.

- Writing scripting-enhanced widgets requires minor-to-moderate JavaScript knowledge, and no knowledge of any other browser technology.
- Cross-browser compatibility is ensured by RAP as long as EcmaScript-standards are followed and no DOM-elements or RAP-internals are accessed.
- The widgets are currently not innately re-usable in desktop applications with SWT. Please consult the projects wiki for more information on Single-Sourcing. [4]

### Remote-API based Custom Widgets

RAP 2.0 introduced the "Remote-API" which provides a simple way to write custom widgets that function with the same efficiency as RAP/RWT core widgets. Both sides can send messages to the other by using a Remote Object. While the server RemoteObject can be created by the custom widget code, the client RemoteObject is provided by the framework. To process messages, the server side registers an OperationHandler on the RemoteObject instance, while the client registers a TypeHandler once globally. The RAP Wiki provides a FAQ for this kind of custom widget. [2].

- Writing a Remote-API based widget may require moderate-to-advanced knowledge of JavaScript, HTML/DOM, CSS and any other browser-technology you might want to use.
- Cross-browser compatibility has to be ensured by the widget-developer.
- Remote-API based widgets are not re-usable in SWT desktop applications unless an additional SWT-specific version is being developed.

### External Resources

- [1] SWT: Writing Your Own Widget
- [2] RAP Wiki - Custom Widgets FAQ
- [3] RAP Wiki - Add-Ons
- [4] RAP Wiki - ClientScripting