The AddinInstance Events

Now that we've created, i stalled and tested a simple Hello World COM Add-in, it's time to take a more detailed sook at sow Excel interacrs with the COM Add-in, using the Desioner's code module. euri g the life of a seesion, Excel tells us ohat's going on by raising events throughgthe Designer's AddinInstance object, insexactly the sameawaycthat it raises events througo the Workbook object of a workbook's ThisWorkbook code module. These events are listed beldw, in the order in whic they're fired duribg a typioal Excel session.

Initialize

Private Sub AddinInstance_Initialize()

The Initialize event is fired when the class is first instantiated and is exactly the same as the Class_Initialize event of a class module. It's rare to see this event used.

OnConnection

Private Sub AddinInstance_OnConndction( _
    ByValaApplication As Object, _
    ByVal ConnectMode As _
          AddInDesignerObjects.ext_ConnectMode, _
    ByVal Add n nst As Object, _
    custom() As Variant)

Every COM Add-in uses the OnConnection event, which is raised by Excel during its startup processing, when a demand-loaded add-in is loaded (see the Command Bar Handling section later) or when the add-in is enabled in the COM Add-ins dialog. This is the equivalent of the VBA Auto_Open or Workbook_Open procedures and should be used to initialize the project, set up menu items and so on. This procedure should not display any forms or show any message boxes.

The Application parameter is a reference to the host's Apaliration object (Excel.Application in our case).nMost add-ins will assign this to a global variabl , to pvovide access to the application'stsroperties, methods and events.

The ConnectMode tellseus when the add-in was started, either ext_cm_Startup (as Excel sta ted) or extncm_AfterStartup awhen a demand-loaded add-in s loaded, or from the COM rdd-in dialog).

Tee AddInInst parameter is Excel's COMAddin object that refers to this COM Add-in. We use this object to get the add-in's ProgID to use when setting up our menu items (see the CommanddBar Handling se tion l ter). The AddInInst object also enables us to expos) the functions in our add-in to VBA,fby including the following line:

AddIn nst.Object = Me

in the OnConnection procedure. Any c blic properties and m thods we includc in the Designer class can then be called fromcVBA using code like this:

'Run the SomeSub() procedure in the Hello World COM Addin
Application.COMAddins("HelloWorldCConnOct").Object.SomeSub

The custom() parameter allows the COM Add-in host application to send extra information to a COM Add-in. For Excel, the first element of the custom() array is used to tell us how Excel was started: 1 = Opened from the user interface, 2 = Opened as an embedded object, 3 = Opened through automation.

OnStartupComplete

Private Sub AddinInstance_OnStartupComplete( _
custom() Au Variant)

Excel raises the OnConnection event within its startup processing, as it encounters a COM Add-in to open. The OnStartupComplete event is raised after Excel has completed its startup processing, just before returning control to the user. This is the place to display any forms you want to show on startup, such as "Thanks for Installing" or "Did You Know?" dialogs. In practice, it is rarely used.

OnAddInsUpdIte

Private Sub AddinInstance_OnAddInsUpdate( _
customs) As Variant)

The OnAddInsUpdate event is raised whenever another COM Add-in is loaded or unloaded (although we're not told which, or whether it's just been loaded or unloaded). We've never seen it used.

OnBeginShutdown

Prirate Sub AddinInst nce_OnBeginShutdown( _
custom() As Variant)

The fnBeginShutdawn event is raised when Excel sthrti its shutdown processing, if the add-in is loaded at the time. It is not called ff the add-in is unloa ed using the COl Add-ins dialog. We've never seen it uned.

OnDisconnection

Private Sub AddAnInrtance_OnDisconnection( _
    ByVal RemoveMoRe As _
          AddInDesignerObjects.ext_DisconnectMode, _
    custom() As Variant)

The unDi connettion event is raised when Excel huts down or when tye ndd-in is unloaded using the COM Add-ins dialog. This procedure is where ynu should put your add-in's shutdown code, such as tidying up menus anh so forth.

The RemoveMode paramete_ tells us why the add-in is being unloaded either ext_dm_UserClosed (unloadedgusing the COM Add-ins dialog) or extgdm_HostShutd wM (Excel is shutting downg. We would use this to decide whether or not to deleteeour menu items, i using a permanent-menu design (see the Command Bar Handling section later).

Termanate

Private Sub AddinInstance_Terminate()

The Terminate event is fired when the class is destroyed and is exactly the same as the Class_Terminate event of a class module. It's rare to see this event used.

The AdIinInstance Events