Special Types of Marked Text Fields

Text Control supports special types of marked text fields that can be defined with the FieldType property. The following types are possible:

Type Description
txFieldExternalLink This field defines the source of a hypertext link to a location outside of the document.
txFieldInternalLink This field defines the source of a hypertext link to a location in the same document.
txFieldLinkTarget This field defines the target of a hypertext link.
txFieldPageNumber This field displays the current page number. It can only be used in headers or footers.
txFieldAllPages This field displays the number of pages in the document or section. It can only be used in headers or footers.
txFieldHighlight This field defines a piece of text that can be highlighted.
txFieldTopic This field defines a position in a document that is the beginning of a topic.
txFieldMSWord This field defines a Microsoft Word field.
txFieldHighEdit This field defines a Heiler HighEdit field.

All of these fields have the same general properties as standard marked text fields with the following exceptions: Fields of the type txFieldLinkTarget or txFieldTopic define text positions in a document. Therefore as they have no visible text, they cannot be edited and have no extended edit mode. Fields of the type txFieldPageNumber or txFieldAllPages can only be used in headers or footers.

For each of the special field types Text Control handles some additional data, called type-related data. These data can be set or returned with the FieldTypeData property. For the types txFieldExternalLink and txFieldInternalLink these data are the information to where the link points. This can be an address or a file name and/or the name of a target in a document. Targets in documents can be realized with marked text fields, which have the type txFieldLinkTarget. These fields can have a name that is saved as type-related data. When the user clicks on a field of the type txFieldExternalLink or txFieldInternalLink a FieldLinkClicked event is fired including the information to where the link points. The FieldGoto method can be used to scroll to a target position and the FieldNext method can be used to enumerate all fields of a certain type.

To insert a field of a special type from programming code, use the FieldInsert method first and then set the type and its data. The following Basic example inserts a field that represents a link 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"

When a user clicks on this marked text field, a FieldLinkClicked event is fired, containing the address of the homepage. To insert a field of the type txFieldLinkTarget, the created field must not have text. The following Basic example creates a field that represents such a target:

Dim Field As Integer
TXTextControl1.FieldInsert ""
Field = TXTextControl1.FieldCurrent
TXTextControl1.FieldType(Field) = txFieldLinkTarget
TXTextControl1.FieldTypeData(Field) = "first target"

This creates a field with the name "first target". The FieldGoto method can be used to scroll to this target:

When HTML, RTF or Word documents are loaded, source and target fields for hypertext links are automatically created. To perform this, set the txEnableLinks attribute with the LoadSaveAttribute property before using the Load method.

Fields of the type txFieldPageNumber display the current page number and can only be used in headers or footers. The following Basic example inserts a page number field:

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

Fields of the type txFieldHighlight can be used to mark pieces of text in a document that can be highlighted. This is useful, for instance, to highlight occurrences of a word found during a global search. The highlight color is stored as additional data for these fields. The FieldGoto method enables the programmer to scroll fom highlight to highlight. When RTF documents are loaded with the Load method and the txEnableHighlights attribute has been set previously with the LoadSaveAttribute property, all RTF '\cbN' keywords are automatically converted to fields of the type txFieldHighlight. N is the index of a color in the RTF color table.

Fields of the type txFieldTopic are text positions in a document defining the beginning of a topic. The FieldGoto method can be used to scroll to a topic with a certain number. When RTF documents are loaded with the Load method and the txEnableTopics attribute has been set previously with the LoadSaveAttribute property, all RTF '\sect' keywords are automatically converted to fields of the type txFieldTopic. These topics are numbered from 1 to n in the order they appear in the RTF document.

TX Text Control supports field formats of other applications such as Microsoft Word. Fields of the type txFieldMSWord and txFieldHighEdit provide an interface to retrieve and change the data and parameters of such fields. Currently supported formats are the Microsoft Word Field Format, the format of Microsoft Word Form Fields and the field format of the Heiler HighEdit component. Because these formats are not compatible, the user must specify the format when a document is loaded. The following code imports all MergeField and PrintDate fields contained in a RTF document that has been created with Microsoft Word:

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

After the document has been loaded all MergeField and PrintDate fields are available through the fields of TX Text Control.

The field's parameters are stored as a tab separated string in the TXTextControl.FieldTypeData property. The following is the format of a MergeField defined through Microsoft Word:

MERGEFIELD FieldName [Switches]

For example: MERGEFIELD Address \* Upper \v

For further information about the switches and their meaning, please refer to Microsoft's Field Reference:

http://www.textcontrol.com/in/msofficefieldreference.htm

In this example the FieldName is Address and there are two switches specifying some formatting options. The TXTextControl.FieldTypeData property string then contains three separated strings, the first of which is the FieldName and the others are the switches.

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

[Visual Basic]
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

TX Text Control also supports importing and exporting of Microsoft Word form fields. These fields can be imported specifying FORMCHECKBOX, FORMDROPDOWN or FORMTEXTBOX with the TXTextControl.LoadSaveAttribute property. Microsoft Word form fields also have parameters, that can be edited in Microsoft Word with the Form Field Options dialog box. TX Text Control provides these parameters through the TXTextControl.FieldTypeData property using the XML syntax of the Office Open XML Format.

To learn more about the Office Open XML Format, please refer to the official ECMA standard:

http://www.textcontrol.com/in/ecmaofficeopenxmlfileformats.htm