Controls on Outlook Forms
Sometimes controls on Microsoft Outlook forms don't work the way you expect. Or, maybe you need some tips to go beyond the basics of form design. This page collects such tips and tricks about the different basic controls for Outlook form design, as well as more advanced techniques.
From the Microsoft Knowledgebase
Some built-in controls are not available to custom form designers:
- Date/time picker on appointment, task, and journal forms
- Telephone number dialog on contact forms
- Picture control on the contact form in Outlook 2003 and later
- Controls introduced in Outlook 2007 for form regions; do not use these on legacy custom forms
Using non-Outlook controls on an .oft form template or other one-off form may result in a security prompt; see Microsoft Outlook Forms Security Issues.
To enable a text box to wrap lines, bring up the control's Properties dialog and check the Multi-line box. Or, bring up the Advanced Properties dialog and set the Multiline and EnterKeyBehavior properties to True. The WordWrap property will also be set to True, by default.
A multiline text box will not show a scroll bar until the user clicks in the control. If you want the user to be able to use carriage returns in a multiline text box, use the Advanced Properties dialog to set the EnterKeyBehavior property to True.
To set the focus to a multiline text box and put the cursor at the beginning of a new line at the bottom of the previously entered text, you can use this code, adjusting it for your own page and control names:
An unbound text box on an Outlook form does not fire a Click event.
List and Combo Boxes
To populate a list or combo box, you can either use the AddItem method or the List property. I think List is much easier -- especially for multiple column list boxes. (TIP: You probably will find the Split() and Join() functions convenient for working with arrays.)
To populate a list or combo box from the data in an Excel worksheet, see Loading a combobox...is there a faster way? for a code sample.
To populate a multicolumn list or combo box from an ADO Recordset, set its ColumnCount property to the number of fields in the RecordSet and then use this very simple syntax:
ListBox1.Column = rst.GetRows
A single-select list or combo box bound to an Outlook property fires the PropertyChange or CustomPropertyChange event. A single-select unbound list or combo box fires a Click event.
If you are using a multi-column list or combo box, you may want to retrieve information from one of the columns besides the bound column. The ListIndex property returns the index of the selected row. Use that value with the Column property to return the value in a particular column. Remember that Column is zero-based. This example returns the value in the second column for the selected row:
val = ListBox1.Column(1, ListBox1.ListIndex)
A multi-select list box fires no events. To get the selected values from an unbound multi-select list box, you cannot use ListIndex. Instead, loop through all the items in the list and check the value of the Selected property for each one. Use code in the Item_Write event to store the selections in a delimited list in a text property, then reverse the process to reload the selections in the Item_Open event handler. Alternatively, if the list is small and static enough that you can set it in the Properties dialog for the control, using the Possible Values setting on the Value tab, you can bind the list box to a keywords-type field. Note that Outlook will not automatically display the user's selections if you bind the control to a keywords field and set the rows of the multi-select list box in code; it requires additional code to set the value of the Selected property for the appropriate rows. For a demonstration of these different ways of dealing with multi-select list boxes, download Form Controls Demo.zip (9kb, 7 Jul 09), unzip it, open the .oft file, and publish that form. Then run the published form.
In a combo box, if you want to require the user to use one of the listed choices, bring up the Advanced Properties dialog for the control and set the value of the MatchEntry property to -1 - True. If the user does not choose one of the choices, Outlook will pop up the message "Invalid Property Value."
List boxes on Outlook forms do not support column headings (the ColumnHeads property). Both list boxes and combo boxes are limited to a maximum of 10 columns.
Also known as radio buttons, option buttons are a good technique if you need the user to pick from a small number of mutually exclusive choices.
On the Value tab of each button's Properties dialog, bind each button in a set to the same Outlook property and set a unique value for each button.
To work with your option buttons in code, you can use a Select Case statement:
The above example assumes that you assigned a string representing a color to each button.
If you have more than one set of option buttons on a form, you must surround each set with a frame control. (Actually, you can leave the frame off one set -- and that set will use the form page as a whole as the equivalent of a frame.)
If you bind two option buttons to a Yes/No property, on the Value tab for each control, you should set the format to True/False. Set the Value property of one button to True and the other to False. Alternatively, set the format to Yes/No, and use Yes and No for the Value property for the two buttons.
Bound option buttons will fire a PropertyChange or CustomPropertyChange event, depending on what property they are bound to.
If you are using a set of unbound buttons, the value for each button can only be either True or False. Your code can check the values of each button in the set until it finds the one that's True. Unbound option buttons will fire a Click event; you may want to use the Caption or Tag property of the button to hold information related to the button that your code can use to set the value of another control or property on the form.
For a demonstration of both bound and unbound option buttons, download Form Controls Demo.zip (9kb, 9 Jul 09), unzip it, open the .oft file, and publish that form. Then run the published form.
If you have more than one set of option buttons to show on a form page, you must put each set inside its own frame control. (The form page itself acts as a frame, by the way.) Other uses for frames:
- Enclose a group of controls so that they can be enabled/disabled or hidden/shown with a single line of code
- Provide a visual separator to set off some controls
To work with the properties of a control inside a frame, you need to go through the frame's own Controls property. Here's a code snippet that shows the text inside a text box that is inside a frame when a command button is clicked:
In the above example, if you wanted to hide Frame1 and all its controls in Frame1, you'd use:
Frame1.Enabled = False
To set the tab order for the controls inside a frame, select the frame first, then choose Layout | Tab Order.
A spin button control provides up and down arrows that increment the value of the control as the user clicks them. It's a good choice where you want to provide a limited range of integer values to choose from.
To get the value from a spin button control, you must bind it to an Outlook property. (An unbound spin button does not support a Click event on Outlook forms.) To show the current value of the spin button, you can provide a text box bound to the same property.
On the Advanced Properties for the spin button, set the Max, Min and SmallChange properties to control the maximum and minimum values and the amount that the value increments with each click.
A sample task form shows how to use a spin button to duplicate the behavior of the control that changes the value of the TaskItem.PercentComplete property (the % Complete field in the UI) in 25% increments.
The multipage control consists of two or more tabbed pages in a Pages collection, each of which can have its own set of controls. To control which page is shown, set the page's Visible property to True (if it was hidden) and then set the multipage control's Value property to the index for the page. This is a zero-based property, meaning that 0 is the value for the leftmost page. The SelectedItem property returns a Page object corresponding to the currently displayed page.
No events are fired when the user clicks a tab to switch to a different page. A workaround is to have the user switch pages with command buttons instead. The Multipage Demo form shows both the lack of a Click event and this command button technique.
Each Page in the Pages collection has a Controls collection, used to provide access to the individual controls. The Change multipage control focus code sample demonstrates how to make a page visible or hidden and how to access individual controls.
An individual Page object fires a Click event when the user clicks on the empty body of the page, but that's not very useful.
Outlook View Control
Web Browser Control
For Outlook 2003, the October 28, 2008, hotfix adds a NewAccel registry value to solve with the web browser control on custom forms displaying an "operation failed" error when common accelerator keys are used.