Programming Hypertext Links

Hypertext links are connection points with other text positions in the same or another document. TX Text Control distinguishes between links that point to text positions in the same document and links that point to other documents. Links that point to another document are called hypertext links and are encapsulated through the HypertextLink class.

A link to another position in the same document is called a document link, encapsulated through the DocumentLink class. The position to which the link points can also be defined through the programmer. It is called a document target and can be specified with the DocumentTarget class.

For each type of these objects, a Text Control maintains a collection to enable the programmer to add, remove or manipulate an item. An appropriate property of the TextControl class as described in the chapter TextField Classes enables access to the collection.

The following code defines a link and a target inside a TextControl document. It first defines a target at the top of the document's second page and then creates a hypertext link that points to this target:

[C#]
int curPosition = textControl1.InputPosition.TextPosition;
DocumentTarget target = new DocumentTarget("Second Page");
textControl1.InputPosition = new InputPosition(2, 1, 0);
textControl1.DocumentTargets.Add(target);

textControl1.InputPosition = new InputPosition(curPosition);
DocumentLink link = new DocumentLink("Goto second page", target);
textControl1.DocumentLinks.Add(link);
[Visual Basic]
Dim curPosition As Integer = TextControl1.InputPosition.TextPosition
Dim Target As New DocumentTarget("Second Page")
TextControl1.InputPosition = New InputPosition(2, 1, 0)
TextControl1.DocumentTargets.Add(Target)

TextControl1.InputPosition = New InputPosition(curPosition)
Dim Link As New DocumentLink("Goto second page", Target)
TextControl1.DocumentLinks.Add(Link)

Before setting the input position to the second page, the old position is saved. The old position is restored before inserting the link. The target's constructor receives a name for the target, which is independent of the Name property inherited from the TextField class. Therefore, in addition to the target name, other string data can still be stored, using the document target's Name property.

There is no automatic linking implemented for a link-target pair in a Text Control document, because applications handle clicks differently depending on whether additional keyboard keys are pressed. To implement linking use the target's ScrollTo method when a user has clicked onto a link as shown with the following code example:

[C#]
textControl1.DocumentLinkClicked
         += new DocumentLinkEventHandler(textControl1_DocumentLinkClicked);
private void textControl1_DocumentLinkClicked(object sender, DocumentLinkEventArgs e) {
    if (Control.ModifierKeys == Keys.Control) {
        e.DocumentLink.DocumentTarget.ScrollTo();
    }
}
[Visual Basic]
Private Sub TextControl1_DocumentLinkClicked(ByVal sender As Object, _
        ByVal e As DocumentLinkEventArgs) Handles TextControl1.DocumentLinkClicked
    If Control.ModifierKeys = Keys.Control Then
        e.DocumentLink.DocumentTarget.ScrollTo()
    End If
End Sub

This code implements an event handler for the TextControl.DocumentLinkClicked event. The handler's code scrolls to the target that is connected with the link that has caused the event. This occurs only, if the CTRL keyboard key is pressed.

Hypertext links to other documents are treated similarly. They are inserted or deleted with the HypertextLinkCollection class. A click on such a link results in a TextControl.HypertextLinkClicked event. The application has to provide the code for the linking action.

All editing features, as described in the chapter Editing Marked Text Fields, can also be used for hypertext links. But a document target is handled like a text position, therefore editing a target is not possible and using the Text property with the DocumentTarget class results in an error. Relating string data and identifiers as described in the chapter Names and Identifiers is possible for links and targets. Further code examples can be found in the User's Guide chapter Using Hypertext Links.