FormDescription Object

[Previous] [Next]

Microsoft Outlook supports 11 built-in events that get called when users of your Outlook applications try to use some of the built-in capabilities of Outlook. You can write code to handle these events as well as disable these events. The following section describes how to add event-handling code to your application, what the sequence of the events are and details about each event.

Writing Event Handlers

The Outlook Script Editor makes it easy to add event handlers to your VBScript code. In the Script Editor, select Event Handler from the Script menu. Select the event you wish to write a handler for and click Add. Outlook will add a skeleton Function for you with the correct information about the event. You can enter your specific code to handle the event. In Outlook, the event names are preceded with the word Item. For example, the open event is called Item_Open. As you saw earlier, Outlook provides an implicit Item keyword that refers to the current form. This is what the Item in the event handler name is referring to.

Disabling Events

You can prevent events and their default behavior from occurring by setting the function value, the name of the event, to False. You can then place your own code inside of the event handler that replaces the standard behavior. For example, if you write a custom contact form that synchronizes the information with a database, you can disable the Write event if the database is not available. This will prevent Outlook from saving the item and also will prevent the two data sources, Outlook and the database, from becoming out of synch. The following code sample shows an example of this.

     Function Item_Write()         'Call the CheckDatabase function         boolIsOnline = CheckDatabase()         if boolIsOnline = False then             'No database             'Do not save the item             Item_Write = False             msgbox "The database is offline"         end if     End Function     Function CheckDatabase         'You would put your database connection code here         CheckDatabase = False     end Function 

Sequence of Events

The built-in Outlook events include Item_Close, Item_CustomAction, Item_CustomPropertyChange, Item_Forward, Item_Open, Item_PropertyChange, Item_Read, Item_Reply, Item_ReplyAll, Item_Send, and Item_Write. Outlook also includes another event that you can place on your custom controls named Click. The Click event is the only VBScript control event supported in Outlook. The following describes the sequence of these events when you perform common Outlook functions.

Creating a New Item Using a Form or In-Cell Editing

When a user attempts create a new item in Outlook, either by opening a form or by typing information into a new item row in a view with in-cell editing enabled, Outlook will fire the Item_Open event.

Sending an Item

When a user attempts to send an item in Outlook, the Item_Send event is first fired followed by the Item_Write event and finally the Item_Close event. If you disable any event in the sequence, the other events will not fire.

Posting an Item

When a user attempts to post an item, the Item_Write event fires, and then the Item_Close event fires. Again, if you disable any event in the sequence, the subsequent events will not fire.

Saving an Item

When a user tries to save an item, the Item_Write event fires.

Opening an Item

When a user opens an item, the Item_Read event fires followed by the Item_Open event.

Closing an Item

When a user attempts to close an item, the Item_Close event fires.

Details About the Events

The following sections describe the 11 built-in Outlook events.

Item_Close Event

The Item_Close event occurs when the Inspector associated with the Outlook item is being closed. While this event is occurring, the form remains open. You can prevent the form from closing by setting the function value of the Item_Close event to False. The following code sample shows how to disable the close event for a MailItem object if the user has not typed any text in the message body:

     Function Item_Close()         if Item.Body = "" then             msgbox "You did not type any text.  Please type some."             Item_Close = False         end if     End Function 

Item_CustomAction Event

The Item_CustomAction event occurs when a user attempts to launch a custom action on the form either by selecting it from the menu bar or clicking a button that executes the action. The event handler for this event receives both the name of the custom action the user is trying to execute as well as the newly created object from the action. The following code, taken from the Account Tracking application, shows you how you can use CustomAction event. Based on the action, a custom procedure is called to handle the action. The event is disabled to prevent a response form from appearing.

     Function Item_CustomAction(ByVal Action, ByVal ResponseItem)         select case Action              case "Create Account Sales Charts"                 cmdCreateSalesChart_Click()                 'Disable the action so a response form does not appear                 Item_CustomAction = False             case "Print Account Summary"                 cmdPrintAccountSummary_Click()                 Item_CustomAction = False         end select     end Function 

Item_CustomPropertyChange

Th Item_CustomPropertyChange event is called when the user changes the value contained in one of the user-defined fields for the form. The field name is passed as a parameter to the event so that your event handler can determine which property was changed. The following code snippet, taken from the Account Tracking application, shows you how you can use this property to dynamically make controls appear on a form when a user fills in another control. This code example also shows you how to dynamically add values to a control based on the changes a user makes to a field in the Outlook form.

     Sub Item_CustomPropertyChange(ByVal FieldName)         if FieldName = "txtAccountRegion" then             if composemode then                 item.userproperties.find("txtAccountDistrict").value = ""                 oDefaultPage.Controls("lblDistrict").visible = True                 set oDistrict = oDefaultPage.Controls("lstDistrict")                 oDistrict.visible = True                 oDistrict.clear                 select case item.userproperties.find( _                 "txtAccountRegion").value                     case "East"                         oDistrict.additem "Florida"                         oDistrict.additem "New Jersey"                         oDistrict.additem "New York"                         oDistrict.additem "Washington DC"                      case "Central"                         oDistrict.additem "Chicago"                         oDistrict.additem "Detriot"                         oDistrict.additem "Minneapolis"                     case "West"                         oDistrict.additem "California"                         oDistrict.additem "Colorado"                         oDistrict.additem "Washington"                     case "International"                         oDistrict.additem "England"                         oDistrict.additem "France"                         oDistrict.additem "Italy"                         oDistrict.additem "Japan"                         oDistrict.additem "Other"                 end select             end if         end if     End Sub 

Item_Forward Event

The Item_Forward event occurs when the user executes the forward action of a form. This event also fires when the user clicks the Forward button in the Outlook user interface. The event handler is passed the newly forwarded item created by the action. The following code sample shows you how you can remove a message flag on a message programmatically before forwarding the message in cases where the flag does not apply to the users to whom you are forwarding the item.

     Function Item_Forward(ByVal ForwardItem)         if ForwardItem.FlagStatus = 2 then         'There is a flag             ForwardItem.FlagStatus = 0         end if     End Function 

Item_Open Event

The Item_Open event occurs when an item is being opened so that it displays in an Inspector. This event fires when a user starts to compose a new form or reads an existing form based on the item. When your event handler is running, the Inspector is initialized but not yet visible to the user. If you set the Item_Open function value to False, the inspector will not appear and the form will not open. The following code snippet, taken from the Account Tracking application in Chapter 7, initializes some variables and checks to see whether a control exists on the form. If it does, the code enables other controls on the form.

     Sub Item_Open         'Get the default page of the application to use it later         Set oDefaultPage = GetInspector.ModifiedFormPages( _             "Account Tracking")         Set oNameSpace = Application.GetNameSpace("MAPI")         'Initialize the web browser control         set oWebBrowser = GetInspector.ModifiedFormPages( _             "Company Website").Controls("oWebBrowser")         'Check to see if the browser was sucessfully created, if so then         'enable the go button for the company website and the          'NetMeeting option         if err.number = 0 then             bWebExists = True             oDefaultPage.Controls("cmdGo").enabled = True             oDefaultPage.Controls("cmdNetMeetingContact").Visible = True             oDefaultPage.Controls("lblNetMeetingContact").Visible = True             oDefaultPage.Controls("cmdNetMeetingContact").Enabled = True             oDefaultPage.Controls("lblNetMeetingContact").Enabled = True         end if     End Sub 

NOTE

---

The event handler for an Outlook event does not have to be a function. Instead, you can use the VBScript Sub keyword to make your event-handling code subroutines. You should only do this if your code will never need to cancel the event.

Item_PropertyChange Event

The Item_PropertyChange event occurs when one of the standard fields in the item is changed. The event handler is passed the field name so that your code can figure which field has been changed in the code. The following code displays a message box whenever a user changes a value of a message flag for an item:

     Sub Item_PropertyChange(ByVal Name)         Select Case Name             Case "FlagStatus"                 msgbox "You changed the flag status"             Case "FlagRequest"                 msgbox "You changed the flag text"             Case "FlagDueBy"                 msgbox "You changed the flag due date"         end Select     End Sub 

Item_Read Event

The Item_Read event occurs when a user opens an existing item for editing. This event also occurs when a user selects an item in a view that support in-cell editing. The Item_Read event is fired before the Item_Open event. By using the Item_Read event, you can detect whether the user is composing a new form or reading an existing form in your application as shown in the code below.

     Sub Item_Read         'Check to see if the application is in compose mode         ComposeMode = False     End Sub 

Item_Reply Event

The Item_Reply event occurs when a user executes the reply action for an item. The reply event can be initiated either through the Reply button on the form or through the Reply menu option. Your event handler receives the newly created reply object as a parameter. The following code uses the reply event to add new text to the body of the created reply item:

     Function Item_Reply(ByVal Response)         txtNewText = "This was added by the Reply event!"         Response.Body = Response.Body & chr(13) & txtNewText     End Function 

Item_ReplyAll Event

The Item_ReplyAll event occurs when the user executes the Reply All action for an item. This reply all event can be initiated either through the Reply All button on the form or through the Reply All menu option. Your event handler receives the newly created Reply All object as a parameter. The following code makes sure that the user wants to reply to all of the recipients on the item before sending the reply:

     Function Item_ReplyAll(ByVal Response)         txtMessage = "Are you sure you want to reply all?"         boolResult = MsgBox(txtMessage, 292)         If boolResult Then             Item_ReplyAll = True         Else             Item_ReplyAll = False         End If     End Function 

Item_Send Event

The Item_Send event occurs when a user attempts to send an item. If you set this event to be False, the item is not sent and the item remains open. The following code sets the message flag, if it does not already exist, to be the subject of the message, and it sets the due date for the message to be seven days from the current date.

     Function Item_Send()         If item.FlagStatus <> 2 then         'No flag set             item.FlagStatus = 2             item.FlagDueBy = Date + 7             item.FlagRequest = item.Subject         end if     End Function 

Item_Write Event

The Item_Write event occurs when the item is explicitly saved, such as when a user selects Save from the File menu, or when an item is implicitly saved, such as when a user tries to close and open item. When you set this event to False, Outlook will not save the item. For a code sample for this event, see the "Disabling Events" section earlier in this supplement.