ChildEntry Event

The ChildEntry event is triggered for a composite field when one of its child fields receives an Entry event.

compositefieldname is optional if you specify the event in a field script for a composite field, or if the composite field is the frame's top form.

The following attributes of the FrameExec class can be used in the ChildEntry event block:

Specifies the composite field specified in the initial on childentry statement

Specifies that this field is set to null during the Entry event, because the Exit for the previous field is done but the Entry event for the TriggerField is not yet complete.

Use the CurFrame system variable to access these attributes. For more information, see FrameExec Class.

Usage: The ChildEntry event is defined for all composite fields, including the subform that is the frame's top form. If you specify this event in the frame script without a composite field name, the ChildEntry event is triggered when a user enters any field in the frame.

• When you provide a ChildEntry event block for a column of a table field, any entry to the specified column in any row of the table triggers execution of the event block. OpenROAD also triggers the ChildEntry event when the user moves from one field to another inside a column.

For example, assume that your form contains a field called help_field and when the user enters some other field on the form, you want help_field to display a message that explains what data is expected in the current field. The following ChildEntry event block displays the appropriate message for the salary column in the emptable table field:

on childentry emptable[*].Salary =
begin
help_field = 'Enter Salary in thousands.';
end

Users see this message in help_field when they enter any cell in the salary column. To turn off the message, you could provide a corresponding ChildExit event block for the column. For more information, see ChildExit Event.

If you want to know which row of the table field is being entered you can use the CurRow attribute (not the ActiveRow attribute because input focus has not yet been set to that field).

• With operations that must be performed each time a user enters any field on a form or subform

To use the event this way, include one generic ChildEntry event block. If you want the event block to apply to each field on a form, place the event block in the frame script, and do not specify a composite field name in its syntax. If you want the event block to apply to all fields in a composite field, place the event block in the frame script, and specify the composite field name.

For example, based on the previous code example, assume that you want to provide the same help information for all fields on the form, not just those in the table field. To do this, use the following ChildEntry event block in your frame script:

/* CurFrame.TriggerField is the field being
** entered. In this example, the
** Display_Help_Message procedure could get
** a simple help message placed in
** help_field by using the field name.
*/
callproc Display_Help_Message(
field_name = CurFrame.TriggerField.Name,
field_to_fill_in = byref(help_field));

This event block applies to all fields on the frame, because it has no specified composite field name. The code calls a procedure, passing to the procedure the name of the field that triggered the event and, by reference, the name of the help field. The procedure uses those parameters to return a message to the help field.

You can specify an Entry event block for a field and a ChildEntry event block for one or more of the enclosing composite fields for the field. OpenROAD then executes the Entry event block as follows:

• It executes the ChildEntry event block for the innermost enclosing composite field.

• It executes any ChildEntry events for any outer enclosing composite fields.

Executing a resume statement within any of the event blocks breaks the sequence, and any remaining unexecuted ChildEntry events are ignored. Because the entry happens after PreviousField has lost the focus and before TriggerField has received it, when you use a resume statement, no field has the input focus (you can use CurFrame.InputFocusField to redirect the input focus).