LoadEventBehavior Method
The LoadEventBehavior method stores a "response" agent plus an eventkey at the specified location. When an inputevent subsequently triggers that eventkey, the response defined by the agent is executed.
Triggering inputevents can be anything that an eventkey can define: mouse actions, timer alerts, key actions, user-defined actions. For more information about these, see the InputEvent
EventKey Method and
TriggerEventBehavior Method.
Responses can involve changes to field display properties, background images, sprite patterns and behaviors, or mouse cursors; they can be procedure calls, pulse effects, or animations; they can be recursive, nested, or self-defining. The response agent is an object defining the necessary properties and methods to apply that response (different responses require different types of agents). For more information about responses, see the InputEvent
Response Method.
Event behaviors can be loaded at runtime (they disappear when the component is closed), or at design time (they are permanently stored and available in the application).
Typically, no 4GL code is involved: a frame displaying a variety of event behaviors loaded at design time using LoadEventBehavior—mouse-over highlighting and dropdowns, button pulsing, progress bar effects, and so on—can do so even with no 4GL code present in the frame at all, as all these responses (except procedure calls), are handled at system class level.
The behaviors are not queued but executed immediately; although a procedure-call response can post a userevent if queueing is required, or issue a QueueResponse call if it needs to issue frame calls. For more information, see the InputEvent
QueueResponse Method.
Responses are necessarily specific to a field, frame, class, template, or application. When specifying location, consider whether the behavior should be loaded to a session-only location (a runtime field, for example), or to a location where the behavior will be saved and available without loading in the future (a framesource, frametemplate, or framesource field, for example).
Responsetype
Even within the same location it is necessary to distinguish and separate certain response types or contexts. The responsetype parameter defines the context in which a behavior will be applied. OpenROAD uses this to distinguish “sprite” responses from other event responses, and separates out certain subtypes of response within these groupings.
When defining the responsetype for a response you have defined, two responsetypes provide categories for general use:
'event_responses'
Stores any type of event-triggered response. You should expect to use this in all normal situations.
'sprite_responses'
Stores any type of sprite-triggered response that you have defined.
However, if invoking one of OpenROAD's specific intrinsic responses, you should make use of OpenROAD’s categorizations. These are:
'sprite_cursors'
Stores sprite-triggered cursor overrides
'sprite_functions'
Stores sprite-triggered prochandles
'sprite_dropdowns'
Stores sprite-triggered menu or choice dropdown fields
'sprite_droplists'
Stores choicelists for the choice dropdowns
Note: You can choose to specify your own responsetypes to create a custom categorization for a set of stored responses. If doing so, treat the following unprefixed values as reserved: "cursors", "functions", "dropdowns", "droplists", "intervals", "responses".
This method has the following syntax:
integer = InputEvent.LoadEventBehavior(location = Object, eventkey = varchar(32),
responsetype = varchar(32), response = Object [, makepermanent = integer]
[, intervals = array of IntegerObject])
This method has the following parameters:
location
(Required) Specifies the field, frame, class, fieldtemplate, frametemplate, or application to store the response.
Mouse inputevents can only be triggered on fields that are "inputevent-enabled." Fields that have a BgBitmap and an "active" BgDisplayPolicy (BDP_BORDEREDSCALED, BDP_BORDEREDTILED, or BDP_CORNERED) are automatically enabled. Alternatively, you can activate any field using the InputEvent ActivateField method; this can be useful for responses that do not involve BgBitmaps.
You should specify as location either the field to which the response is to be applied, or the frame's topform; the event processing will look for a defined response first in the triggered field, then the frame's topform.
eventkey
(Required) Specifies the eventkey to be used to look up the stored response.
responsetype
(Required) Specifies the category of response under which to store this event-behavior definition.
Existing categories are defined above, or you can define your own.
response
(Required) Specifies the response agent to use when executing the response.
The simplest way to specify response agents suitable for this parameter is to use the LoadEventBehavior Response method. Although it is possible to define such responses directly and explicitly, we do not recommend or support this.
An exception is "sprite_cursors": in this case, simply supply the CursorBitmap directly as the response parameter.
For more information about responses and their definition, see the
Response Method.
makepermanent
Specifies whether the defined behavior is saved with the component in which it was loaded. This enables defined behaviors to be tested without saving, then saved after being tested. Valid values are:
TRUE
The behavior is saved.
FALSE
The behavior is not saved.
Default: FALSE
intervals
Specifies the intervals between successive responses in a time-based response. Each interval value is in milliseconds.
Note: This parameter is included only for backwards compatibility. Instead, use the
Response Method to define time-based responses as a single object, to use as the LoadEventBehavior response parameter.
This method returns ER_OK if the eventbehavior definition was loaded successfully, and ER_FAIL otherwise.