Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "RAP/Incubator/ClientScripting"

< RAP
(Data Types)
(JavaScript API)
Line 86: Line 86:
 
For simple data types/values the mapping is as follows:
 
For simple data types/values the mapping is as follows:
  
{| align="left" cellspacing="0" cellpadding="3" border="1" style="margin: auto auto 1em auto;"
+
{| cellspacing="0" cellpadding="3" border="1" style="margin: auto auto 1em 1em;"
 
! SWT
 
! SWT
 
! ClientScripting
 
! ClientScripting

Revision as of 06:03, 2 February 2012

Overview

Conventional RAP applications are running almost entirely on a Server, with a thin client only rendering a user interface with some limited interactivity. This has several advantages, but it also means all application-relevant events have to be forwarded to the Server before being processed, causing small delays and traffic. Scenarios where interactions occur with a high frequency, like typing or mouse movements, would therefore be undesirable.

This is where RAP ClientScripting can help. ClientScripting allows developer to handle some of the events directly on the client, without creating any http-requests. This is ideal to customize or enhance the behavior of specific widgets, making it much less often necessary to develop RAP custom-widgets.

The scripts themselves are written in JavaScript on a SWT-like API. This allows application developer SWT-experience to get started right away, and makes porting between SWT/Java and RAP-ClientScripting fairly easy. Even without any JavaScript-experience, this document should provide you with all the basics.

The ClientScripting feature is currently in early development, aiming to enable only some specific usecases at first. However, all API published here should be stable and is unlikely (but currently not guarenteed) to change in the future. The project is currently hosted on GitHub.

Java API

JavaScript API

The Event Object

This object is given as the first argument when calling a client event listener function. Its API is designed after org.eclipse.swt.widgets.Event.

Field Summary
number type
the type of event, as defined by the event type constants in object SWT
Widget widget
an object representing the widget that issued the event.
boolean doit
depending on the event, a flag indicating whether the operation should be allowed. Setting this field to false will cancel the operation. Currently supported only for key and mouse events on Text and Text-like widgets.
string doit
depending on the event, the character represented by the key that was typed. This is the final character that results after all modifiers have been applied. For non-printable keys (like arrow-keys) this field is not set. Changing its value has no effect.
number keycode
depending on the event, the key code of the key that was typed, as defined by the key code constants in object SWT. When the character field of the event is ambiguous, this field contains the unaffected value of the original character. For example, typing Shift+M or M result in different characters ( 'M' and 'm' ), but the same keyCode (109, character code for 'm').
number stateMask
depending on the event, the state of the keyboard modifier keys and mouse masks at the time the event was generated.
number button
the button that was pressed or released; 1 for the first button, 2 for the second button, and 3 for the third button, etc.
number x
x coordinate of the pointer at the time of the event
number y
y coordinate of the pointer at the time of the event

The SWT Object

The SWT object contains a number of public contants. It is available as a local variable within the scope of any ClientScripting function. Its API designed after org.eclipse.swt.SWT, but the values for the constants may be different. To get an overview of all available constants and their purpose, view the file "js/org/eclipse/rap/clientscripting/SWT.js" from the ClientScripting bundle.

The Widget Object

The Widget object in RAP ClientScripting is a abstract representation of an SWT widget. It has a subset of the API of the actual SWT Widget it represents. In same cases API may slightly differ.

Setter

All widgets have setter functions for all properties defined in the RAP-Protocol. For now a list of all the properties is available in the readme.txt in the ClientScripting bundle. Please be aware that as of now, changing a widgets property with these setter will in most cases only affect it's client side representation. Only properties that can also be changed by a users interaction with the UI (like selection) will also be updated on the java widget instance. This will be improved in later versions to fully synchronize all properties.

Getter

Currently only some getter are available. A list of all properties that have getter is available in the readme.txt in the ClientScripting bundle.

setData and getData

The Widget object a setData and a getData function. Similar to SWT, these allow to attach data to a widget instance without affecting the widget itself. Unlike SWT any value can be stored with setData, not just objects. Note that the date storage on the client is not synchronized with the data storage on the actual SWT Widget.

Function Summary
undefined setData( string key, value value )
stores the given value. The key is mandatory.
value getData( string key )
gets a stored value. The key is mandatory.

Data Types

The type and format of the values that can be set/get on the widget objects is a javascript-specific approximation of its SWT counterpart. They are identical to those used in the RAP Protocol.

For simple data types/values the mapping is as follows:

SWT ClientScripting
void undefined
null null
boolean boolean
int number, but treated like int
float number
String string
char string with length of 1

For complex types see http://wiki.eclipse.org/RAP/Protocol#Common_Data_Types.

Restrictions and Bans

Hints and Best Practices

Back to the top