Canceling Events

Events that are triggered before an action has taken place (i.e. DocumentSaving) are often cancellable. (Use the Cancellable property to determine if the event can be cancelled.) For example, you may want to check some criteria are met in a model before it is saved. By registering for the DocumentSaving or DocumentSavingAs event, for example, you can check for certain criteria in the document and cancel the Save or Save As action. Once cancelled, an event cannot be un-cancelled.

Note: If a pre-event is cancelled, other event handlers that have subscribed to the event will not be notified. However, handlers that have subscribed to a post-event related to the pre-event will be notified.

The following event handler for the DocumentSavingAs event checks if the ProjectInformation Status parameter is empty, and if it is, cancels the SaveAs event. Note that if your application cancels an event, it should offer an explanation to the user.

Code Region 24-2: Canceling an Event

private void CheckProjectStatusInitial(Object sender, DocumentSavingAsEventArgs args)
{
        Document doc = args.Document;
        ProjectInfo proInfo = doc.ProjectInformation;
        
        // Project information is only available for project document.
        if (null != proInfo)
        {
                if (string.IsNullOrEmpty(proInfo.Status))
                {
        
                        // cancel the save as process.
                        args.Cancel = true;
                        MessageBox.Show("Status project parameter is not set.  Save is aborted.");
                }
        }
}

Note: Although most event arguments have the Cancel and Cancellable properties, the DocumentChanged and FailuresProcessing events have corresponding Cancel() and IsCancellable() methods.