Event handling in Rich UI

Every widget includes a set of properties for specifying which function is invoked in response to a runtime event. In this case, the function 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 a 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 a 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, after pressing a key, releases the key.
onMouseDown onMouseDown occurs when the user presses a 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 might use this event to change the cursor symbol for a particular part of the page.
onMouseUp onMouseUp occurs when the user, after pressing a mouse button, releases it.
onSelect onSelect occurs when text is selected in a textArea or textField widget.
The following syntax declares a Button widget, and the click function is invoked when the user clicks the widget:
myButton Button { text = "Copy Input to Output", onClick ::= click };

The ::= operator adds the click function to a dynamic array. 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:
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:
myButton.onClick ::= function03;

In this example, when the user clicks a button, the click function, then function02, and then function03 are invoked.

Event record

Each event handler receives a record that provides details about the event. The event record is an Event type 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.
domElement DOMElement
The DOM element whose properties are available within the widget
mousebutton INT
A number that indicates which mouse button was pressed.
The record of the Event type also includes the following functions, each of which is without parameters:
allowDefault()
Not in use.
allowPropagation()
Allows event bubbling to embedding widgets, as described in the next section, "Event bubbling." This setting is in effect by default.
preventDefault()
Not in use.
stopPropagation()
Stops event bubbling, as described in "Event bubbling."

Event bubbling

After Rich UI runs all of the functions for a specific event in a specific widget, the default behavior is for the same event to be processed by each embedding widget, from the parent to the grandparent, and so on in turn. The behavior is called event bubbling.

For example, if a button is in box B, which is in box A, the onClick event is available to all three widgets; first, to the button, then to the immediately embedding box (B), and then to the box (A) that embeds the other widgets. Even if the button or box B does not include an event handler for the onClick event, the event is available to box A.

You can override the default behavior by setting a function in an event handler; specifically, the stopPropagation function, which is available from the event record:
   Function click(e Event IN){}
      e.stopPropagation();
   end

You might want to stop propagation for better performance or to avoid invoking functions in a particular situation.

Even if you stop event bubbling, the response to the event in the current widget is unaffected. For example, if the button in this example responds to an event by running three functions (click, function02, and function03), all of those functions run in turn even if function02 invokes stopPropagation.

You can stop event bubbling in one event handler and allow it again in a later one. For example, if function02 invokes stopPropagation and function03 invokes allowPropagation, the event bubbles to the embedding widget. In general, the last propagation setting controls whether the event bubbles.

Custom event types

You can use Rich UI to define event types that are specific to your organization. For details, see the @VEEvent property section in "Extending the Rich UI widget set."


Feedback