SendUserEvent Method

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)])

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.)

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.

Controls the behavior of the input focus in the receiving frame before processing the user event. Valid settings for focusbehavior are:

Descriptions of system constant values and their numeric equivalents are listed in FocusBehavior Settings for ActiveField, ControlButton, and MenuItem.

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.

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.

targetframe.SendUserEvent(eventname =
'originalevent;'..., errorevent =
'replyevent');
response = curframe.WaitFor(eventname = 'replyevent');
if response.MessageErrorcode = 0 then

In the target frame:

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.