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%\Documents\TX Text Control 32.0.NET for WPF\CSharp\Howto\Hyperlinks
  • %USERPROFILE%\Documents\TX Text Control 32.0.NET for WPF\VB.NET\Howto\Hyperlinks

Used TX Text Control controls:

  • TXTextControl.WPF.TextControl

Relevant API links:

Step 3: 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 referred 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 Document Targets / Insert... menu item.

Image

Finally use the Links / Insert... 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 dtDocumentTarget = new TXTextControl.DocumentTarget(m_tbxTargetName.Text);
dtDocumentTarget.Deleteable = m_chbxCanBeDeleted.Checked;
m_txTextControl.DocumentTargets.Add(dtDocumentTarget);
Dim dtDocumentTarget As TXTextControl.DocumentTarget = New TXTextControl.DocumentTarget(m_tbxTargetName.Text)
dtDocumentTarget.Deleteable = m_chbxCanBeDeleted.Checked
m_txTextControl.DocumentTargets.Add(dtDocumentTarget)

Inserting Links to Targets

The Insert Hyperlink 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 adding a combo box that replaces the hyperlink text box when the corresponding Document Link radio button is toggled. The combo box is filled with targets by adding all elements from the DocumentTargets collection:

TXTextControl.DocumentTargetCollection colDocumentTargets = m_txTextControl.DocumentTargets;
foreach (TXTextControl.DocumentTarget target in colDocumentTargets) {
        m_cmbxDocumentTargets.Items.Add(new DocumentTargetItem(target));
}
Dim colDocumentTargets = m_txTextControl.DocumentTargets
For Each target As TXTextControl.DocumentTarget In colDocumentTargets
        m_cmbxDocumentTargets.Items.Add(New DocumentTargetItem(target))
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 TextControl_DocumentLinkClicked(object sender, TXTextControl.DocumentLinkEventArgs e) {
        TXTextControl.DocumentTarget dtTarget = e.DocumentLink.DocumentTarget;
        if (dtTarget != null) {
                dtTarget.ScrollTo();
        }
}
Private Sub TextControl_DocumentLinkClicked(ByVal sender As Object, ByVal e As TXTextControl.DocumentLinkEventArgs) Handles m_txTextControl.DocumentLinkClicked
        Dim dtTarget As TXTextControl.DocumentTarget = e.DocumentLink.DocumentTarget
        If dtTarget IsNot Nothing Then
                dtTarget.ScrollTo()
        End If
End Sub

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