Canceling Events
Description
All of the events whose names are prefixed with "Can" can be canceled, thus preventing the event from occurring. The CANCEL()command is used to cancel an event.
The CANCEL()command can take an optional flag which can be .T. or .F. If the flag is set to .t. then Alpha Anywhere error messages are suppressed. When you cancel an event, if your Xbasic code provides the appropriate feedback to the end-user as to why the event is being canceled (for example, by including a UI_MSG_BOX() in the code), then you would not want additional error reporting from Alpha Anywhere itself. In this case, you would use CANCEL(.t.) in your code to cancel the event. For example, assume that you have a control on a form and that you define a script for that control's CanDepart event. Assume that the control has focus and that the user tries to give focus to another control on the form. This will cause the control's CanDepart event to fire. If this script executes the CANCEL()command, the event will be canceled and the user will not be able to move focus away from this control. The following example shows how a script could be attached to a table's CanDeleteRecord event. When the user deletes a record, the script is executed. It displays a dialog box asking the user for the password. If he enters the correct password, the record is deleted. Otherwise, the Delete event is canceled and the record is retained. This script prompts the user for a password before deleting a record.
password = "Alpha5"
user = UI_GET_text("Password", "Enter the password", "******", "&&&&&&")
if (user = "") then
end
end if
if (.not.(user == password)) then
cancel()
ui_msg_box("Password", "Password invalid.")
end ifThe following example could be attached to the CanWriteField event for the FAX field of the Vendor table. If the area code prefix of the PHONE field does not match the FAX field's area code, the script prompts you with a warning dialog box. If you choose to heed the warning (by clicking 'Retry'), the CANCEL()command is executed, and the cursor is prevented from leaving the FAX field. If you choose to abort the fax number entry (by clicking 'Abort'), the A_FIELD_VALUE is set back to the original value as stored in the record buffer, and the cursor is allowed to leave the FAX field. Obtain the area code from this field and the PHONE field. It is presumed that phone numbers are stored like (xxx) xxx-xxxx
prefix1 = left(A_FIELD_VALUE,5)
prefix2 = left(Vendor->PHONE, 5)
if (prefix1 <> prefix2) then
'Compute the Message Type code
code = UI_ATTENTION_SYMBOL + UI_ABORT_RETRY_IGNORE
response = ui_msg_box("Warning","The area codes of the Phone and Fax numbers should be the same.", code)
'RETRY selected
if (response = UI_RETRY_SELECTED) then
'prevent field exit
cancel()
'ABORT selected
elseif response = UI_ABORT_SELECTED then
'undo field change
A_FIELD_VALUE = Vendor->FAX
end if
end ifThe list of events below summarizes what happens when an event is canceled with the CANCEL()command.
CanEditField
Prevents this field from getting focus. Alpha Anywhere will automatically advance to the next field.
CanWriteField
Prevents focus from leaving the field.
CanChangeRecord
Prevents the record from being changed. Contrast this with the CanChange form event.
CanDeleteRecord
Prevents the record from being deleted.
CanEnterRecord
Prevents entry of a new record.
CanMarkRecord
Prevents the record from being marked.
CanUnMarkRecord
Prevents the record from being unmarked.
CanSaveRecord
Abandons the edited record, without saving it. Contrast with the CanSave event, which cancels the save, but does not discard the record being edited.
CanArrive
Prevents a control from getting focus.
CanChange
Prevents the user from changing a record. Contrast this with the CanChangeRecord event. Both events allow you to prevent a user from changing a record. However, the CanChangeRecord event cannot prevent the user from typing a new value into a control on the form even though it can prevent Alpha Anywhere from saving the value the user typed. The CanChange event is cleaner because it can actually prevent the user from tying a value into a control on a form.
CanDepart
Prevents focus from leaving a control.
CanExit
Prevents a form from being closed. If you want to prevent a user from exiting from Alpha Anywhere until a certain condition has been met, you can use this event on a hidden form.
CanSave
Prevents a record from being saved. Contrast this with the field rule level, CanSaveRecord event which also prevents a record from being saved, but discards the record being edited.
CanTabChange
Prevents the user from changing focus to a different page on a tab object.
What to Do if Your "Can" Event Scripts Don't Work
Including user interface code, such as UI_MSG_BOX()etc. in the scripts executed by "Can" events can sometimes cause the script to fail (i.e. even though the CANCEL()command is executed, the event still takes place). This is because the user interface code takes focus away from the current object in Alpha Anywhere when it executes. If this happens, you can try to include the CANCEL()command in your script before any user interface code. Here is another way in which you could get unexpected results when you try to cancel an event. Assume that you have a form with a Tab object on the form. You would like to prevent the user from changing focus from the current tab page to another tab page if a certain condition is true. Also, you would like to give focus to a particular field on the tab page if the condition to change pages has not yet been met. The following code is attached to the Tab object's CanTabChange event:
condition = logical text that sets value of condition
If (.not. condition) then
'user does not have permission to change tab pages
cancel()
company.activate()
End ifThis does not work! However, the following does work:
condition = logical text that sets value of condition
If (.not. condition) then
'user does not have permission to change tab pages
company.activate()
cancel()
End ifThe reason that the first script fails is that when company.activate() executes, it resets the value of the system variable A_CAN_DO to "Yes" (because the command succeeded) - thus undoing the effect of the CANCEL()command. When the script ends, the value of A_CAN_DO is "Yes", and so the event is not cancelled.
See Also