Form Fields

Form fields are the places of a TXTextControl document that the user fills in, while the rest of an application form, order form or questionnaire stays as it is. There are five kinds: a text box, a check box, a combo box, a drop-down list and a date the user picks from a date control. They arrived in TX Text Control ActiveX 28.0, and version 31.0 added a built-in dialog box for their settings.

Read on to insert each kind of form field in Visual Basic 6, change its settings, read what the user entered, react to changes and protect the rest of the document. The code follows the TXWords sample, whose Insert and Format menus create and edit form fields.

Form Field Types

Each kind of form field has its own insert method and a field type that the FieldType property returns:

A combo box and a drop-down list have the same field type. They differ in the FieldChangeable property, which is True for a combo box.

How Form Fields Relate to Marked Text Fields

A form field is a marked text field of a special type. Marked text fields are ranges of text that your code addresses by a number, the field identifier; Marked Text Fields explains them. So everything that works with field identifiers works with form fields, too:

• The current field. Each insert method sets the FieldCurrent property to the identifier of the new form field, and each form field event sets it to the identifier of the changed field.
• The Field members. FieldText, FieldDelete, FieldNext, FieldAtInputPos and the other Field... members work with the identifier of a form field.

What sets a form field apart is how it comes into being and the data it carries:

• Only the insert methods create it. For the four form field types, FieldType is read only. You can't turn a standard marked text field into a form field by setting its type; you insert the form field with its Form...Insert method.
• It has members of its own. The items of a list, the date, the date format, the check box characters and the width of an empty field are set with the FormField... properties, not with FieldTypeData.
• It has events of its own. Four Form... events report that the user changed the check state, the date, the selected item or the text.

A Microsoft Word form field, such as FORMTEXT, is loaded as a TX Text Control form field or as a marked text field of the type txFieldMSWord, depending on how you load the document. Load and Save Forms shows the setting, and Using Microsoft Word Fields wraps the txFieldMSWord variant in a Visual Basic class.

Insert Form Fields

Form fields are inserted at the current input position, the position of the caret. In TXWords, the Insert menu has a Form Field submenu with the items Text, Check Box, Combo Box, Drop-Down List and Date. Each item calls one insert method with empty contents:

Private Sub mnuInsert_FormField_Text_Click()
    TXTextControl1.FormTextFieldInsert ""
End Sub

Private Sub mnuInsert_FormField_CheckBox_Click()
    TXTextControl1.FormCheckBoxInsert False
End Sub

Private Sub mnuInsert_FormField_ComboBox_Click()
    TXTextControl1.FormComboBoxInsert "", "", False
End Sub

Private Sub mnuInsert_FormField_DropDownList_Click()
    TXTextControl1.FormDropDownListInsert "", -1, False
End Sub

Private Sub mnuInsert_FormField_Date_Click()
    TXTextControl1.FormDateFieldInsert Nothing, False
End Sub

TXWords enables the Form Field submenu only when the input position isn't inside another field, that is, when FieldAtInputPos returns zero.

The parameters of the insert methods also set the initial contents. Each of the following statements inserts one field with contents at the current input position; in an application, each one runs when the caret is where the field belongs, for example from a menu item as in TXWords. Widths are in twips, 1/1440 inch; Text Formatting and Views explains the unit.

Dim sizes As String
sizes = "Small" & vbTab & "Medium" & vbTab & "Large"

' A text field that is 2 inches wide while it is empty
TXTextControl1.FormTextFieldInsert "", 2880

' A check box that is checked, with the default characters
TXTextControl1.FormCheckBoxInsert True

' A combo box with three items and the text "Medium"
TXTextControl1.FormComboBoxInsert "Medium", sizes, False

' A drop-down list with the first item selected
TXTextControl1.FormDropDownListInsert sizes, 0, False

' A date field with today's date
TXTextControl1.FormDateFieldInsert Date, False

The code works as follows:

• FormTextFieldInsert takes the text of the field and, optionally, its width when it is empty. Without the width, an empty field is 2000 twips wide.
• FormCheckBoxInsert takes the initial check state. Two optional parameters are the Unicode character codes of the checked and the unchecked symbol; the defaults are &H2612 and &H2610.
• FormComboBoxInsert takes the text of the combo box, its items separated by TAB characters (vbTab) and whether the drop-down arrow is shown right after insertion.
• FormDropDownListInsert takes the items, the zero-based index of the selected item (-1 for none) and whether the drop-down arrow is shown right after insertion.
• FormDateFieldInsert takes the date, here today's date from the Visual Basic Date function, and whether the date control is shown right after insertion. When the first parameter holds no date, the date field is empty. An optional fourth parameter is the date format; without it, the format depends on the language of the field's text.

Each insert method returns True when the field could be inserted and False otherwise, and sets FieldCurrent to the identifier of the new field. To keep the identifier, read FieldCurrent right after the call:

Dim nameFieldId As Integer
If TXTextControl1.FormTextFieldInsert("", 2880) Then
    nameFieldId = TXTextControl1.FieldCurrent
End If

Change the Settings of a Form Field

The FormField... properties take the field identifier as a parameter and change the data of an existing form field at run time:

Two read-only properties list the values that fit a field. FormFieldCheckedChars and FormFieldUncheckedChars return the characters that can show a check box's state; they depend on the check box's font. FormFieldDateFormats returns the date formats, as Day, Month and Year Format Picture strings separated by TAB characters; they depend on the locale of the field's text.

The following code gives a drop-down list new items and formats a date field with the first format its locale offers:

Dim formats() As String

' Replace the items of a drop-down list
TXTextControl1.FormFieldItems(sizeFieldId) = "S" & vbTab & "M" & vbTab & "L" & vbTab & "XL"

' Use the first date format the date field offers
formats = Split(TXTextControl1.FormFieldDateFormats(dateFieldId), vbTab)
TXTextControl1.FormFieldDateFormat(dateFieldId) = formats(0)

sizeFieldId and dateFieldId hold the identifiers of a drop-down list and a date field, read from FieldCurrent after they were inserted. An empty string as FormFieldDateFormat restores the default format of the field's language.

Open the Form Field Dialog Box

The FormFieldDialog method opens a built-in dialog box with the settings of a check box, combo box, text form field or date field. TXWords opens it from Format > Form Field > Properties... for the field at the input position:

Private Sub mnuFormat_FormFields_Properties_Click()
    Dim fieldId As Integer

    fieldId = TXTextControl1.FieldAtInputPos
    TXTextControl1.FormFieldDialog fieldId
End Sub

FormFieldDialog returns True when the user changed one or more settings and closed the dialog box with OK, and False when the user clicked Cancel. TXWords enables the Form Field submenu only when FieldAtInputPos returns a field whose FieldType is txFieldCheckBox, txFieldComboBox, txFieldDate or txFieldFormText.

Delete a Form Field

A form field is deleted like any marked text field, with FieldDelete. With True, the field and its text are deleted; with False, the text stays as plain text. TXWords deletes the field with its text from Format > Form Field > Delete Field. The following code first makes the field at the input position the current field:

TXTextControl1.FieldCurrent = TXTextControl1.FieldAtInputPos
TXTextControl1.FieldDelete True

Read What the User Entered

When the user has filled in the form, your code reads each field by its identifier:

• Text form fields, combo boxes and drop-down lists. FieldText returns the text of the current field. For a combo box and a drop-down list, this is the text of the selected item, or the text the user typed into the combo box.
• Check boxes. The text of a check box is either the checked or the unchecked character. Compare FieldText with the character that FormFieldCheckedChar returns.
• Date fields. FormFieldDate returns the date.

FieldNext enumerates the fields of a document. Its second parameter selects field types: &H40000 check boxes, &H80000 combo boxes and drop-down lists, &H100000 text form fields and &H200000 date fields. Their sum, &H3C0000, returns all form fields. The following procedure prints the value of every form field to the Immediate window:

Private Sub ListFormFields()
    Dim fieldId As Integer

    fieldId = TXTextControl1.FieldNext(0, &H3C0000)
    Do While fieldId <> 0
        TXTextControl1.FieldCurrent = fieldId
        Select Case TXTextControl1.FieldType(fieldId)
            Case txFieldCheckBox
                Debug.Print fieldId, (TXTextControl1.FieldText = _
                    ChrW(TXTextControl1.FormFieldCheckedChar(fieldId)))
            Case txFieldDate
                Debug.Print fieldId, TXTextControl1.FormFieldDate(fieldId)
            Case Else
                Debug.Print fieldId, TXTextControl1.FieldText
        End Select
        fieldId = TXTextControl1.FieldNext(fieldId, &H3C0000)
    Loop
End Sub

The code works as follows:

• FieldNext with 0 returns the first form field, and with an identifier the form field after it. It returns 0 when there is none, which ends the loop.
• FieldCurrent makes each form field the current field, which FieldText needs.
• FieldType tells the kinds apart. For a check box, the comparison prints True when the box is checked.

Respond to Changes

Four events report that the user changed a form field. Each passes the identifier of the field and sets FieldCurrent to it:

Because the event sets FieldCurrent, FieldText reads the changed field directly in the handler:

Private Sub TXTextControl1_FormSelectedItemChanged(ByVal FieldId As Integer)
    Debug.Print "Field " & FieldId & " now shows " & TXTextControl1.FieldText
End Sub

Private Sub TXTextControl1_FormDateChanged(ByVal FieldId As Integer)
    Debug.Print "Field " & FieldId & " now holds " & TXTextControl1.FormFieldDate(FieldId)
End Sub

Let Users Fill In a Protected Form

To let the user fill in the fields and change nothing else, protect the document: set the EditMode property to 1, Protected, or 3, Password Protected. What the user may still do is set by the DocumentPermissions property, and its setting txAllowEditingFormFields (2048) allows editing form fields:

TXTextControl1.DocumentPermissions = txAllowEditingFormFields
TXTextControl1.EditMode = 1

The values of DocumentPermissions can be added, for example txAllowEditingFormFields + txAllowPrinting. TXWords switches the setting on and off with Edit > Permissions > Allow Filling in Form Fields. Document Protection covers the edit modes, the other permissions and editable regions.

Load and Save Forms

Form fields are saved and loaded with the TX Text Control format and with the Microsoft Word (.doc, .docx) and RTF formats.

Form fields of documents created in Microsoft Word are loaded depending on two attributes of the LoadSaveAttribute property, which apply to the Word and RTF formats:

• txLoadMSWordFields converts Word fields into marked text fields of the type txFieldMSWord, which you read with FieldTypeData. Special Types of Marked Text Fields describes this for Word form fields.
• txLoadFormFields converts Word form fields into TX Text Control form fields and overrides txLoadMSWordFields. When both are True, check boxes, text form fields, combo boxes, drop-down lists and date fields become TX Text Control form fields, and all other Word fields become txFieldMSWord fields.

The following code loads a Word form so that its form fields can be read with the members on this page:

TXTextControl1.LoadSaveAttribute(txLoadMSWordFields) = True
TXTextControl1.LoadSaveAttribute(txLoadFormFields) = True
TXTextControl1.Load "c:\order-form.docx", 0, 13, False

The format value 13 is the Microsoft Word format (.docx) of the Load method. Working with Files covers loading and saving in general.

Since version 34.0, a form field can also have a descriptive text, which FieldDescriptiveText sets for the current field.

Key Members

The programming category Form Fields lists all members for form fields.

Related Pages

• Marked Text Fields: the field identifiers and Field... members that form fields share.
• Special Types of Marked Text Fields: the other field types and the import of Word fields as txFieldMSWord fields.
• Using Microsoft Word Fields: a Visual Basic class for the Word FORMTEXT field.
• Signature Fields: fields that receive a signature image and a digital signature.
• Document Protection: edit modes, permissions and editable regions.
• A Word Processor: the TXWords sample and its menus.