SendUserEvent Method
The SendUserEvent method sends a user event to a frame.
This method has the following syntax:
GhostExec.SendUserEvent(eventname = varchar(256)
[,parameter1 = datatype1][,parameter2 = datatype2][, ...]
[, messageobject = Object][, messageinteger = integer]
[, messagefloat = float][, messagevarchar = varchar(256)]
[, delay = float][, focusbehavior = integer]
[, errorevent = varchar(256)])
This method has the following parameters:
eventname
(Required) Specifies the user event that you are sending
parametern, messageobject, messageinteger, messagefloat, messagevarchar
Specify parameters that let you send data with the event. The parameters you send must be the ones that are expected in the receiving frame. (In the receiving frame, the values are placed in attributes with corresponding names. You can access these attributes in the user event block code for the specified event. For more information, see the descriptions of these GhostExec system attributes.)
delay
Specifies a delay, in seconds, to wait before sending the event.
A delayed user event does not block any of the other frames currently active. It is not placed on the event queue until after the delay time has elapsed.
Default: 0 (the event is sent immediately)
focusbehavior
Controls the behavior of the input focus in the receiving frame before processing the user event. Valid settings for focusbehavior are:
FT_NOSETVALUE
Specifies no forced processing
FT_SETVALUE
Forces a SetValue event on the current field in the receiving frame
FT_TAKEFOCUS
Forces SetValue and Exit events on the current field
Default: FT_NOSETVALUE
Setting the focusbehavior parameter to FT_SETVALUE or FT_TAKEFOCUS can cause the receiving frame to discard the user event that you sent. This behavior happens when the SetValue event block for the current field in the receiving frame executes a resume statement. The user event is also discarded if a data type conversion error occurs when OpenROAD attempts to execute the SetValue event.
errorevent
Specifies a user event that is returned to the sending frame if the current user event is not delivered
The value of GhostExec is the frame receiving the event. If the frame is blocked because it has called another frame or procedure, it receives the event when it is unblocked.
If the SendUserEvent call completes a WaitFor call, the message parameters are not available in the GhostExec attributes. Instead, you can access them through the Event object returned by the WaitFor call. For more information, see the description of the ProcExec class
WaitFor Method.
If the SendUserEvent call does not complete a WaitFor call, you can use the focusbehavior parameter to control the behavior of the input focus in the receiving frame before processing the user event.
The errorevent parameter specifies a user event that is returned to the sending frame if the current user event is not delivered. The following example demonstrates usage of this parameter.
In the sending frame:
targetframe.SendUserEvent(eventname =
'originalevent;'..., errorevent =
'replyevent');
response = curframe.WaitFor(eventname = 'replyevent');
if response.MessageErrorcode = 0 then
/* The target frame replied as usual. */
else
... /* The target frame never got the user event. */
endif
In the target frame:
on userevent 'originalevent' =
begin
sendingframe.SendUserEvent(eventname = 'replyevent')
.../* process the userevent we received */
end
In the preceding code, if the user event is delivered to the target frame, the user can designate that a response is sent. If the user event is not delivered, OpenROAD designates that a response is sent.
You can specify user-named parameters as arguments to the SendUserEvent method defined for the GhostExec class.You can specify, at the time a user event is triggered, which arguments in the target frame's user event activation block declaration will be set with values from the frame sending the event. You can choose from any of the supported OpenROAD 4GL data types, and may pass as many arguments as you like from the source frame to the event target. This support for user-named parameters supplements the existing support for the predefined attributes MessageFloat, MessageInteger, MessageObject, and MessageVarchar.
The following example shows how you might send a user-named parameter to a target frame by using a SendUserEvent invocation.
The activation block in the user event sending frame:
on click =
begin
emp_loc = 'New Haven';
recframe = OpenFrame EmployeeMaint();
recframe.SendUserEvent( eventname = 'NewEmp',employee_location = emp_loc );
end
The target frame's activation block for event 'NewEmp':
on userevent 'NewEmp' (employee_location = varchar(32))=
begin
Message 'Adding Employee to the ' + employee_location + ' location....';
end
If there is a data type mismatch between the parameter being passed and the variable receiving the parameter in the receiving frame, it is flagged with the appropriate error at runtime when the event recipient's activation block is activated. Data type mismatches between the source and target are not flagged by the 4GL compiler.
For more information about the SendUserEvent method, see the Programming Guide.