Special Types of Marked Text Fields

Hypertext links, page numbers, highlights, topics and the fields of Microsoft Word and Heiler HighEdit documents are all marked text fields of a special type in TX Text Control ActiveX. You give a field its type with the FieldType property and the data that goes with the type with FieldTypeData. The sections below describe each type, with Visual Basic code for links, page numbers and Word fields.

Field Types

Fields of these types have the same general properties as standard marked text fields, with two exceptions:

• txFieldTopic fields define text positions in a document. They have no visible text, so they cannot be edited and have no extended editing mode.
• txFieldPageNumber and txFieldAllPages fields can only be used in headers or footers.

Type-Related Data

For each special type, TXTextControl handles additional data, the type-related data, which FieldTypeData sets and returns. What it holds depends on the type: the destination of a link, the color of a highlight or the parameters of a Word field. FieldNext enumerates all fields of a certain type.

Insert a Hypertext Link

For txFieldExternalLink and txFieldInternalLink, the type-related data says where the link points: an address or a file name, the name of a target in a document, or both. You insert targets in a document with the TargetInsert method, which takes the target's name; Link Targets and Bookmarks lists the members that work with them.

To insert a field of a special type from code, insert a field with FieldInsert first and then set its type and its data. The following Visual Basic code inserts a field that links to the Text Control homepage:

Dim Field As Integer
TXTextControl1.FieldInsert "visit the Text Control homepage"
Field = TXTextControl1.FieldCurrent
TXTextControl1.FieldType(Field) = txFieldExternalLink
TXTextControl1.FieldTypeData(Field)  = _
      "http://www.textcontrol.com"

The code works as follows:

• FieldInsert inserts a marked text field with the text "visit the Text Control homepage".
• FieldCurrent returns the identifier of the new field.
• FieldType makes the field the source of an external link, and FieldTypeData sets the address it points to.

When the user clicks a txFieldExternalLink or txFieldInternalLink field, TXTextControl fires the FieldLinkClicked event with the information where the link points; for the field above, this is the address of the homepage. The TargetGoto method then scrolls to a target position.

Load Links From Documents

When HTML, RTF or Word documents are loaded, TXTextControl creates the source and target fields of their hypertext links automatically. Set the txEnableLinks attribute with the LoadSaveAttribute property before you call the Load method.

Insert a Page Number

A txFieldPageNumber field displays the current page number and can only be used in a header or footer. The following Visual Basic code inserts one:

TXTextControl1.FieldInsert ""
TXTextControl1.FieldType(TXTextControl1.FieldCurrent) = _
      txFieldPageNumber

Highlight Text

txFieldHighlight fields mark pieces of text that can be highlighted, for instance the occurrences of a word that a global search has found. The highlight color is stored as the type-related data of the field, and the FieldGoto method scrolls from one highlight to the next.

RTF documents can bring highlights with them. When the txEnableHighlights attribute is set with LoadSaveAttribute before an RTF document is loaded with Load, every RTF \cbN keyword is converted to a txFieldHighlight field. N is the index of a color in the RTF color table.

Mark Topics

txFieldTopic fields are text positions that mark the beginning of a topic. FieldGoto scrolls to the topic with a given number.

When the txEnableTopics attribute is set with LoadSaveAttribute before an RTF document is loaded with Load, every RTF \sect keyword is converted to a txFieldTopic field. The topics are numbered from 1 to n in the order they appear in the RTF document.

Import Microsoft Word Fields

TX Text Control supports the field formats of other applications such as Microsoft Word. Fields of the types txFieldMSWord and txFieldHighEdit let you retrieve and change the data and parameters of such fields. Three formats are supported:

• the Microsoft Word field format;
• the format of Microsoft Word form fields;
• the field format of the Heiler HighEdit component.

The formats are not compatible with each other, so you specify the format when you load a document. The following code imports all MergeField and PrintDate fields of an RTF document created with Microsoft Word:

TXTextControl1.LoadSaveAttribute(txLoadMSWordFields) = True
TXTextControl1.LoadSaveAttribute(txMSWordFieldTypeNames) = "MERGEFIELD" + Chr(9) + "PRINTDATE"
TXTextControl1.Load "c:\invoice.rtf", 0, 5, False

After loading, all MergeField and PrintDate fields of the document are marked text fields of TX Text Control.

The Parameters of a Word Field

FieldTypeData holds the field's parameters as a tab-separated string. A MergeField defined in Microsoft Word has this format:

MERGEFIELD FieldName [Switches]

For example, in MERGEFIELD Address \* Upper \v the FieldName is Address, and two switches specify formatting options. The FieldTypeData string of this field starts with the type name, MERGEFIELD, followed by the field's parameters: the FieldName and then the switches. Microsoft's field reference for Word explains the switches and their meaning.

Change the Text of Imported Fields

The following code goes through all fields imported by the example above and sets the visible text of the address field:

FieldID = TXTextControl1.FieldNext(FieldID, &H8000)
Do While FieldID > 0
  TXTextControl1.FieldCurrent = FieldID
  Dim parameters() As String
  parameters = Split(TXTextControl1.FieldTypeData(FieldID), Chr(9))

  If parameters(0) = "MERGEFIELD" And parameters(1) = "Address" Then
    TXTextControl1.FieldText = "Bakerstreet, London"
  End If

  FieldID = TXTextControl1.FieldNext(FieldID, &H8000)
Loop

The code works as follows:

• FieldNext with the field group &H8000 returns the identifier of the next txFieldMSWord field; the loop ends when there is none.
• FieldCurrent makes each field the current field.
• Split divides the FieldTypeData string at the tab characters, Chr(9).
• When the field is the MergeField named Address, FieldText sets its visible text.

Import Microsoft Word Form Fields

TX Text Control also imports and exports Microsoft Word form fields. To import them, specify FORMCHECKBOX, FORMDROPDOWN or FORMTEXTBOX with the LoadSaveAttribute property.

Word form fields have parameters, too, which users edit in Microsoft Word in the Form Field Options dialog box. TX Text Control provides these parameters through FieldTypeData, in the XML syntax of the Office Open XML format. The official ECMA standard for Office Open XML file formats describes this syntax.

Related Pages

• Link Targets and Bookmarks: the Target members that replace txFieldLinkTarget fields.
• Hypertext Links: a Visual Basic application that inserts links and targets and reacts to clicks.
• Using Microsoft Word Fields: classes for the Word fields MERGEFIELD and FORMTEXT.
• Marked Text Fields: the members that every marked text field has.