InsertFormField

Syntax

InsertFormField [.Entry = text] [, .Exit = text] [, .Name = text] [, .Enable = number] [, .TextType = number] [, .TextDefault = text] [, .TextWidth = number or text] [, .TextFormat = text] [, .CheckSize = number] [, .CheckWidth = number or text] [, .CheckDefault = number] [, .Type = number] [, .OwnHelp = number] [, .HelpText = text] [, .OwnStat = number] [, .StatText = text]

Remarks

Inserts a form field at the insertion point. The arguments for the InsertFormField statement correspond to the options in the Form Field (Insert menu) and Form Field Options dialog boxes.

Argument

Explanation

.Entry

The macro that runs when the form field receives the focus.

.Exit

The macro that runs when the form field loses the focus.

.Name

A name for a bookmark that will mark the form field.

.Enable

If 1, allows the form field to be changed as the form is filled in.

.TextType

When inserting a text form field, specifies the type:

0 (zero) Regular Text

1 Number

2 Date

3 Current Date

4 Current Time

5 Calculation

.TextDefault

The default text for a text form field.

.TextWidth

When inserting a text form field, specifies a maximum width:

0 (zero) Unlimited

> 0 A maximum width, in characters


Argument

Explanation

.TextFormat

When inserting a text form field, specifies a format appropriate for .TextType. If .TextType is set to 0 (zero) for Regular Text, the following values are available: Uppercase, Lowercase, First Capital, Title Case.

For formats available to other text types, review the items in the Text Format box in the Text Form Field Options dialog box.

.CheckSize

When inserting a check box form field, specifies whether to set a fixed size:

0 (zero) Auto (the size is determined by the font size of the surrounding text).

1 Exactly (the size is fixed to that specified by .CheckWidth).

.CheckWidth

When inserting a check box form field, and if .CheckSize is set to 1, specifies a fixed width and height in points or a text measurement.

.CheckDefault

When inserting a check box form field, specifies whether the check box should be cleared or selected by default:

0 (zero) Cleared

1 Selected

.Type

Specifies the type of form field to insert:

0 (zero) or omitted Text form field

1 Check box form field

2 Drop-down form field

.OwnHelp

Specifies the source of the text that is displayed in a message box when the form field has the focus and the user presses the F1 key (Windows) or COMMAND+/ or HELP (Macintosh):

0 (zero) None

1 The text of the AutoText entry specified by .HelpText

2 The text specified by .HelpText

.HelpText

If .OwnHelp is set to 1, the name of an AutoText entry containing help text for the form field. If .OwnHelp is set to 2, help text.

.OwnStat

Specifies the source of the text that is displayed in the status bar when the form field has the focus:

0 (zero) None

1 The text of the AutoText entry specified by .StatText

2 The text specified by .StatText

.StatText

If .OwnStat is set to 1, the name of an AutoText entry containing status bar text for the form field. If .OwnHelp is set to 2, the text to be displayed in the status bar.


Examples

This example inserts a drop-down form field for which status bar text is specified and then adds the names of three cities to the form field:


InsertFormField .Name = "Cities", .Enable = 1, .Type = 2, \
        .OwnStat = 1, .StatText = "Select a city."
AddDropDownItem "Cities", "Bonn"
AddDropDownItem "Cities", "Paris"
AddDropDownItem "Cities", "Tokyo"

The following example inserts a check box form field that is 8 points high and wide and is selected by default. WriteSettings is specified as the "on-exit" macro that runs when the check box loses the focus. In a macro, instructions following this one could use GetFormResult() and SetPrivateProfileString to record in a text file whether the user selects or clears the check box.


InsertFormField .Exit = "WriteSettings", .Name = "Check1", \
        .Enable = 1, .CheckSize = 1, .CheckWidth = "8 pt", \
        .CheckDefault = 1, .Type = 1

The following example inserts a text form field. The argument .TextType = 1 specifies that the text is a number, and .TextFormat = "0%" specifies that the number be shown as a percentage. The default percentage is 100 percent.


InsertFormField .Name = "PercentComplete", .Enable = 1, \
        .TextType = 1, .TextWidth = "4", \
        .TextDefault = "100%", .TextFormat = "0%", .Type = 0

See Also

AddDropDownItem, CheckBoxFormField, DropDownFormField, EnableFormField, FormFieldOptions, RemoveAllDropDownItems, RemoveDropDownItem, TextFormField