Microsoft KB Archive/182362

= OL98: How to Use Fields and Controls with VBScript =

Article ID: 182362

Article Last Modified on 2/26/2004

-

APPLIES TO


 * Microsoft Outlook 98 Standard Edition

-



This article was previously published under Q182362



SUMMARY
When you write Visual Basic Scripting Edition (VBScript) code to customize a Microsoft Outlook 98 form, you must understand the relationship between the item's fields and form controls.



MORE INFORMATION
Microsoft provides programming examples for illustration only, without warranty either expressed or implied, including, but not limited to, the implied warranties of merchantability and/or fitness for a particular purpose. This article assumes that you are familiar with the programming language being demonstrated and the tools used to create and debug procedures. Microsoft Support professionals can help explain the functionality of a particular procedure, but they may not modify these examples to provide added functionality or construct procedures to meet your specific needs. If you have limited programming experience, you may want to contact the Microsoft fee-based consulting line at (800) 936-5200. For more information about the support options available from Microsoft, please see the following page on the World Wide Web:

http://support.microsoft.com/default.aspx?scid=fh;EN-US;CNTACTMS

The Difference Between Controls and Fields
Controls are objects, such as a text box, a scroll bar, a rectangle, a list box, or a command button, that let users control the program. You place controls on a form to display data or choices, perform an action, or make the form easier to read. As an example, you can control a mail message item by using built-in controls, such as the "Subject" textbox, or you can modify the form by adding your own controls. Controls, by themselves, provide no storage for the data that is associated with them. Controls are only the visual representation of the data on the form.

Item fields are the actual Messaging Application Programming Interface (MAPI) properties where you store data when you save or send an item. In the example above, the "Subject" listbox control is linked (or "bound") to an item field also called "Subject." The control and the field may or may not have the same name.

Using Fields and Controls
All of the built-in form controls (To, From, Cc, and such) are automatically linked to corresponding built-in MAPI fields. However, if you create a custom form and add a custom control, you should typically create a MAPI field to store the data that is associated with the control.

For example, suppose you want to add a textbox to your mail message form that may enable people to type in their office location. When you design the new form, you can add a textbox control by dragging the control from a special toolbar called the Control Toolbox. This creates a place to type in the office location. Since the control itself provides no storage for the item, when you send the item to someone, the text you typed into the office location is lost. You must also create a field to provide storage for the data.

You can create a field by using the Field Chooser. Once the field is created, you then use the Properties dialog of the office location textbox control to bind the control to the field. Once this is done, the office location control has an item field to provide storage for the data. This way, when someone fills in the field and sends the item, the data is preserved when the item is received by someone else.

Steps to Create a Control on a Form

 * 1) Create a new item, such as a new message.
 * 2) On the form's Tools menu, point to Forms, and then click Design This Form to switch to the form's design mode.
 * 3) On the Form menu, click Control Toolbox.
 * 4) Drag the control type that you want from the Control Toolbox to the place on the form where you want the control to appear.

Steps to Create a Field to Provide Storage for the Control

 * 1) If the Field Chooser window is not open, on the form's Form menu, click Field Chooser.
 * 2) Click New to open the New Field dialog box.
 * 3) In the Name box, type a name for your new field. In the Type list, click to select the data type of field. In the Format list, click to select the format for the field.
 * 4) Click OK.

Steps to Bind a Control to a Field

 * 1) Starting in the form design view, right-click the control, and then click Properties on the shortcut menu.
 * 2) In Properties, click the Value tab.
 * 3) Click Choose Field the field you want to bind to this control.

NOTE: You can also click New to create a new field at this time instead of using the Field Chooser.

Using VBScript to Change Field and Control Values
The VBScript syntax for accessing values associated with controls is quite different from the syntax for accessing fields. There are situations where it is possible to change a value by using either method.

Syntax for Accessing a Control on a Form
  Generic: Item.GetInspector.ModifiedFormPages("PageName").Controls _ ("ControlName").Property =

Example: Item.GetInspector.ModifiedFormPages("Message") _ .Controls("OfficeLoc").Visible = True

Syntax for Accessing a Built-in Field
  Generic: Item.FieldName = 

Example: Item.Subject = "This is a new subject"

Syntax for Accessing a Field You Create (User-defined Field)
  Generic: Item.UserProperties.Find("FieldName").Property = Value

Example: Item.UserProperties.Find("OfficeLoc").Value = "Blg 4, 1234"

Usage Examples
In the "Office Location" example above, these two example lines of code have the same effect on the form. Item.UserProperties.Find("OfficeLoc").Value = "Blg 4, 1234" -or- Item.GetInspector.ModifiedFormPages("Message").Controls _ ("OfficeLoc").Text = "Blg 4, 1234" The first example changes the Office Location field to a new value, and the second line changes the textbox control text property to the new value. Since the control is bound to the field, a change made in either place affects the other.

Tips for When to Use Each Method
  When you want to change a "Property" (color, visibility, bold, italic) of a form control, you must use the control syntax. You cannot set control properties by changing the field.   Example:    Make the Office Location textbox not visible

Correct:   Item.GetInspector.ModifiedFormPages("Message") _ .Controls("OfficeLoc").Visible = False

Incorrect: Item.UserProperties.Find("OfficeLoc").Visible = False   When you want to change the value of the data (text, number, date) use the field syntax. If the field is a built-in field then the syntax for the field method is much simpler.   Example:    Change the office location text to "Building 5"

Preferred: Item.UserProperties.Find("OfficeLoc").Value = "Building 5"

Also works: Item.GetInspector.ModifiedFormPages("Message") _ .Controls("OfficeLoc").Text = "Buiding 5" Example:   Change the subject to "This is a subject"

Preferred: Item.Subject = "This is a subject"

Also works: Item.GetInspector.ModifiedFormPages("Message") _ .Controls("Subject").Text = "This is a subject"  The control method requires that the form is open. When the form is closed, the control is not available. The item field is always available and you can use references to the field in your code at all times. For example, suppose you want to be able to start from one item form and click a button that changes the subject for a different item's form. If you use the field method, you do not have to write code to open the form. If you use the control method, your code must include lines to display the form. Displaying the item takes more code and more time. Fields work whether the form is loaded or not, regardless of what page the control is on, and affect all the controls that display that field, not just one. Using fields also insures that other fields calculated from the original update.</ul>

<div class="references_section">