Registering Events

Where and how to register events.

Using events is a two step process. First, you must have a function that will handle the event notification. This function must take two parameters, the first is an Object that denotes the "sender" of the event notification, the second is an event-specific object that contains event arguments specific to that event. For example, to register the DocumentSavingAs event, your event handler must take a second parameter that is a DocumentSavingAsEventArgs object.

The second part of using an event is registering the event with Revit. This can be done as early as in the OnStartup() function through the ControlledApplication parameter, or at any time after Revit starts up. Although events can be registered for External Commands as well as External Applications, it is not recommended unless the External Command registers and unregisters the event in the same external command. Also note that registering to and unregistering from events must happen while executing on the main thread. An exception will be thrown if an external application attempts to register to (or unregister from) events from outside of a valid API context.

The following example registers the DocumentOpened event, and when that event is triggered, this application will set the address of the project.

Code Region 24-1: Registering ControlledApplication.DocumentOpened

public class Application_DocumentOpened : IExternalApplication
{
    /// <ExampleMethod>
    /// <summary>
    /// Implement this method to subscribe to event.
    /// </summary>
    public Result OnStartup(UIControlledApplication application)
    {
        try
        {
            // Register event. 
            application.ControlledApplication.DocumentOpened += new EventHandler
                <Autodesk.Revit.DB.Events.DocumentOpenedEventArgs>(application_DocumentOpened);
        }
        catch (Exception)
        {
            return Result.Failed;
        }

        return Result.Succeeded;
    }

    public Result OnShutdown(UIControlledApplication application)
    {
        // remove the event.
        application.ControlledApplication.DocumentOpened -= application_DocumentOpened;
        return Result.Succeeded;
    }

    public void application_DocumentOpened(object sender, DocumentOpenedEventArgs args)
    {
        // get document from event args.
        Document doc = args.Document;

        // Following code snippet demonstrates support of DocumentOpened event to modify the model.
        // Because DocumentOpened supports model changes, it allows user to update document data.
        // Here, this sample assigns a specified value to ProjectInformation.Address property. 
        // User can change other properties of document or create(delete) something as he likes.
        //
        // Please note that ProjectInformation property is empty for family document.
        // So please don't run this sample on family document.
        using (Transaction transaction = new Transaction(doc, "Edit Address"))
        {
            if (transaction.Start() == TransactionStatus.Started)
            {
                doc.ProjectInformation.Address =
                    "United States - Massachusetts - Waltham - 1560 Trapelo Road";
                transaction.Commit();
            }
        }
    }
}