Module 15: Using Events (VBA Programming for Microsoft Office Project Versions 98 Through 2007)
This article is an excerpt from VBA Programming for Microsoft Office Project Versions 98 Through 2007, by Rod Gill, from Soho Corp. (ISBN 0-9759828-7-7, copyright Rod Gill 2006, portions copyright Soho Corp. 2006, all rights reserved). No part of these chapters may be reproduced, stored in a retrieval system, or transmitted in any form or by any means—electronic, electrostatic, mechanical, photocopying, recording, or otherwise—without the prior written permission of the publisher, except in the case of brief quotations embodied in critical articles or reviews.
After completing this module, you will be able to:
Understand what constitutes an Event
Understand why Events are useful
Program your own Events
What Are Events?
Using Project Events
Using Task Events
Hands On Exercise
What Are Events?
Events provide a powerful programming tool in VBA and in other programming languages such as dot net languages like VB, C#, and others. I discuss only project and task Events in this module, but Microsoft Project also provides Events for resources and assignments that the system handles in exactly the same way as task Events.
Events allow code to run automatically when they occur in the application. For example, an Event occurs whenever you open a project, close a project, save a project, or create a new task.
When an action occurs that triggers an Event in Microsoft Project, such as opening a file or deleting a task, you can write code that runs when the Event occurs. Some Events happen after the action and some happen before. For example, the File Open event occurs after the file is open and the File Close event occurs before the file closes. That way the file remains available for your code to perform actions against it after the event occurs and before the file actually closes.
Events that occur before an action can actually prevent the action from occurring. These events always have the word Before somewhere in their name. For example, if a task edit does not meet certain codified rules, then your code can cancel the task edit action.
Using Project Events
Project events are all related to the whole project (or file). Typical events for a file are:
Before File Close
Before File Save
To create code for one of these events, complete the following steps:
In the VBE, press Ctrl+R to display the Project Explorer.
Expand the Microsoft Project Objects folder for your file.
Double-click the ThisProject (your file name) file.
In the upper left corner of the code window, click the Object pick list button and select the Project item.
In the upper right corner of the code window, click the Event pick list button and select the event you wish to use.
Figure 15-1 shows the Object and Procedure pick lists.
Figure 15-1: Object and Procedure pick lists
The following code runs every time the user opens a project and scrolls the timescale to today’s date. This is very useful for projects covering a long time frame.
Private Sub Project_Open(ByVal pj As Project) EditGoTo Date:=Date End Sub
To get all projects to scroll to the current date, copy the above code to the ThisProject object of the ProjectGlobal (Global.mpt) file. Note that your project file must contain at least one task for the Event to trigger when you next open the project.
Using Task Events
Task Events occur when task values change. Unfortunately, they are not as easy to code as project events. To write code for task, resource, and assignment Events, you need code in three different places:
The ThisProject object as a Project Open Event to call the enable events code.
A Module to hold the enable events code that is in turn called from the Project Open event.
A Class Module to hold the code for the Event itself.
Unfortunately these task (and resource and assignment) Events are rather complex to create but provided you follow the steps below they work well.
Events such as task changes may not be triggered in all cases, or they may trigger other events as well. Sometimes changing one task changes other tasks in the plan, ultimately causing task change events to trigger for a number of other tasks. You need to test your code carefully and thoroughly to make sure that events do what you want them to do; no more and no less!
The instructions below take you through the creation of a Before Task Delete event that displays a confirmation dialog before allowing the user to delete the task. In this code, if the Flag1 field is set to Yes for the selected task, then the code does not display the confirmation dialog and the user can delete the task without prompting. To create this Event, complete the following steps:
Go to the VBE (press Alt+F11) and open the ThisProject object.
Create a Project_Open event and add this code:
Private Sub Project_Open(ByVal pj As Project) MsgBox "Hello, you have opened a project with an " & _ "Open Project and a Before Delete event." 'The following code calls a routine in Module DeleteCode 'To enable the Before Task Delete Event EnableEvents End Sub
Insert a new Module and rename it from Module1 to DeleteCode.
In the new Module, enter the following code:
Public Del As New clsDelete Sub EnableEvents() Set Del.ProjApp = MSProject.Application End Sub
In the preceding code sample, Del is a variable and clsDelete refers to the Class Module Name. They can both have other names, but make sure that you make the names the same for the other steps; otherwise the events will not work.
Click Insert .. Class Module.
Press F4 to display the Properties Window and rename the Class to clsDelete
If you start all class names with cls, they all appear together in IntelliSense lists. This is always useful if you cannot remember the exact name and have several Class Modules.
The system calls the EnableEvents procedure from the Project Open Event so that it automatically runs every time the user opens a project file. To add the Delete class code, complete these steps:
In the Class Module, enter the following code:
Public WithEvents ProjApp As MSProject.Application
ProjApp is a variable name. You can use any valid name you wish, but remember it for step 6.
You can either type the procedure name and parameters, or you can select it from the class module window. To select the ProjectBeforeTaskDelete declaration from the Procedure pick list, do the following:
Click the Object pick list button and select ProjApp.
Click the Procedure pick list button and select ProjectBeforeTaskDelete. The list will hold all events available for tasks, resources, and assignments.
Enter code for the whole Delete Class as follows:
Public WithEvents ProjApp As MSProject.Application Private Sub ProjApp_ProjectBeforeTaskDelete( _ ByVal tsk As Task, Cancel As Boolean) 'Only allow the task to be deleted if Flag1 is False 'Or the user says Yes to the MsgBox prompt If tsk.Flag1 = False Then If MsgBox("Are you sure you want to Delete Task" & _ vbCrLf & vbCrLf & tsk.Name, vbYesNo) _ = vbNo Then Cancel = True 'Cancel the Task Delete End If End If End Sub
To test the code, save and close the project and then reopen it.
If your code did not run at all, your macro security may be set too high. Change it to Medium or Low.
In the event declaration ByVal tsk As Task, Cancel As Boolean, tsk is a task variable that you can use to get all task information for the task that triggered the event. Cancel is only available for all Before events. Set Cancel to True to stop the action that triggered the event. In the example above, the system will cancel the Task Delete action.
Some events are duplicated in the Procedure drop down list, but have a 2 at the end of their name. In Project 2002, Microsoft needed to redo events, so they added the 2 versions for backwards compatibility. You will not need to worry about them, so ignore the event names ending with a 2.
Hands On Exercise
Create a task Event.
In a new project file, or one of your own, add an Event that occurs whenever the user creates a new assignment (assigns a resource to a task).
Add a message that the system displays only if the user assigns a resource at 100% Units. The message should suggest making the assignment more realistic, since no one really works a full 100% of each working day!
VBA Programming for Microsoft Office Project Versions 98 Through 2007:Module 19: Working with Timephased Data (VBA Programming for Microsoft Office Project Versions 98 Through 2007)