In Revit API 2011, application events have been reorganized and a lot of more added. Many times, it is necessary to listen to some of these events to do some pre or post processing. For example, when a Revit model (term document in API) is being closed, some programs may want to know what has happened to it.
With the existence of the DocumentClosing application event (plus the DocumentClosed event if necessary), this kind of tasks become fairly feasible now.
Firstly, we define a handler for the DocumentClosing application event. It can be anywhere, e.g. in an application class, a command class, any existing class, or in a separate new class; it can be local (member method) or global (static method); its name can be long or short. All depend on your need. In the code example we are talking about here, a new class and some static event handler methods are created, and a naming convention like AppEvent_DelegateName_Handler is applied.
Here is a sample implementation of the DocumentClosing event handler:
public static void AppEvent_DocumentClosing_Handler(Object sender, EventArgs args)
{
DocumentClosingEventArgs specificArgs = args as DocumentClosingEventArgs;
string msg = "Cancellable: " + specificArgs.Cancellable + "\n"
+ "Document Title: " + specificArgs.Document.Title + "\n";
MessageBox.Show(msg, "DocumentClosing Event");
}
It may be worth of mentioning the EventArgs casting a little bit. If we’d like to access some specific information for the event, the generic EventArgs needs to be casted to the specific DocumentClosingEventArgs. Then we can access to some information like whether the document is cancellable or what its title is, and even determine whether to cancel the document closing when necessary.
Of course, the EventArgs parameter type can be replaced directly by the specific type in the handler signature and it seems a common practise, but we choose to keep all event handlers the same signature and do the type casting inside each individual handler when necessary.
Secondly, the handler needs to be hooked up into the system. This is done in the OnStartup implementation of an IExternalApplication interface:
public Result OnStartup(UIControlledApplication uiApp)
{
//……
uiApp.ControlledApplication.DocumentClosing += AppEventHandler.AppEvent_DocumentClosing_Handler;
//……
}
Thirdly, we’d better remove the handler from the application event system when the Revit is shutting down. It is not absolutely necessary as the addin and all its affiliates and even the whole Revit application will be destroyed at that moment, but it does not harm at all and is always a good practise to do so.
public Result OnShutdown(UIControlledApplication uiApp)
{
//……
uiApp.ControlledApplication.DocumentClosing -= AppEventHandler.AppEvent_DocumentClosing_Handler;
//……
}
That is about it.
The code examples regarding handling, registration and un-registration of all application events have been appended below for reference:
Application event handlers:
public class AppEventHandler
{
public static void AppEvent_DocumentChanged_Handler(Object sender, EventArgs args)
{
MessageBox.Show("DocumentChanged");
}
public static void AppEvent_DocumentClosed_Handler(Object sender, EventArgs args)
{
MessageBox.Show("DocumentClosed");
}
public static void AppEvent_DocumentClosing_Handler(Object sender, EventArgs args)
{
MessageBox.Show("DocumentClosing");
}
public static void AppEvent_DocumentCreated_Handler(Object sender, EventArgs args)
{
MessageBox.Show("DocumentCreated");
}
public static void AppEvent_DocumentCreating_Handler(Object sender, EventArgs args)
{
MessageBox.Show("DocumentCreating");
}
public static void AppEvent_DocumentOpened_Handler(Object sender, EventArgs args)
{
MessageBox.Show("DocumentOpened");
}
public static void AppEvent_DocumentOpening_Handler(Object sender, EventArgs args)
{
MessageBox.Show("DocumentOpening");
}
public static void AppEvent_DocumentPrinted_Handler(Object sender, EventArgs args)
{
MessageBox.Show("DocumentPrinted");
}
public static void AppEvent_DocumentPrinting_Handler(Object sender, EventArgs args)
{
MessageBox.Show("DocumentPrinting");
}
public static void AppEvent_DocumentSaved_Handler(Object sender, EventArgs args)
{
MessageBox.Show("DocumentSaved");
}
public static void AppEvent_DocumentSavedAs_Handler(Object sender, EventArgs args)
{
MessageBox.Show("DocumentSavedAs");
}
public static void AppEvent_DocumentSaving_Handler(Object sender, EventArgs args)
{
MessageBox.Show("DocumentSaving");
}
public static void AppEvent_DocumentSavingAs_Handler(Object sender, EventArgs args)
{
MessageBox.Show("DocumentSavingAs");
}
public static void AppEvent_DocumentSynchronizedWithCentral_Handler(Object sender, EventArgs args)
{
MessageBox.Show("DocumentSynchronizedWithCentral");
}
public static void AppEvent_DocumentSynchronizingWithCentral_Handler(Object sender, EventArgs args)
{
MessageBox.Show("DocumentSynchronizingWithCentral");
}
public static void AppEvent_FailuresProcessing_Handler(Object sender, EventArgs args)
{
MessageBox.Show("FailuresProcessing");
}
public static void AppEvent_FileExported_Handler(Object sender, EventArgs args)
{
MessageBox.Show("FileExported");
}
public static void AppEvent_FileExporting_Handler(Object sender, EventArgs args)
{
MessageBox.Show("FileExporting");
}
public static void AppEvent_FileImported_Handler(Object sender, EventArgs args)
{
MessageBox.Show("FileImported");
}
public static void AppEvent_FileImporting_Handler(Object sender, EventArgs args)
{
MessageBox.Show("FileImporting");
}
public static void AppEvent_ViewPrinted_Handler(Object sender, EventArgs args)
{
MessageBox.Show("ViewPrinted");
}
public static void AppEvent_ViewPrinting_Handler(Object sender, EventArgs args)
{
MessageBox.Show("ViewPrinting");
}
}
Application event registration in the OnStartup implementation of an IExternalApplication interface:
public Result OnStartup(UIControlledApplication uiApp)
{
try
{
//……
uiApp.ControlledApplication.DocumentChanged += AppEventHandler.AppEvent_DocumentChanged_Handler;
uiApp.ControlledApplication.DocumentClosed += AppEventHandler.AppEvent_DocumentClosed_Handler;
uiApp.ControlledApplication.DocumentClosing += AppEventHandler.AppEvent_DocumentClosing_Handler;
uiApp.ControlledApplication.DocumentCreated += AppEventHandler.AppEvent_DocumentCreated_Handler;
uiApp.ControlledApplication.DocumentCreating += AppEventHandler.AppEvent_DocumentCreating_Handler;
uiApp.ControlledApplication.DocumentOpened += AppEventHandler.AppEvent_DocumentOpened_Handler;
uiApp.ControlledApplication.DocumentOpening += AppEventHandler.AppEvent_DocumentOpening_Handler;
uiApp.ControlledApplication.DocumentPrinted += AppEventHandler.AppEvent_DocumentPrinted_Handler;
uiApp.ControlledApplication.DocumentPrinting += AppEventHandler.AppEvent_DocumentPrinting_Handler;
uiApp.ControlledApplication.DocumentSaved += AppEventHandler.AppEvent_DocumentSaved_Handler;
uiApp.ControlledApplication.DocumentSavedAs += AppEventHandler.AppEvent_DocumentSavedAs_Handler;
uiApp.ControlledApplication.DocumentSaving += AppEventHandler.AppEvent_DocumentSaving_Handler;
uiApp.ControlledApplication.DocumentSavingAs += AppEventHandler.AppEvent_DocumentSavingAs_Handler;
uiApp.ControlledApplication.DocumentSynchronizedWithCentral += AppEventHandler.AppEvent_DocumentSynchronizedWithCentral_Handler;
uiApp.ControlledApplication.DocumentSynchronizingWithCentral += AppEventHandler.AppEvent_DocumentSynchronizingWithCentral_Handler;
uiApp.ControlledApplication.FailuresProcessing += AppEventHandler.AppEvent_FailuresProcessing_Handler;
uiApp.ControlledApplication.FileExported += AppEventHandler.AppEvent_FileExported_Handler;
uiApp.ControlledApplication.FileExporting += AppEventHandler.AppEvent_FileExporting_Handler;
uiApp.ControlledApplication.FileImported += AppEventHandler.AppEvent_FileImported_Handler;
uiApp.ControlledApplication.FileImporting += AppEventHandler.AppEvent_FileImporting_Handler;
uiApp.ControlledApplication.ViewPrinted += AppEventHandler.AppEvent_ViewPrinted_Handler;
uiApp.ControlledApplication.ViewPrinting += AppEventHandler.AppEvent_ViewPrinting_Handler;
return Result.Succeeded;
}
catch (Exception ex)
{
MessageBox.Show( ex.ToString() );
return Result.Failed;
}
}
Application event un-registration in the OnShutdown implementation of an IExternalApplication interface:
public Result OnShutdown(UIControlledApplication uiApp)
{
try
{
//……
uiApp.ControlledApplication.DocumentChanged -= AppEventHandler.AppEvent_DocumentChanged_Handler;
uiApp.ControlledApplication.DocumentClosed -= AppEventHandler.AppEvent_DocumentClosed_Handler;
uiApp.ControlledApplication.DocumentClosing -= AppEventHandler.AppEvent_DocumentClosing_Handler;
uiApp.ControlledApplication.DocumentCreated -= AppEventHandler.AppEvent_DocumentCreated_Handler;
uiApp.ControlledApplication.DocumentCreating -= AppEventHandler.AppEvent_DocumentCreating_Handler;
uiApp.ControlledApplication.DocumentOpened -= AppEventHandler.AppEvent_DocumentOpened_Handler;
uiApp.ControlledApplication.DocumentOpening -= AppEventHandler.AppEvent_DocumentOpening_Handler;
uiApp.ControlledApplication.DocumentPrinted -= AppEventHandler.AppEvent_DocumentPrinted_Handler;
uiApp.ControlledApplication.DocumentPrinting -= AppEventHandler.AppEvent_DocumentPrinting_Handler;
uiApp.ControlledApplication.DocumentSaved -= AppEventHandler.AppEvent_DocumentSaved_Handler;
uiApp.ControlledApplication.DocumentSavedAs -= AppEventHandler.AppEvent_DocumentSavedAs_Handler;
uiApp.ControlledApplication.DocumentSaving -= AppEventHandler.AppEvent_DocumentSaving_Handler;
uiApp.ControlledApplication.DocumentSavingAs -= AppEventHandler.AppEvent_DocumentSavingAs_Handler;
uiApp.ControlledApplication.DocumentSynchronizedWithCentral -= AppEventHandler.AppEvent_DocumentSynchronizedWithCentral_Handler;
uiApp.ControlledApplication.DocumentSynchronizingWithCentral -= AppEventHandler.AppEvent_DocumentSynchronizingWithCentral_Handler;
uiApp.ControlledApplication.FailuresProcessing -= AppEventHandler.AppEvent_FailuresProcessing_Handler;
uiApp.ControlledApplication.FileExported -= AppEventHandler.AppEvent_FileExported_Handler;
uiApp.ControlledApplication.FileExporting -= AppEventHandler.AppEvent_FileExporting_Handler;
uiApp.ControlledApplication.FileImported -= AppEventHandler.AppEvent_FileImported_Handler;
uiApp.ControlledApplication.FileImporting -= AppEventHandler.AppEvent_FileImporting_Handler;
uiApp.ControlledApplication.ViewPrinted -= AppEventHandler.AppEvent_ViewPrinted_Handler;
uiApp.ControlledApplication.ViewPrinting -= AppEventHandler.AppEvent_ViewPrinting_Handler;
return Result.Succeeded;
}
catch (Exception ex)
{
MessageBox.Show(ex.ToString());
return Result.Failed;
}
}
Another good news is that all these can be done automatically by the RevitAddinWizard.
Links to some related articles:
Manage Revit Application Events of Revit API
Use RevitAddinWizard to Add Revit Application Event Handlers of Revit API
Implement Revit FailuresProcessing Event Hanlders of Revit API
Use RevitAddinWizard to Implement Revit FailuresProcessing Event Hanlders of Revit API
Manage Revit UIApplication Events
Manage Revit Document Events of Revit API - 3 Document Event Handler of RevitAddinWizard
Recent Comments