Howto: Use Hypertext Links

This chapter shows you how to add hypertext links and targets to your documents, and how to respond to events fired by TX Text Control when a hypertext link is clicked. For an overview of the various classes, properties, methods and events involved, please refer to the chapter Text Fields and Hypertext Links in the Technical Articles part of this manual.

The source code for this example is contained in the subfolders Step1 to Step3 of the following directories:

  • %USERPROFILE%\My Documents\TX Text Control 29.0.NET for Windows Forms\Samples\WinForms\VB.NET\Hyperlinks
  • %USERPROFILE%\My Documents\TX Text Control 29.0.NET for Windows Forms\Samples\WinForms\CSharp\Hyperlinks

Used TX Text Control controls:

  • TXTextControl.TextControl

Relevant API Links

Adding Document Targets

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.

Image

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.

Image

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);
textControl1.DocumentTargets.Add(Target);
Dim Target As New TXTextControl.DocumentTarget(InsertTarget.TargetName)
TextControl1.DocumentTargets.Add(Target)

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);
For Each Target As TXTextControl.DocumentTarget In tx.DocumentTargets
    cboLinkTo.Items.Add("#" + Target.TargetName)
Next

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)
{
    e.DocumentLink.DocumentTarget.ScrollTo();
}
Private Sub mnuView_JumpToTargets_Click(ByVal sender As System.Object, _
    ByVal e As System.EventArgs) Handles mnuView_JumpToTargets.Click
    e.DocumentLink.DocumentTarget.ScrollTo()
End Sub

Editing Links to Targets

The auto-scroll 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 auto-scroll 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.

Image