Running Your Code

The "hook" that allows your code to run is an event handler or an event procedure. Outlook recognizes particular external eventslike an instance of a form being opened, or the user clicking on the Send button to send a mail messageand responds by firing an event. If a procedure exists to handle that event, its code is executed automatically. The event procedure can in turn call other procedures or functions, which can also call other procedures and functions, and so on.

Using VBScript, you are able to access only form-level events andcontrol-level events; events at other levels, such as the application or even the Items collection level, cannot be trapped within the scripted environment. You can examine a list of some of the available events in the VBScript editor by selecting Script Event Handler. The editor opens the Insert Event Handler dialog like the one shown in Figure 6-4. If you select one of the events from the list box, the editor automatically creates the code shell for the event procedure. For example, if you were to select the Open item (which is fired just before a form is opened) in Figure 6-4, the editor would automatically generate the following code:

Function Item_Open( )

End Function

Figure 6-4. The Insert Event Handler dialog

Note that Outlook identifies the object whose Open event is being fired as " Item." Each form represents a particular kind of Item objectan email message, for instance, is represented by a MailItem object, while an appointment is represented by an AppointmentItem object. In other words, "Item" generically identifies the current item in much the same way that "Form" in Visual Basic identifies the current form. Each of the Outlook item object types listed in Table 6-1 supports the events for which the VBScript editor automatically generates a code shell.

If any arguments are passed by Outlook to your event handler, they are shown in the code shell created by the editor. For example, if you were to select the AttachmentAdd item, the editor would generate the following code automatically:

Sub Item_AttachmentAdd(ByVal NewAttachment)

End Sub

In this case, a single argument, which is referred to as NewAttachment within the event handler, is passed by value to the event handler; it represents the name of the file to be attached to a mail message.

Note that the editor identified the handler for the Item_Open event as a function, while it identified the handler for the Item_AttachmentAdd event as a subroutine. The difference is significant: a subroutine (defined with the Sub keyword) does not return a value, while a function (defined with the Function keyword) does. In the case of the Open event, the function returns a Boolean value that, if True, indicates that the form should be opened and, if False, cancels the open operation. So if the statement:

Item_Open = False

is executed within the function, the Item_Open event procedure will return a value of False, and Outlook will not open the item.

Table 6-2 lists theevents that you can select from the Insert Event Handler dialog and for which you can write event handlers. In addition, the table notes the types of items to which the event applies, lists any arguments passed to the handler, and, in the case of functions, notes their possible return values.

Table 6-2. Events automatically recognized by the VBScript editor

Event	Description
AttachmentAdd	Fired when an attachment is added to an item. Parameter: NewAttachment, a reference to an Attachment object passed by value that represents the newly attached file.
AttachmentRead	Fired when an attachment is opened. Parameter: ReadAttachment, a reference to an Attachment object passed by value that represents the attachment.
BeforeAttachmentSave	Fired before an attachment is saved. Parameter: SaveAttachment, a reference to an Attachment object passed by value that represents the attachment to save.
BeforeCheckNames	Fired before Outlook begins to check the names in the Recipients collection, which contains all the recipients of an item. Return Value: If False, the default value, Outlook checks recipients' names. If set to True, the names check is cancelled.
Close	Fired before the Inspector (the window that displays an item) associated with the item is closed. Return Value: If True, the default value, the Inspector is closed. If set to False, cancels the close operation and keeps the Inspector open.
CustomAction	Fired when a custom action of an Outlook item executes. Parameters: Action, a reference to an Action object passed by value that defines the custom action; NewItem, a ByVal reference to the object created as a result of the custom action. Return Value: If True ( the default), allows the custom action to complete. If set to False, the custom action is not complete. Optional: False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.
CustomPropertyChange	Fired when the value of a custom property is changed. Parameter: Name, a string passed by value containing the name of the custom property whose value was changed.
Forward	Fired when the user attempts to forward the item to one or more recipients. Parameter: ForwardItem, a reference passed by value to the new item to be forwarded. Return Value: If True (the default), the new item to be forwarded is displayed; if set to False, the operation is cancelled and the item is not displayed.
Open	Fired when an Outlook item is being opened in an Inspector but before the Inspector is displayed. Return Value: If True ( the default), the item is opened; if set to False, the Open operation is cancelled.
PropertyChange	Fired when the value of a standard property is changed. Parameter: Name, a string passed by value containing the name of the standard property whose value was changed.
Read	Fired when an existing item is opened in a view that supports editing. This contrasts with the Open event, which is fired whenever a new or an existing item is opened. The Read event is fired before the Open event. And although the VBScript editor treats Item_Read as a function, setting its return value cannot cancel the read operation.
Reply	Fired when the user attempts to reply to an item. Parameter: Response, a reference passed by value to the new item to be sent in response to the original message. Return Value: If True (the default), the reply is displayed; if set to False, the operation is cancelled and the new item is not displayed.
ReplyAll	Fired when the user selects the Reply All option in response to an item. Parameter: Response, a reference passed by value to the new item to be sent in response to the original message. Return Value: If True (the default), the reply is displayed; if set to False, the operation is cancelled and the new item is not displayed.
Send	Fired when the user attempts to send an item. Return Value: If True (the default), the item is sent; if set to False, the Send operation is cancelled but the Inspector remains open.
Write	Fired when an item is about to be saved. Return Value: If True (the default), the item is saved; if set to False, the save operation is cancelled.

Inaddition to these form-level events, there is a single control event that you can trap in your code that will automatically be executed. This is the Click event, which is fired whenever the user clicks any of the following controls:

CommandButton control

Frame control

Image control

Label control

Page tab of form

Page tab of MultiPage control

In addition, the Click event is also fired whenever the user changes the values of any of the following controls:

CheckBox control

ComboBox control

ListBox control

OptionButton control (when the value changes to True only)

ToggleButton control

The remaining standard controls (TextBox, ScrollBar, SpinButton, TabStrip, and TextBox) do not support the Click event.

If you're accustomed to working with controls either in Visual Basic or in Microsoft Office (or even with intrinsic elements in HTML forms), you'll be very surprised (and probably disappointed) by an Outlook form's support only for the Click event. The diverse events that developers have come to rely on are simply not trapped in Outlook's scripted environment.

VBScript does not automatically create a code shell for these control or page Click events as it does for form events. Instead, you have to create the code shell. Its general form is:

Sub ControlName_Click( )

End Sub

where ControlName is the string assigned to the control's Name property.

Control References in Code

Note that if you want to reference a control incode other than in the shell of its Click event handler, you either have to provide a complete object reference that identifies the control or instantiate an object variable that references the control. For instance, if you wanted to populate a list box named lstFavoriteColors with the names of some colors, you might use the following code fragment:

 ' This is a public variable so we don't have to instantiate
' it over and over
public lstFavoriteColors
' The Open event handler is executed before the form is 
' opened
Function Item_Open( )

set lstFavoriteColors = _
 Item.GetInspector.ModifiedFormPages("P.2").lstFavoriteColors
lstFavoriteColors.AddItem "Red"
lstFavoritecolors.AddItem "Green"
lstFavoritecolors.AddItem "Black" 
lstFavoritecolors.AddItem "Pink"
0
End Function

Strangely, even if you reference the control in its own event handler, you must still retrieve a reference to it. For example, the following click event generates a syntax error if cmdVerify is not a public variable:

Sub cmdVerify_Click( )
 If InStr(1, cmdVerify.Caption, "On") > 0 Then
 cmdVerify.Caption = "Verify: Off"
 Else
 cmdVerify.Caption = "Verify: On"
 End If
End Sub

Instead, code like the following is needed to recognize cmdVerify as a valid object:

Sub cmdVerify_Click( )
 Dim cmdVerify
 Set cmdVerify = _
 Item.GetInspector.ModifiedFormPages("P.4").cmdVerify
 If InStr(1, cmdVerify.Caption, "On") > 0 Then
 cmdVerify.Caption = "Verify: Off"
 Else

 cmdVerify.Caption = "Verify: On"
 End If

End Sub

The MultiPage control is somewhat unusual in that, while the control itself does not support the Click event, its individual pages do. (Individual pages are represented by Page objects that are contained in the Pages collection, which in turn is returned by the MultiPage control's Pages property.) Strangely, clicks on the page proper are detected, while clicks on the page's tab are not. The general format of a page's Click event is:

Sub PageName_Click( )

End Sub

where PageName is the name of the page as defined by its Name property (and not the string that appears on the page's tab, which is defined by its Caption property). This, of course, requires coding a separate event handler for each page of the control.

But taking advantage of the hook that automatically runs the code on your form isn't very useful unless Outlook will automatically load the form itself. This, however, is quite easy. Outlook loads forms on a folder-by-folder basis, with the form to be used defined by the "When posting to this folder, use" dropdown combo box on the General tab of a folder's Properties dialog (see Figure 6-5). The dialog is accessible by right-clicking on a folder and selecting Properties from the popup menu.

Figure 6-5. Defining the form used to display an item

In the case of mail messages, that approach won't work, since Outlook expects that a Post message form will be used to display messages for all mail folders. A user can be given the choice of loading some form other than the default, however. To do this, publish the form to the folder in which you want it to be available. The user can then create a form of that type by selecting Actions New formname from the Outlook menu.