Syntax for Outlook property and control values and events

Built-in Properties

Once you know the property name, use this syntax to get the value:

MyValue = objItem.propname

where objItem is an object variable representing an Outlook item. If you're writing code behind an Outlook form, the current item -- the one the code is running for -- is the Item intrinsic object, so you can use:

MyValue = Item.propname

On an Outlook form, to react to changes in the values of built-in properties, use the PropertyChange event with a Select Case block:

Sub Item_PropertyChange(ByVal Name) Select Case Name Case "Subject" ' your code goes here Case "Categories" ' more code goes here ' continue with Case statements for other properties ' whose values you want to monitor End Select End Sub

The PropertyChange event fires only after the user presses Tab or Enter or otherwise moves the focus to another property. On some types of items, changing one property causes several other properties to change as well. To test what built-in properties change in response to particular user actions, try this code on an Outlook form: 

Sub Item_PropertyChange(ByVal Name) MsgBox "The " & Name & " property changed." End Sub

The PropertyChange event does not fire for the Body property, which represents the main block of text on an item (shown in the Field Chooser as either Note or Message, depending on the type of item). To track changes in the Body property, you will probably want to put code in the Item_Open event handler to get the initial value of Body, then compare it later with the user's changes. 

Custom Properties

MyValue = objItem.UserProperties("propname")

where objItem is an object variable representing an Outlook item. 

If you're writing code behind an Outlook form, the current item -- the one the code is running for -- is the Item intrinsic object, so you can use:

MyValue = Item.UserProperties("propname")

On an Outlook form, to react to changes in the values of custom properties, use the CustomPropertyChange event with a Select Case block:

Sub Item_CustomPropertyChange(ByVal Name) Select Case Name Case "MyProp1" strMyProp1 = Item.UserProperties("MyProp1") Select Case strMyProp1 Case "Text1" ' code to react to the MyProp1 ' string property having a value of "Text1" Case "Text2" ' code to react to the MyProp1 ' string property having a value of "Text2" Case Else ' code to handle other values of MyProp1 End Select Case "MyProp2" ' code to handle a change in MyProp2 goes here ' continue with Case statements for other properties ' whose values you want to monitor End Select End Sub

Do not replace "Name" in the argument for the CustomPropertyChange event or the Select Case statement with the name of a particular property. This one event fires for every custom property. Use the Select Case block  to handle the individual properties, starting with a Case statement for each property whose value change you are interested in. Within each Case block, you will probably need to test the value of the property that changed with either an If ... End If block or another Select block.

The inner Select Case statement above example above shows the structure for checking the value of a string property. The syntax would be slightly different, of course, for a date/time or Boolean property.

The CustomPropertyChange event fires only after the user presses Tab or Enter or otherwise moves the focus to another control. If you need to handle a custom property change in all situations, you may need to include that code in your Send, Write, and other event handlers.

Outlook 2002 SP3 has problems with the UserProperties.Find("propname") syntax. Instead, use UserProperties("propname"). See A problem occurs with custom forms that use the UserProperties.Find method and formulas in Outlook 2002 Service Pack 3.

One other oddity: If you can successfully add a property from another type of item to a custom form (and that's a big IF -- very few properties can transfer between items), Outlook automatically creates a corresponding UserProperty. That property does not, however, behave like a normal UserProperty. It doesn't fire a CustomPropertyChange event, and the value of the property may not change when you expect it to. See task Item.UserProperties("Cc") changing after creating a message object for a discussion of such a case.

Unbound Controls

The third type of value that you may need to access, particularly in Outlook form code, is the data that a user has entered into an unbound control on a form. (Unbound means that the text box or other control is not tied to an Outlook property.) Outlook uses a peculiar syntax to get the value of a control, more complicated than a VB or VBA programmer might be accustomed to. You need to know not just the name of the control, but also the name of the page on the Outlook form where it appears. Get the name of the control by right-clicking the control and viewing its Properties dialog. Then use this syntax:

Set objPage = Item.GetInspector.ModifiedFormPages("My Page") Set objControl = objPage.Controls("TextBox1") MyValue = objControl.Value

The only event supported by controls on an Outlook form is the Click event. For example, you can use the Click event to track when a user selects a new value from a drop-down list (combo box):

Sub ComboBox1_Click() Set objPage = _ Item.GetInspector.ModifiedFormPages("My Page") Set objControl = objPage.Controls("ComboBox") MsgBox "The value in the " & objControl.Name & _ "control has changed to " & objControl.Value & "." End Sub

However, not all controls support the Click event. The Click event fires on a drop-down list combo box, but not if the user types a value into a combo box with the style set to DropDownCombo (0). It fires for label (see To create a hyperlink on an Outlook form for an application), frame (when the user clicks empty space inside the frame), list box, check box, option button and command button controls, but not for text box or spin button controls. For list boxes, there must be at least one item in the list, and the user must click on a list item (not in any blank area in the list box), in order for the Click event to fire.

Another common application of the Click event is to use a checkbox or option buttons to change the appearance of another control. For example, you might want to change the items displayed in a list or combo box or display a group of items that were previously hidden. In this example, chkNeedCheck is an unbound checkbox and frmCheckData is a frame on the General page containing bound controls where the user can enter additional information.

Sub chkNeedCheck_Click() Set myinspector = Item.GetInspector Set myPage1 = myInspector.ModifiedFormPages("General") Set frmCheckData = myPage1.Controls("frmCheckData") Set chkNeedCheck = myPage1.Controls("chkNeedCheck") frmCheckData.Visible = chkNeedCheck.Value End Sub

Clicking on the chkNeedCheck checkbox toggles the frmCheckData's Visible property, alternately showing and hiding the frame and all the controls it contains. If you want to disable and enable the control, use the Enabled property instead of Visible.

For a demonstration of the Click event generated by unbound option buttons, download Form Controls Demo.zip (6kb, 30 Aug 04), unzip it, open the .oft file, and publish that form. Then run the published form. Also see How to make a checkbox show and hide a frame.

Besides the Click event, you can use the Item_Write, Item_Close or Item_Send event to process the information in the unbound controls. Note, however, that if the user changes only the data in an unbound control -- and not the data in any bound control -- Item_Write will not fire when the user clicks Save. 

Tips

You can use the PropertyChange and CustomPropertyChange events to help you understand what happens when the user interacts with form controls showing both built-in and custom properties. Just add this code to your form to have a message box pop up every time a property changes. (For example, guess how many properties change when you change the status of a task to Completed.)

Sub Item_PropertyChange(ByVal Name) MsgBox "The " & Name & " property changed." End Sub Sub Item_CustomPropertyChange(ByVal Name) MsgBox "The " & Name & " custom property changed." End Sub

The Click event for an unbound control fires when you set the Value of the control. If you initialize the value of a control in the Item_Open event of a form, then use the control's Click event to set the value of an Outlook property, you may want to use code like this to make sure that the property is set only when the user click's the control, not during form initialization. In this example, cmbCategories is a combo box on a Contact form's General page and UserCat2 is a custom property:

Dim cmbCategories Dim blnDidInit Sub Item_Open() Set myinspector = Item.GetInspector Set myPage1 = myInspector.ModifiedFormPages("General") Set cmbCategories = myPage1.Controls("cmbCategories") cmbCategories.AddItem "Adult Daycare Centres" cmbCategories.AddItem "Aged Care Facilities" cmbCategories.AddItem "Agricultural & Pastoral Societies" If Item.UserProperties("UserCat2") <> "" Then cmbCategories.Value = Item.UserProperties("UserCat2") End If blnDidInit = True End Sub Sub cmbCategories_Click() If blnDidInit Then Item.UserProperties("UserCat2") = cmbCategories.Value End If End Sub

More Information

• Controls on Microsoft Outlook Forms
• OL2000: Working With User-defined Fields in Solutions
• OL2000: How to Programmatically Refer to Standard Fields
• OL2000: Working with Keywords Fields from VBScript
• OL2000: How to Use Fields and Controls with VBScript
• OL2002 Click Event Behavior for Standard Controls
• OL2000 PropertyChange Event Runs Twice When Setting Categories
• OL2002 How to Programmatically Set TextBox and CheckBox Values