JSEvent

Overview

The JSEvent object serves as the primary argument for user-event callbacks, encapsulating key details about application-triggered events. It provides information such as event type, source element or form, position, and any associated data, enabling developers to handle interactions dynamically and efficiently. Constants like ACTION, DATACHANGE, and DOUBLECLICK help identify specific event types, while methods such as getType(), getSource(), and getElementName() give precise context for each event.

In addition to identifying event origins and types, the object supports positional data with methods like getX() and getY(), and tracks the timing of occurrences using getTimestamp(). It also features a data property to carry event-specific payloads, enhancing customization options. This makes JSEvent a flexible and powerful tool for implementing responsive, user-driven functionality in applications.

Constants Summarized

Type	Name	Summary
String	ACTION	Constant returned by JSEvent.
String	DATACHANGE	Constant returned by JSEvent.
String	DOUBLECLICK	Constant returned by JSEvent.
String	FOCUSGAINED	Constant returned by JSEvent.
String	FOCUSLOST	Constant returned by JSEvent.
String	FORM	Constant returned by JSEvent.
Number	MODIFIER_ALT	Constant for the ALT modifier that can be returned by JSEvent.
Number	MODIFIER_CTRL	Constant for the CTRL modifier that can be returned by JSEvent.
Number	MODIFIER_META	Constant for the META modifier that can be returned by JSEvent.
Number	MODIFIER_SHIFT	Constant for the SHIFT modifier that can be returned by JSEvent.
String	NONE	Constant returned by JSEvent.
String	RIGHTCLICK	Constant returned by JSEvent.

Properties Summarized

Type	Name	Summary
Object	data	A data object that specific events can set, a user can set data back to the system for events that supports this.

Methods Summarized

Type	Name	Summary
String	getElementName()	returns the name of the element, can be null if the form was the source of the event.
String	getFormName()	returns the name of the form the element was placed on.
Number	getModifiers()	Returns the modifiers of the event, see JSEvent.
String	getName()	Returns the name of the event which was triggered
Object	getSource()	returns the source component/element of the event.
Date	getTimestamp()	Returns the time the event occurred.
String	getType()	returns the event type see the JSEvents constants what it can return.
Number	getX()	Returns the x position of the event, relative to the component that fired it, if applicable.
Number	getY()	Returns the y position of the event, relative to the component that fired it, if applicable.
void	stopPropagation()	stopPropagation is used in case of multiple event listeners (added via application.

Constants Detailed

ACTION

Constant returned by JSEvent.getType() in a method that is attached to an onAction event.

Type String

Sample

if (event.getType() == JSEvent.ACTION)
{
	// its an action event.
}

DATACHANGE

Constant returned by JSEvent.getType() in a method that is attached to an onDataChange event.

Type String

Sample

if (event.getType() == JSEvent.DATACHANGE)
{
	// its a data change event
}

DOUBLECLICK

Constant returned by JSEvent.getType() in a method that is attached to an onDoubleClick event.

Type String

Sample

if (event.getType() == JSEvent.DOUBLECLICK)
{
	// its a double click event.
}

FOCUSGAINED

Constant returned by JSEvent.getType() in a method that is attached to an onFocusGained or the forms onElementFocusGained event.

Type String

Sample

if (event.getType() == JSEvent.FOCUSGAINED)
{
	// its a focus gained event.
}

FOCUSLOST

Constant returned by JSEvent.getType() in a method that is attached to an onFocusLost or the forms onElementFocusLost event.

Type String

Sample

if (event.getType() == JSEvent.FOCUSLOST)
{
	// its a focus lost event.
}

FORM

Constant returned by JSEvent.getType() in a method that is attached to a form event (like onShow) or command (like onDeleteRecord)

Type String

Sample

if (event.getType() == JSEvent.FORM)
{
	// its a form event or command
}

MODIFIER_ALT

Constant for the ALT modifier that can be returned by JSEvent.getModifiers();

Type Number

Sample

//test if the SHIFT modifier is used.
if (event.getModifiers() & JSEvent.MODIFIER_SHIFT)
{
	//do shift action
}

MODIFIER_CTRL

Constant for the CTRL modifier that can be returned by JSEvent.getModifiers();

Type Number

Sample

//test if the SHIFT modifier is used.
if (event.getModifiers() & JSEvent.MODIFIER_SHIFT)
{
	//do shift action
}

MODIFIER_META

Constant for the META modifier that can be returned by JSEvent.getModifiers();

Type Number

Sample

//test if the SHIFT modifier is used.
if (event.getModifiers() & JSEvent.MODIFIER_SHIFT)
{
	//do shift action
}

MODIFIER_SHIFT

Constant for the SHIFT modifier that can be returned by JSEvent.getModifiers();

Type Number

Sample

//test if the SHIFT modifier is used.
if (event.getModifiers() & JSEvent.MODIFIER_SHIFT)
{
	//do shift action
}

NONE

Constant returned by JSEvent.getType() if the event is not used in a known event or command.

Type String

Sample

if (event.getType() == JSEvent.NONE)
{
	// type is not set.
}

RIGHTCLICK

Constant returned by JSEvent.getType() in a method that is attached to an onRightClick event.

Type String

Sample

if (event.getType() == JSEvent.RIGHTCLICK)
{
	// its a right click event.
}

Properties Detailed

data

A data object that specific events can set, a user can set data back to the system for events that supports this.

Type Object

Sample

// A client design method that handles ondrag
if (event.getType() == JSEvent.ONDRAG)
{
     // the data is the selected elements array
     var elements = event.data;
     // only start a client design drag when there is 1 element
     if (elements.length == 1)
     {
     	return true;
     }
}

// code for a data drag method
event.data = "drag me!";
return DRAGNDROP.COPY;

// code for a data drop method
var data = event.data;
elements[event.getElementName()].setText(data);
return true;

Methods Detailed

getElementName()

returns the name of the element, can be null if the form was the source of the event.

Returns: String a String representing the element name.

Sample

if (event.getElementName() == 'myElement')
{
    elements[event.getElementName()].bgcolor = '#ff0000';
}

getFormName()

returns the name of the form the element was placed on.

Returns: String a String representing the form name.

Sample

forms[event.getFormName()].myFormMethod();

getModifiers()

Returns the modifiers of the event, see JSEvent.MODIFIER_XXXX for the modifiers that can be returned.

Returns: Number an int which holds the modifiers as a bitset.

Sample

//test if the SHIFT modifier is used.
if (event.getModifiers() & JSEvent.MODIFIER_SHIFT)
{
	//do shift action
}

getName()

Returns the name of the event which was triggered

Returns: String name of event as string

Sample

var name = event.getName();

getSource()

returns the source component/element of the event. If it has a name the getElementName() is the name of this component.

Returns: Object an Object representing the source of this event.

Sample

// cast to runtime text field (change to anoter kind of type if you know the type)
/** @type {RuntimeTextField} */
var source = event.getSource();
var sourceDataProvider = source.getDataProviderID();

getTimestamp()

Returns the time the event occurred.

Returns: Date a Date when this event happened.

Sample

event.getTimestamp();

getType()

returns the event type see the JSEvents constants what it can return. Plugins can create events with there own types.

Returns: String a String representing the type of this event.

Sample

if (event.getType() == JSEvent.ACTION)
{
	// its an action event.
}

getX()

Returns the x position of the event, relative to the component that fired it, if applicable. For example drag'n'drop events will set the x,y positions.

Returns: Number an int representing the X position.

Sample

var x = event.getX();
var xPrevious = previousEvent.getX();
var movedXPixels = x -xPrevious;

getY()

Returns the y position of the event, relative to the component that fired it, if applicable. For example drag'n'drop events will set the x,y positions.

Returns: Number an int representing the Y position.

Sample

var y = event.getY();
var yPrevious = previousEvent.getY();
var movedYPixels = y -yPrevious;

stopPropagation()

stopPropagation is used in case of multiple event listeners (added via application.addEventListener). When application.fireEventListeners is called you can use this api to stop executing further listeners.

Returns: void

Sample

event.stopPropagation()

---