Force Exit - User Event (Magic xpa 4.x)

This property allows you to define the level from which the Magic xpa engine will exit before performing the handler of your defined event.

None: The event is handled immediately. It does not exit to any level before it is handled.

Editing: The event instructs the task to exit the edit mode of the current control before executing a corresponding handler to handle the event. This means that by the time the logic unit of the event will be executed, the newly edited value of the control will be updated in the control's variable. After all the handlers of the events are executed, the task returns back to edit mode.

On handling such an event, the engine:

1. Exits the Edit mode

2. Updates the variable with the edited value

3. Recomputes all the values related to the updated variable

4. Executes the Variable Change logic unit if the data was modified

5. Executes the Event logic unit

6. The engine returns to the Edit mode

When referring to the control's variable from the executed handler, the engine displays the last edited value as it is updated in the variable.

This level of the Force exit parameter is useful for handling events that need to refer to newly typed values of the current control. For example, if you want to handle the Zoom event of a given control and in the task called from the Zoom logic unit you want to refer to the newly entered value, you should create a User event set to be triggered by the Zoom internal event, and set the Force Exit property to Editing.

This option is required primarily for Edit, Rich Edit, and Multiple Selection List Box controls, and controls that have an editing state that differs from the variable update value.

When the Force Exit is set to None, and the logic unit that handles the event updates the current variable, the new value will be seen only on tabbing out of the control. This is because the control remains in Edit mode with the last edit value. However, when the Force Exit is set to Editing, because the engine exits the Edit mode and re-enters it, the new edit mode shows newly updated values.

See also How Do I Retrieve the New Value of an Edit Control While Handling Its Events?

Control: The event instructs the task to exit the current control before executing a corresponding handler to handle the event. On handling such an event the following sequence will take place:

1. The engine exits the Edit mode

2. Updates the variable with the edited data

3. Recomputes all the values related to the task

4. Executes the Variable Change logic unit

5. Executes the Control Verification and Suffix logic units

6. Executes the Event logic unit

7. Executes the Control Prefix logic unit

8. The engine returns to the Edit mode

Once the event handling is complete, the task returns to the same control. This means that the engine will execute all Control level logic units pertaining to the current controls, namely the Control Verification and Control Suffix, because of exiting the control, and the Control Prefix, because of re-entering the control.

Pre Record Update: The event instructs the task to exit the current record before executing a corresponding handler to handle the event. The User event completes the handling of the event and updates the record in the active transaction. Once this sequence is complete, the task returns to the same record and executes its Record Prefix level. In other words, the handler is executed after the Record Suffix just before it is updated in the database. Once the handling is complete, the record is updated in the database.

On handling such an event the following sequence will take place:

1. The engine exits the Edit mode

2. Updates the variable with the edited data

3. Recomputes all the values based on the variable

4. Executes the Variable Change, Control Verification (in Online – only if the variable is changed; in Rich Client – always), and Control Suffix logic units

5. Executes the Record Suffix if the record has been modified

6. Executes the Event logic unit

7. Updates the record in the table if the record was modified

8. Executes the Record Prefix

9. Executes the Control Prefix

10. The engine returns to the Edit mode

Any reference to the record from the Event level will not reflect the changes in the record, since the record is not yet updated when the Event level is executed.

You can set the event with Force Exit as Pre Record Update if you want the record to be updated in the current transaction immediately after the event handling is completed.

When you set the event to Force Exit = Pre Record Update, any Update operation performed through the executed handler is also updated when the engine exits the record and updates the record in the transaction.

Post Record Update: The event instructs the task to exit and update the current record before executing a corresponding handler to handle the event. This option is similar to the Pre Record Update option. However, in Post Record Update the engine first updates the modified record in the database, re-enters the already updated record, and performs its Record Prefix logic unit. Only then does it execute the logic units of the triggered event.

On handling such an event the following sequence will take place:

1. The engine exits the Edit mode

2. Updates the variable with the edited data

3. Recomputes all the values based on the variable

4. Executes the Variable Change, Control Verification (in Online – only if the variable is changed; in Rich Client – always), and Control Suffix logic units

5. Executes the Record Suffix if the record has been modified

6. Updates the record in the table if the record was modified

7. Executes the Record Prefix

8. Executes the Event logic unit

9. Executes the Control Prefix

10. The engine returns to the Edit mode

Any reference to the record from the Event logic unit will reflect the changes in the record, since the record is already updated when the Event logic unit is executed.

You can set the event with Force Exit = Post Record Update if the event logic unit is set to call other tasks that also refer to the current record and the record must be modified in the database before calling such a task. This way the called task will get the newly updated record.

When you set the event to Force Exit = Post Record Update, any Update operation performed through the executed logic unit on the current record will be done after the record has been updated and will be reflected in the database only after the engine leaves the record once more, either implicitly or explicitly by the end user.

Note: For the Main Program, you are required to provide a public name for the user event because Magic xpa will use the public name of the user event and not of the program when searching for a corresponding handler.

See also How Do I Force Writing the Current Record to the Database?

Related Topics

How Do I Force a Handler to Use the Newly Updated Values that Have Not Yet Been Committed?