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 actually sets the Alpha Anywhere system variable, A_CAN_DO to "NO".

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 if

The 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 if

The 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 if

This 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 if

The 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