Step 3: Adding Document Targets

Windows Forms User's Guide > Howto: Use Hypertext Links

Step 1 and 2 introduced references to external resources, i.e. addresses of web pages or files. In this step, links to positions in the same document will be discussed. These links are called document links and the positions, to which they point, are called document targets. Document targets are also refered to as anchors (in the context of HTML editors) or bookmarks (in word processors).

When running this sample program, first add some text and then one or two targets with the Insert / Target... menu item.

Finally use the Insert / Hypertext Link... menu item to add links to these targets. The names of the targets you have inserted will be displayed in the Link Location combo box.

Inserting a Target

A target is created by adding a DocumentTarget object to the DocumentTargets collection.

Unlike links, targets have no visible text. The constructor therefore has only a single parameter, which is the target's name.

TXTextControl.DocumentTarget Target = 
    new TXTextControl.DocumentTarget(InsertTarget.TargetName);
[Visual Basic]
Dim Target As New TXTextControl.DocumentTarget(InsertTarget.TargetName)

Inserting Links to Targets

The Hypertext Link dialog box from Step 2 needs to be extended so that it will not only accept URLs as link targets, but also lets us select from a list of document targets. This is done by replacing the Link To text box with a combo box. The combo box is filled with targets by adding all elements from the DocumentTargets collection:

foreach (TXTextControl.DocumentTarget Target in tx.DocumentTargets)
    cboLinkTo.Items.Add("#" + Target.TargetName);
[Visual Basic]
For Each Target As TXTextControl.DocumentTarget In tx.DocumentTargets
    cboLinkTo.Items.Add("#" + Target.TargetName)

Jumping to a Target

When a document link is clicked on, text should automatically be scrolled so that the text part containing the link's target becomes visible. This is done by responding to the DocumentLinkClicked event and calling the ScrollTo method. The DocumentTarget class inherits this method from its parent class, TextField.

private void textControl1_DocumentLinkClicked(object sender,
    TXTextControl.DocumentLinkEventArgs e)
[Visual Basic]
Private Sub mnuView_JumpToTargets_Click(ByVal sender As System.Object, _
    ByVal e As System.EventArgs) Handles mnuView_JumpToTargets.Click
End Sub

Editing Links to Targets

The autoscroll feature has one drawback in that you can no longer click on a link and open the hyperlinks dialog box to edit it. This is because each time you click on a link, Text Control will scroll it out of view. However, this can be fixed by adding a Jump to targets item to the View menu, which switches the autoscroll feature on and off as required.

Displaying and Editing Targets

TX Text Control is able to display a marker to visualize the location of a target. But if targets are invisible, how can you locate them in your document, or delete one that's no longer required? The solution is a list box which displays the names of all targets a document contains, and lets you jump to or remove a selected target.