Create Something at Revit Startup with C# or VB.NET

We discussed and demonstrated various events of kinds of objects before like Application/ControlledApplication, UIApplication/UIControlledApplication, and Document. In this article, let us have a look at a very useful event, UIApplication.Idling, and see what it can do for us particularly.

Supposing there is such a requirement, creating a text into the document either new or old at Revit startup. What shall we do?

In the OnStartup callback of the IExternalApplication implementation, we can not do much about it since the passed in argument is of type UIControlledApplication which does not carry any information about document objects.

The good thing is that we can register an Idling event of the UIApplication/UIControlledApplication at that point:

uiApp.Idling += UIAppEventHandlers1.UIAppEvent_Idling_Handler;

and implement the Idling event handler like follows:

public static void UIAppEvent_Idling_Handler(Object sender, EventArgs args)
{
    Autodesk.Revit.ApplicationServices.Application app = sender as Autodesk.Revit.ApplicationServices.Application;
    UIApplication uiApp = new UIApplication(app);
    IdlingEventArgs specArgs = args as IdlingEventArgs;
    uiApp.Idling -= UIAppEvent_Idling_Handler;

    Document doc = uiApp.ActiveUIDocument.Document;
    ElementId id = ElementId.InvalidElementId;

    using (Transaction tr = new Transaction(doc, "Hello from RevitAddinWizard.") )
    {
        tr.Start();

        TextNote text = doc.Create.NewTextNote(
            doc.ActiveView,
            new XYZ(0, 0, 0),
            new XYZ(1, 0, 0),
            new XYZ(0, 0, 1),
            2,
            TextAlignFlags.TEF_ALIGN_CENTER,
            "Hello from RevitAddinWizard.");
        text.Width = 20;

        tr.Commit();
        id = text.Id;
    }

    if (id != ElementId.InvalidElementId)
    {
        uiApp.ActiveUIDocument.ShowElements(id);
    }
}

Then it is done! After Revit starts up and a document is opened or created, the text node will be created at the first second into the document when it is not busy.

A few points may be worth of mentioning about the Idling event handler implementation here.

• The sender object is of type Application instead of UIApplication or UIControlledApplication that you may expect.
• The Idling handler is unregistered as early as possible to avoid reentry or endless notifications.
• To unregister the Idling event handler, we have to get the UIApplication object.
• This can be done from creating a UIApplication instance from the Application sender.
• A transaction is enclosed into a using statement to make sure the transaction is always disposed and to save code of exception handling and transaction rolling back or aborting.
• The UIDocument.ShowElements() method is used to finally highlight the newly created TextNote.

Here is the VB.NET code to achieve the same goal:

Public Shared Sub UIAppEvent_Idling_Handler(ByVal sender As Object, ByVal args As EventArgs)
    Dim app As Autodesk.Revit.ApplicationServices.Application = TryCast(sender, Autodesk.Revit.ApplicationServices.Application)
    Dim uiApp As New UIApplication(app)
    Dim specArgs As Autodesk.Revit.UI.Events.IdlingEventArgs = TryCast(args, Autodesk.Revit.UI.Events.IdlingEventArgs)
    RemoveHandler uiApp.Idling, AddressOf UIAppEvent_Idling_Handler

    Dim doc As Document = uiApp.ActiveUIDocument.Document
    Dim id As Autodesk.Revit.DB.ElementId = Autodesk.Revit.DB.ElementId.InvalidElementId

    Using tr As New Autodesk.Revit.DB.Transaction(doc, "Hello from RevitAddinWizard.")
        tr.Start()

        Dim text As Autodesk.Revit.DB.TextNote = doc.Create.NewTextNote( _
                doc.ActiveView, _
                New Autodesk.Revit.DB.XYZ(0, 0, 0), _
                New Autodesk.Revit.DB.XYZ(1, 0, 0), _
                New Autodesk.Revit.DB.XYZ(0, 0, 1), _
                2, _
                TextAlignFlags.TEF_ALIGN_CENTER, _
                "Hello from RevitAddinWizard.")
        text.Width = 20

        tr.Commit()
        id = text.Id
    End Using

    If id <> Autodesk.Revit.DB.ElementId.InvalidElementId Then
        uiApp.ActiveUIDocument.ShowElements(id)
    End If
End Sub

The external application implementation is not appended here as it can be created by the RevitAddin Project Wizard in no time either in C#, VB.NET, or CLI/C++.  So can the UIApplication/UIControlledApplication event handlers and registrations be created by the Item Project, UIApplication Event Handlers, in a moment in either C# or VB.NET.