How to: Handle Environment Events in Macros
Every new macro project includes a module called EnvironmentEvents, which is visible only in the Macros IDE. This is a template item that contains a number of useful pre-defined event procedures that you can implement in your macros, specifically:
You can view these event procedures in the Class Name combo box and their events in the Method Name combo box. Both boxes are located at the top of the code editor.
To insert a pre-defined event procedure into your macro
On the Class View explorer pane, in the Macros IDE, double-click the EnvironmentEvents node to display it as an EnvironmentEvents tab and a drop-down menu on the macro editor pane.
From the EnvironmentEvents drop-down menu, select an events type, such as TaskListEvents. The Declarations combo box is now populated with the available Task List events.
On the Declarations drop-down menu, select an event, such as TaskAdded, to add its event procedure to the module.
The event is inserted into your macro and you can now add code to the event procedure.
In some cases, you might want to add more event procedures to the Class Name combo box, for example, the CommandEvents events.
Adding a New Event Procedure
To add a new event procedure to the Class Name combo box
Enter a declaration for the event after the hidden region of the EnvironmentEvents module labeled "Automatically generated code, do not modify":
<System.ContextStaticAttribute()> Public WithEvents CommandEvents As EnvDTE.CommandEvents ' This procedure handles DTEEvents.OnMacrosRuntimeReset.
Set up the OnMacrosRuntimeReset procedure so that the new event variable initializes each time a macro is re-run:
Public Sub DTEEvents_OnMacrosRuntimeReset() Handles _ DTEEvents.OnMacrosRuntimeReset CommandEvents = DTE.Events.CommandEvents End Sub
Set up the OnStartupComplete procedure to complete the initialization procedure in step 5.
Private Sub DTEEvents_OnStartupComplete() Handles_ DTEEvents.OnStartupComplete CommandEvents = DTE.Events.CommandEvents End Sub
Add code to respond to the event. In this example, after a command executes, this procedure reports on the details of the command that was issued:
Public Sub CommandEvents_AfterExecute(ByVal Guid As String, ByVal ID As Integer, ByVal CustomIn As Object, ByVal CustomOut as Object) Handles CommandEvents.AfterExecute MsgBox(DTE.Commands.Item(Guid, ID).Name) End Sub
When you declare a new event, you must first initialize it in order to use it. For macros, the place to initialize the new event variable is in theevent procedure.
This event occurs whenever a macro's runtime is reset, such as when a macro is loaded or unloaded. When this occurs, there is a loss of global state. That is, the values of global variables are lost and event handlers are unhooked, meaning that code that formerly executed when an event occurs no longer does so.
When a macro's runtime is reset, the OnMacrosRuntimeReset event occurs. This allows you to automatically re-initialize variables and event handlers whenever a macro runtime reset occurs. By initializing event variables and handlers in OnMacrosRuntimeReset, you ensure that their values are reinitialized each time a macro's runtime is reset, and thus, that your new event procedures work correctly.