External Application

Developers can add functionality through External Applications as well as External Commands. Ribbon tabs and ribbon panels are customized using the External Application. Ribbon panel buttons are bound to an External command.

IExternalApplication

To add an External Application to Revit, you create an object that implements the IExternalApplication interface.

The IExternalApplication interface has two abstract methods, OnStartup() and OnShutdown(), which you override in your external application. Revit calls OnStartup() when it starts, and OnShutdown() when it closes.

This is the OnStartup() and OnShutdown() abstract definition:

Code Region 3-6: OnShutdown() and OnStartup()

public interface IExternalApplication
{
        public Autodesk.Revit.UI.Result OnStartup(UIControlledApplication application);
        public Autodesk.Revit.UI.Result OnShutdown(UIControlledApplication application);
}

The UIControlledApplication parameter provides access to certain Revit events and allows customization of ribbon panels and controls and the addition of ribbon tabs. For example, the public event DialogBoxShowing of UIControlledApplication can be used to capture the event of a dialog being displayed. The following code snippet registers the handling function that is called right before a dialog is shown.

Code Region 3-7: DialogBoxShowing Event

application.DialogBoxShowing += new 
        EventHandler<Autodesk.Revit.Events.DialogBoxShowingEventArgs>(AppDialogShowing);

The following code sample illustrates how to use the UIControlledApplication type to register an event handler and process the event when it occurs.

Code Region 3-8: Using ControlledApplication

public class Application_DialogBoxShowing : IExternalApplication
{
        // Implement the OnStartup method to register events when Revit starts.
        public Result OnStartup(UIControlledApplication application)
        {
                // Register related events
                application.DialogBoxShowing += 
        new EventHandler<Autodesk.Revit.UI.Events.DialogBoxShowingEventArgs>(AppDialogShowing);
                return Result.Succeeded;
        }

        // Implement this method to unregister the subscribed events when Revit exits.
        public Result OnShutdown(UIControlledApplication application)
        {

                // unregister events
                application.DialogBoxShowing -= 
        new EventHandler<Autodesk.Revit.UI.Events.DialogBoxShowingEventArgs>(AppDialogShowing);
                return Result.Succeeded;
        }

        // The DialogBoxShowing event handler, which allow you to 
        // do some work before the dialog shows
        void AppDialogShowing(object sender, DialogBoxShowingEventArgs args)
        {
                // Get the help id of the showing dialog
                int dialogId = args.HelpId;

                // Format the prompt information string
                String promptInfo = "A Revit dialog will be opened.\n";
                promptInfo += "The help id of this dialog is " + dialogId.ToString() + "\n";
                promptInfo += "If you don't want the dialog to open, please press cancel button";

                // Show the prompt message, and allow the user to close the dialog directly.
                TaskDialog taskDialog = new TaskDialog("Revit");
                taskDialog.MainContent = promptInfo;
                TaskDialogCommonButtons buttons = TaskDialogCommonButtons.Ok |
                                         TaskDialogCommonButtons.Cancel;
                taskDialog.CommonButtons = buttons;
                TaskDialogResult result = taskDialog.Show();
                if (TaskDialogResult.Cancel == result)
                {
                        // Do not show the Revit dialog
                        args.OverrideResult(1);
                }
                else
                {
                        // Continue to show the Revit dialog
                        args.OverrideResult(0);
                }
        }
}