Event handling in Rich UI

Every widget includes a set of properties for specifying which function is invoked in response to a runtime event. The function in this case is also called an event handler.

Events

The next table lists the available events, though widgets of specific types respond to specific events. For example, buttons respond to onClick, but not to onChange. Also note that two user actions involve "gaining the focus" (by tabbing to or selecting the widget) or "losing the focus" (by tabbing to or selecting a different widget).

Table 1. Events
Event	Meaning
onChange	onChange occurs when the user changes a widget and moves the on-screen focus from that widget, even if the user has reversed the change.
onClick	onClick occurs when the user clicks the widget.
onFocusGained	onFocusGained occurs when the widget gains the focus.
onFocusLost	onFocusLost occurs when the widget loses the focus. The equivalent event in JavaScript™ is onBlur.
onKeyDown	onKeyDown occurs when the user presses any key. On many browsers, the event occurs repeatedly for as long as the user is pressing the key. Each occurrence of onKeyDown is followed by an occurrence of onKeyPress.
onKeyPress	onKeyPress occurs when the user presses any key. On many browsers, the event occurs repeatedly for as long as the user is pressing the key. Each occurrence of onKeyPress is preceded by an occurrence of onKeyDown.
onKeyUp	onKeyUp occurs when the user (having pressed a key) releases it.
onMouseDown	onMouseDown occurs when the user presses any mouse button.
onMouseMove	onMouseMove occurs repeatedly when the user moves the mouse while the on-screen cursor is within the boundary of the widget.
onMouseOut	onMouseOut occurs when the user moves the mouse, just as the on-screen cursor moves away from the widget.
onMouseOver	onMouseOver is an event that JavaScript™ could have named onMouseIn. The event occurs when the user moves the mouse, just as the on-screen cursor moves into the widget. You can use this event, for example, to change the cursor symbol for a particular part of the page.
onMouseUp	onMouseUp occurs when the user (having pressed a mouse button) releases it.
onSelect	onSelect occurs when text is selected in a textArea or textField widget.

The following syntax, for example, declares a Button widget, and the function named click is invoked when the user clicks the widget:

myButton Button { text = "Copy Input to Output", onClick ::= click };

The operator ::= appends the function named click to a dynamic array. One implication is that, when you declare the widget, a set of event-related arrays is immediately available to you, with each array named for an event.

If you specify multiple event handlers for a given event, the order in which the event handlers will run is the order of elements in the array. Here is an example of the syntax:

myButton Button { text = "Start", onClick ::= click, onClick ::= function02 };

You can also use the operator ::= in your code, to add event handlers to the dynamic array. Here is an example:

myButton.onClick ::= function03;

In this examples, a user click causes the invocation of the functions click, then function02, then function03.

Event record

Each event handler receives a record that provides details about the event. The event record is of type Event and includes the following fields:

ch INT: The ASCII code for the keystroke, if any, that caused the event.
x INT: The x coordinate (in pixels) relative to the left of a given widget. For example, if the user clicks in the exact middle of a button that is 10 by 10, the value of x is 5.
y INT: The y coordinate (in pixels) relative to the top of a given widget. For example, if the user clicks in the exact middle of a button that is 10 by 10, the value of y is 5.
clientX INT: The x coordinate of the mouse pointer (in pixels) relative to the left of the browser window. For example, if two buttons, each 10 by 10, are side-by-side at the top left of the browser window and the user clicks the exact middle of the second, the value of x is 15.
clientY INT: The y coordinate of the mouse pointer (in pixels) relative to the top of the browser window. For example, if two buttons, each 10 by 10, are side-by-side at the top left of the browser window and the user clicks the exact middle of the second, the value of y is 5.
screenX INT: The x coordinate of the mouse pointer (in pixels) relative to the left of the screen. The value varies in accordance with the display resolution of the workstation.
screenY INT: The y coordinate of the mouse pointer (in pixels) relative to the top of the screen. The value varies in accordance with the display resolution of the workstation.
widget ANY: The widget to which the event is attached.
mousebutton INT: A number that indicates which mouse button was pressed.

The record of type Event also includes the following functions, each of which is without parameters:

preventDefault()

Prevents the browser from fulfilling a default behavior. For example, you might want to avoid the typical result of a user's clicking a hypertext link. In the following outline, the user's click is passed to the browser only if a specified condition is in effect:

hLink HyperLink { text = "www.ibm.com", 
                  href = "http://www.ibm.com", 
                  onClick ::= handleClickLink };

function handleClickLink(e Event in)
   
   // allow access only to personnel with an explicitly specified status
   if (...)
      return;
   end
   e.preventDefault();
end

stopPropagation()

Used by Rich UI event definitions to cause a behavior that is described in Event propagation.

Event propagation

When a widget within a container does not have a set of event handlers of a given type, the event is made available to the container. For example, if a button is within a box (named B) and if the button does not handle an onClick event, the event is made available to B. This behavior is called event propagation, and it extends to containers of containers, to any level in a container hierarchy. For example, if B is itself within a box (A) and if neither the button nor B handles the onClick event, the event is made available to A.

After an event is handled by a widget at any level in a container hierarchy, the event does not propagate to an embedding widget.

Custom event types

Rich UI provides a way for you to define event types that are specific to your organization. For details, see Extending the Rich UI widget set; in particular, the section on the property @VEEvent.