Response Method

The Response method returns a response agent of the specified type and specifications to be used as the response parameter in a LoadEventBehavior Method

This is the recommended and supported way to provide the LoadEventBehavior response parameter. The only exception is for "sprite_cursor" behavior, where you should provide the CursorBitmap directly as the response parameter.

Note: The response is not executed at this point, or when used in a LoadEventBehavior call; it is applied only when triggered at runtime by the inputevent with which the LoadEventBehavior associated it.

Response agents provide the necessary elements to apply a particular behavior. Thus, for "sprite_cursor" behavior, the agent is a CursorBitmap, for "event_behavior" call responses, the agent is a prochandle, and so on.

Object = InputEvent.Response(type = varchar(32)
[, responseset = array of Object][, err = varchar(32)], specification)

responsekey = varchar(32)[, timebased = integer]
[, responsefield = FormField | responsefieldname = varchar(256)]

handle = ProcHandle | procedurename = varchar(32)
[, ownercomponentname = varchar(65)][, fieldname = varchar(256)]
[, ownervarname = varchar(256)]

responsesequence = array of Object, intervalsequence = array of Object
[, delay = integer][, stop = varchar(32)]]

(Required) Specifies the type of response to be created. Possible values are:

The response when applied to a field will change the index of that field's BgBitmap to display the sub-image corresponding to the new index

The response when applied to a field will change the sprites displayed on that field's BgBitmap

The response when applied to a field will change certain display properties of that field

The response when applied will trigger any behavior(s) defined for the eventkey the response contains

The most common scenario for this is where a timed response needs to be triggered by some other inputevent action. When triggered, the redirect response causes the timed response to be immediately scheduled.

The response when applied will execute the procedure specified by the response.

• It must have the following first two parameters (you may define additional parameters):

because it will be passed the frame and field targeted by the response.

• It must not—directly or indirectly—call a frame or invoke a WaitFor method, unless it invokes the InputEvent QueueResponse method first (it can send user events to an already open frame). For more information, see QueueResponse Method.

The response when applied will apply the sequence of responses it contains, in the order and at the intervals it specifies

The response when applied will apply immediately all the set of responses it contains

Specifies an array to which the response created by this call will be added.

Use this to create the sets of responses needed when calling the Response method with type='multi' (the responses parameter), and type='timed' (the responsesequence parameter).

Specifies a StringObject that will contain any error text associated with the method call if the call fails and no response is returned

Specifies the delay in milliseconds before the timed response is initiated.

This can be used to achieve a domino effect: multiple timed responses are triggered by the same signal, but with different delays.

Default: 0 milliseconds

(Required for sprite response) Specifies the set of sprite definitions to be applied as the sprite response.

Certain maptypes require a specific number of descriptors—superfluous ones will be ignored. See the maptype parameter for more details.

Specifies the name of the field whose script contains the procedure that will be executed by this call response.

Default: empty string

Specifies a ProcHandle defining the procedure that will be executed by this call response.

Either this or the procedurename must be supplied for call responses.

The handle itself will not be used; a new handle will be generated based on its contents.

Specifies the index of the sub-image of the field's BgBitmap to display when this image response is applied.

Either this or the increment parameter must be set for image responses.

Specifies that the next sub-image of the field's BgBitmap is to be displayed when this image response is applied.

If the last sub-image is currently displayed, the next sub-image will be the first.

You can use this in a timer response to create animated effects. Sprite responses using 'replace' can also be used for this purpose; the two approaches have different strengths.

Either this or the imageindex parameter must be set for image responses.

Specifies the intervals in milliseconds between application of successive responses in a timer response.

The number of intervals in the intervalsequence array does not need to match the number of responses in the responsesequence array; each list restarts if the other is unfinished unless an end-of-list stop was specified—see stop parameter for more details.

Specifies the type of sprite-mapping to use when applying a sprite response. Possible values are:

The response spritemap when applied to a field will replace the entire existing spritemap for that field.

The response spritemap when applied to a field will add all the sprites it defines to the existing spritemap for that field.

The response spritemap when applied to a field will remove the (first) sprite it defines from the existing spritemap for that field.

If the response spritemap defines multiple sprites, all but the first will be ignored.

The response spritemap when applied to a field will find and remove the second sprite it defines from the existing spritemap for that field, and in its place put the first sprite it defines.

Note: This is not the same as a 'remove' followed by an 'add', which puts the new sprite at the end of the map (making it the last one painted).

Specifies the component name of the frame or class whose script contains the procedure that will be executed by this call response.

Default: empty string

Specifies the name of a variable that at runtime will be pointing to the frame or userobject whose procedure is to be executed by this call response.

Use this if your procedure depends on the current settings of attributes or initialize variables in a particular userobject.

Although you can specify a frame using this, invoking a procedure of any frame other than the calling frame is not supported (the "calling frame" is the currently executing frame at the moment the response is invoked).

Default: empty string

Specifies the name of the procedure that will be executed by this call response.

Either this or the handle parameter must be supplied for call responses.

Default: empty string

Specifies the field attributes that will be set by this display response.

The attributes' values are copied from the field supplied in the template parameter.

Attributes listed must belong to the following list: BgColor, BgBitmap, BgPattern, BgDisplayPolicy, FgColor, TypeFace, TypeFaceName, TypeSize, IsPlain, IsBold, IsItalic, IsUnderlined, IsReverse, OutlineColor, OutlineWidth.

If this list is empty, all the attributes will be applied.

Default: empty string

Specifies the field to which the redirected response should be applied.

The responsefield must be within the same frame as the triggering event.

If this and responsefieldname are not specified, the secondary response is applied to the same field that hosted the redirect response.

Specifies the fullname of the field to which the redirected response should be applied.

The responsefield must be within the same frame as the triggering event.

If this and responsefield are not specified, the secondary response is applied to the same field that hosted the redirect response.

Default: empty string

(Required for redirect response) Specifies the eventkey that identifies the secondary response that this redirect response will trigger.

For example, if a time-based defined behavior (one for which the inputevent is IE_TICKPOINT or IE_PULSE) needs to be fired only when a particular button is clicked, use Response to define a redirect response that specifies the timed behavior's eventkey, then use LoadEventBehavior to ensure that redirect response is triggered whenever the button is pressed.

(Required for multi response) Specifies the set of responses to be returned as a single multi response.

This is typically used with the responseset parameter, to add a multiple-response element to a set of timed responses.

(Required for timed response) Specifies the sequence of responses used when a timed response is applied.

Specifies when a timed sequence will stop. Possible values are:

For example, if the intervalsequence contained the values 40,40,40, the sequence would stop after the third response, regardless of how many items there were in the responsesequence array.

For example, if the responsesequence array has 10 items, the sequence would stop after the 10th response, regardless of how many items there were in the intervalsequence array.

The sequence will stop once the last interval or the last response, whichever comes first, has been used.

For example, if the intervalsequence array containes 3 items, and the responsesequence array contains 10 items, the sequence would stop after the third response.

(Required for display response) Specifies the field that contains the attribute settings to be applied by a display response.

For a list of those attributes that can be applied, see the propertylist parameter.

The template field can be any displayable type of FormField, but to apply the complete set of attributes, the field should be a ButtonField.

Specifies whether the response to which processing is being redirected is a timed one.

This method returns the response, or null if the response creation fails.