Idling Event

Subscribe to the Idling event to be notified when Revit is not in an active tool or transaction.

Namespace: Autodesk.Revit.UI
Assembly: RevitAPIUI (in RevitAPIUI.dll) Version: 2015.0.0.0 (2015.0.0.0)
Since: 2010


public event EventHandler<IdlingEventArgs> Idling
Visual Basic
Public Event Idling As EventHandler(Of IdlingEventArgs)
Visual C++
 event EventHandler<IdlingEventArgs^>^ Idling {
	void add (EventHandler<IdlingEventArgs^>^ value);
	void remove (EventHandler<IdlingEventArgs^>^ value);


This event is raised when it is safe for the API application to access the active document between user interactions. The event is raised only when the Revit UI is in a state where the user could successfully click on an API command button.

Handlers of this event are permitted to make modifications to any document (including the active document), except for documents that are currently in read-only mode.

In order to change a document, you must begin a new transaction for that document. This transaction will appear in the Revit undo stack and may be undone by the Revit user.

This event is invoked between user actions in the Revit UI. If the handler for this event requires a significant amount of processing time, users will perceive a slowdown in the responsiveness of Revit. If the execution for updates can be safely split across multiple calls to this event, the user perception of Revit responsiveness will be improved.

There are two ways to use this event. In the default mode, a single raise of the event will be made each time Revit begins an idle session. Note that when the user is active in the Revit user interface, idle sessions begin whenever the mouse stops moving for a moment or when a command completes. However, if the user is not active in the user interface at all, Revit may not invoke additional idling sessions for quite some time; this means that your application may not be able to take advantage of time when the user leaves the machine completely for a period of time.

In the non-default mode, your application forces Revit to keep the idling session open and to make repeated calls to your event subscriber. In this mode even if the user is totally inactive the Revit session will continue to make Idling calls to your application. However, this can result in performance degradation for the system on which Revit is running because the CPU remains fully engaged in serving Idling events during the Revit application's downtime.

You can indicate the preference for the non-default Idling frequency by calling SetRaiseWithoutDelay each time the Idling event callback is made. Revit will revert to the default Idling frequency if this method is not called every time in your callback.

Event is not cancellable.


Copy C#
// Create a text note and update it once per second while Revit is idle
TextNote textNote = null;
String oldDateTime = null;
public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements)
    UIApplication uiApp = new UIApplication(commandData.Application.Application);
    Document doc = commandData.Application.ActiveUIDocument.Document;
    using (Transaction t = new Transaction(doc, "Text Note Creation"))
       textNote = doc.Create.NewTextNote(doc.ActiveView, XYZ.Zero, XYZ.BasisX, XYZ.BasisY, 0, TextAlignFlags.TEF_ALIGN_LEFT, DateTime.Now.ToString());
    oldDateTime = DateTime.Now.ToString();
    uiApp.Idling += new EventHandler<IdlingEventArgs>(idleUpdate);
    return Result.Succeeded;
public void idleUpdate(object sender, IdlingEventArgs e)
    UIApplication uiApp = sender as UIApplication;
    Document doc = uiApp.ActiveUIDocument.Document;
    if (oldDateTime != DateTime.Now.ToString())
        using (Transaction transaction = new Transaction(doc, "Text Note Update"))
           textNote.Text = DateTime.Now.ToString();
        oldDateTime = DateTime.Now.ToString();
' Create a text note and update it once per second while Revit is idle
Private textNote As TextNote = Nothing
Private oldDateTime As [String] = Nothing
Public Function Execute(commandData As ExternalCommandData, ByRef message As String, elements As ElementSet) As Autodesk.Revit.UI.Result Implements IExternalCommand.Execute
    Dim uiApp As New UIApplication(commandData.Application.Application)
    Dim doc As Document = commandData.Application.ActiveUIDocument.Document
    Using t As New Transaction(doc, "Text Note Creation")
        textNote = doc.Create.NewTextNote(doc.ActiveView, XYZ.Zero, XYZ.BasisX, XYZ.BasisY, 0, TextAlignFlags.TEF_ALIGN_LEFT, _
    End Using
    oldDateTime = DateTime.Now.ToString()
    AddHandler uiApp.Idling, AddressOf idleUpdate
    Return Result.Succeeded
End Function
Public Sub idleUpdate(sender As Object, e As IdlingEventArgs)
    Dim uiApp As UIApplication = TryCast(sender, UIApplication)
    Dim doc As Document = uiApp.ActiveUIDocument.Document
    If oldDateTime <> DateTime.Now.ToString() Then
        Using transaction As New Transaction(doc, "Text Note Update")
            textNote.Text = DateTime.Now.ToString()
        End Using
        oldDateTime = DateTime.Now.ToString()
    End If
End Sub

See Also