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 MethodThis 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.
This method has the following syntax:
Object = InputEvent.Response(type = varchar(32)
[, responseset = array of Object][, err = varchar(32)], specification)
where specification is defined as:
imagespec | spritespec | displayspec | redirectspec | callspec | timedspec | multispec
imagespec
imageindex = integer | increment = integer
spritespec
descriptors = array of SpriteDescriptor[, maptype = varchar(32)]
displayspec
template = FormField[, propertylist = StringObject]
redirectspec
responsekey = varchar(32)[, timebased = integer]
[, responsefield = FormField | responsefieldname = varchar(256)]
callspec
handle = ProcHandle | procedurename = varchar(32)
[, ownercomponentname = varchar(65)][, fieldname = varchar(256)]
[, ownervarname = varchar(256)]
timedspec
responsesequence = array of Object, intervalsequence = array of Object
[, delay = integer][, stop = varchar(32)]]
multispec
responses = array of Object
This method has the following parameters:
type
(Required) Specifies the type of response to be created. Possible values are:
'image'
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
'sprite'
The response when applied to a field will change the sprites displayed on that field's BgBitmap
'display'
The response when applied to a field will change certain display properties of that field
'redirect'
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.
'call'
The response when applied will execute the procedure specified by the response.
Procedures used for this purpose must meet certain criteria:
• It must have the following first two parameters (you may define additional parameters):
frame = FrameExec, hostfield = FormField
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.
'timed'
The response when applied will apply the sequence of responses it contains, in the order and at the intervals it specifies
'multi'
The response when applied will apply immediately all the set of responses it contains
responseset
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).
err
Specifies a StringObject that will contain any error text associated with the method call if the call fails and no response is returned
delay
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
descriptors
(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.
Default: null
fieldname
Specifies the name of the field whose script contains the procedure that will be executed by this call response.
Default: empty string
handle
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.
Default: null
imageindex
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.
Default: 0
increment
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.
Default: 0
intervalsequence
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.
Default: 0
maptype
Specifies the type of sprite-mapping to use when applying a sprite response. Possible values are:
'apply'
The response spritemap when applied to a field will replace the entire existing spritemap for that field.
'add'
The response spritemap when applied to a field will add all the sprites it defines to the existing spritemap for that field.
'remove'
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.
'replace'
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).
Default: 'apply'
ownercomponentname
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
ownervarname
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
procedurename
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
propertylist
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
responsefield
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.
Default: null
responsefieldname
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
responsekey
(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.
responses
(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.
responsesequence
(Required for timed response) Specifies the sequence of responses used when a timed response is applied.
stop
Specifies when a timed sequence will stop. Possible values are:
'interval'
The sequence will stop once the last interval has been used.
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.
'response'
The sequence will stop once the last response has been used.
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.
'both'
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.
'none'
The sequence will never stop
Default: 'none'
template
(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.
timebased
Specifies whether the response to which processing is being redirected is a timed one.
Default: FALSE
This method returns the response, or null if the response creation fails.