TriggerEventBehavior Method
The TriggerEventBehavior method triggers one or all of the event-behaviors defined at this location with "event_responses" responsetype.
This enables behaviors defined using LoadEventBehavior, such as animations, field highlighting, and a wide range of procedure-driven responses, to be triggered at an appropriate point in the 4GL processing.
The startindex and stopindex parameters facilitate the implementation of sprite or sub-image-based progress bars. Each notification of current progress-location that is received from the processing being monitored can be passed on to the progress bar as startindex=previouslocation, stopindex=currentlocation, enabling the bar to transition smoothly from point to point.
This method has the following syntax:
integer = InputEvent.TriggerEventBehavior(location = Object, eventkey = varchar(32)
[, startindex = integer][, stopindex = integer])
This method has the following parameters:
location
(Required) Specifies the field, frame, class, fieldtemplate, frametemplate, or application under which this event-behavior is stored.
eventkey
(Required) Specifies the eventkey to be used to look up the stored response.
If the specified key is an empty string, all general responses (behaviors with responsetype "event_responses") at this location are triggered.
startindex
Specifies the index of the first response to execute, where the response is actually a response sequence (array).
If stopindex is unspecified, it is set to the same value as startindex. If startindex is unspecified and stopindex is specified, startindex is set to 1.
If both parameters are unset or set to 0, all responses in the sequence will be executed.
Response sequences occur in two circumstances:
• Multi-response: responses in the array are to be executed simultaneously
• Timed: responses in the array are to be executed at specified intervals.
For more information about these types of response, see the InputEvent
Response Method.
Default: 0
stopindex
Specifies the index of the last response to execute, where the response is actually a response sequence (array).
If stopindex is unspecified, it is set to the same value as startindex. If startindex is unspecified and stopindex is specified, the startindex is set to 1.
If both parameters are unset or 0, all responses in the sequence will be executed.
Response sequences occur in two circumstances:
• Multi-response: responses in the array are to be executed simultaneously
• Timed: responses in the array are to be executed at specified intervals.
For more information about these types of response, see the InputEvent
Response Method.
Default: 0
This method returns ER_OK if the eventbehavior definition was triggered successfully, and a non-zero error value otherwise.
The following example creates a defined behavior involving image-switch in the 'testfield' field, and triggers the behavior by a click on the 'gobtn' button field. Testfield must have a BgBitmap that is multiimage, and an appropriate BgDisplayPolicy and BgPattern such as BDP_CORNERED and FP_BITMAP. The response value (-1) causes the next image in the BgBitmap to be displayed.
Note that the eventkey used in the defined behavior uses IE_USER, so it can never be 'accidentally' triggered by a mouse, keyboard, or timer action. If you have multiple behaviors that you need to trigger individually, you can specify action values of IE_USER+1, UE_USER+2, and so on. Alternatively you can specify response values of RE_USERDEFAULT+1, RE_USERDEFAULT+2, and so on.
initialize()=
declare
triggeredeventkey = varchar(32) not null;
enddeclare
{
/*
** Set up the event behavior to be triggered in the test field
*/
triggeredeventkey = CurInputEvent.EventKey(
action=IE_USER,
modifierkey=KB_NONE,
responsecode=RE_USERDEFAULT);
CurInputEvent.LoadEventBehavior(
location=field(testfield),
responsetype='event_responses',
eventkey=triggeredeventkey,
response=ToString(text='-1'));
}
/*
** Trigger the testfield response only when the gobtn is clicked
*/
on click gobtn =
{
CurInputEvent.TriggerEventBehavior(location=field(testfield),
eventkey=triggeredeventkey);
}