Using Hypertext Links in TX Text Control .NET for Windows Forms

In this newsletter, we are going to show 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 Hypertext Links overview in the TX Text Control reference manual.

Step 1: Inserting a Hypertext Link

In this first sample program, a hypertext link will be inserted in to a text document. The document is then saved as an HTML file so that it can be displayed in a web browser. This is what the sample program looks like:

To insert a hypertext link, we first need to create a HypertextLinks collection.

' Visual Basic
Private Sub cmdInsertHyperlink_Click(ByVal sender As System.Object, _
    ByVal e As System.EventArgs) Handles cmdInsertHyperlink.Click

    ' Create a HypertextLink object
    Dim MyLink As New TXTextControl.HypertextLink( _
        "TX Text Control Web Site", _
        "https://www.textcontrol.com")

    ' Insert the hyperlink into the document
    TextControl1.HypertextLinks.Add(MyLink)
End Sub

// C#
private void cmdInsertHyperlink_Click(object sender, System.EventArgs e)
{
    // Create a HypertextLink object
    TXTextControl.HypertextLink MyLink =
        new TXTextControl.HypertextLink(
        "TX Text Control Web Site",
        "https://www.textcontrol.com");

    // Insert the hyperlink into the document
    textControl1.HypertextLinks.Add(MyLink);
}

Note that this first sample program does not handle the Click events, so clicking on a hypertext link in the TX Text Control will have no effect. Also, the link does not yet have the typical blue and underlined formatting style. Click events and formatting will be covered in Step 2.

TX Text Control's Save method is used to save the document as an HTML file:

' Visual Basic
Private Sub cmdSaveAs_Click(ByVal sender As System.Object, _
    ByVal e As System.EventArgs) Handles cmdSaveAs.Click
    TextControl1.Save(TXTextControl.StreamType.HTMLFormat)
End Sub

// C#
private void cmdSaveAs_Click(object sender, System.EventArgs e)
{
    textControl1.Save (TXTextControl.StreamType.HTMLFormat);
}

When the HTML file is opened in a web browser, the hypertext link is displayed as specified in your browser's settings.

Clicking on the link will take you to the TX Text Control web site.

Step 2: Adding a Dialog Box for Inserting Hypertext Links

In this second sample program, a dialog box is created which enables you to insert hypertext links in a more convenient way. Additionally, hypertext links which have previously been inserted or loaded from a file, can be edited and modified. Note that, while hypertext links are usually associated with HTML files, they can as well be stored in RTF or Microsoft Word files, or in TX Text Control's proprietary format.

The dialog box contains two text boxes. The first is for the text that represents the hypertext link in the document and the second is for the address, to which the link points.

The same dialog box is used for both, inserting a new and editing an existing hypertext link. Depending on whether the current input position is inside an existing link, this link is modified. Otherwise a new one is inserted.

' Visual Basic
Private Sub mnuInsert_Hyperlink_Click(ByVal sender As System.Object, _
    ByVal e As System.EventArgs) Handles mnuInsert_Hyperlink.Click

    Dim Hyperlinks As New frmHyperlinks
    Hyperlinks.tx = TextControl1
    Hyperlinks.ShowDialog()
    HighlightHyperlinks(TextControl1, mnuView_Hyperlinks.Checked)
End Sub

// C#
private void mnuInsert_Hyperlink_Click(object sender, System.EventArgs e)
{
    frmHyperlinks Hyperlinks = new frmHyperlinks();
    Hyperlinks.tx = textControl1;
    Hyperlinks.ShowDialog();
    HighlightHyperlinks (textControl1, mnuView_Hyperlinks.Checked);
}

When the form is loaded, the text boxes are filled with the text and link information, provided that the current input position is inside a link:

' Visual Basic
Private Sub frmHyperlinks_Load(ByVal sender As System.Object, _
    ByVal e As System.EventArgs) Handles MyBase.Load
    Dim HyperLink As TXTextControl.HypertextLink = tx.HypertextLinks.GetItem()

    If Not (HyperLink Is Nothing) Then
        ' If there is an existing hypertext link at the input position,
        ' copy its text and target to the text boxes on the form.
        txtLinkedText.Text = HyperLink.Text
        txtLinkTo.Text = HyperLink.Target
    Else
        ' If there is no hypertext link at the input position, but
        ' some text has been selected, then copy this text to the
        ' Linked Text text box.
        If (tx.Selection.Length > 0) Then
            txtLinkedText.Text = tx.Selection.Text
        End If
    End If
End Sub

// C#
private void frmHyperlinks_Load(object sender, System.EventArgs e)
{
    TXTextControl.HypertextLink HyperLink = tx.HypertextLinks.GetItem();

    if (HyperLink != null)
    {
        // If there is an existing hypertext link at the input position,
        // copy its text and target to the text boxes on the form.
        txtLinkedText.Text = HyperLink.Text;
        txtLinkTo.Text = HyperLink.Target;
    }
    else
    {
        // If there is no hypertext link at the input position, but
        // some text has been selected, then copy this text to the
        // Linked Text text box.
        if  (tx.Selection.Length > 0)
            txtLinkedText.Text = tx.Selection.Text;
    }
}

The user can then change the displayed information. On clicking the OK button, the information is transfered to the document by either inserting a new link or modifying the existing one:

' Visual Basic
Private Sub cmdOK_Click(ByVal sender As System.Object, _
    ByVal e As System.EventArgs) Handles cmdOK.Click

    Dim HyperLink As TXTextControl.HypertextLink = tx.HypertextLinks.GetItem()

    If HyperLink Is Nothing Then
        ' Insert a new link
        Dim NewLink As New TXTextControl.HypertextLink( _
            txtLinkedText.Text, txtLinkTo.Text)
        tx.HypertextLinks.Add(NewLink)
    Else
        ' Update an existing link
        HyperLink.Text = txtLinkedText.Text
        HyperLink.Target = txtLinkTo.Text
    End If

    Close()
End Sub

// C#
private void cmdOK_Click(object sender, System.EventArgs e)
{
    TXTextControl.HypertextLink HyperLink = tx.HypertextLinks.GetItem();

    if (HyperLink == null)
    {
        // Insert a new link
        TXTextControl.HypertextLink NewLink =
            new TXTextControl.HypertextLink(
            txtLinkedText.Text , txtLinkTo.Text);
        tx.HypertextLinks.Add(NewLink);
    }
    else
    {
        // Update an existing link
        HyperLink.Text = txtLinkedText.Text;
        HyperLink.Target = txtLinkTo.Text;
    }

    Close();
}

Finally, there is a menu item to switch the character format of the hyperlink's text to blue colored and underlined style. The menu item calls the function HighlightHyperlinks, which is not a TX Text Control method, but part of the sample program. It changes each element of TX Text Control's HyperLinks collection to the desired display style.

' Visual Basic
Private Sub HighlightHyperlinks(ByVal tx As TXTextControl.TextControl, _
    ByVal Highlight As Boolean)
    Dim PreviousStart As Integer = tx.Selection.Start
    Dim PreviousLength As Integer = tx.Selection.Length

    For Each Link As TXTextControl.HypertextLink In tx.HypertextLinks
        tx.Selection.Start = Link.Start - 1
        tx.Selection.Length = Link.Length
        If Highlight Then
            tx.Selection.ForeColor = Color.Blue
            tx.Selection.Underline = TXTextControl.FontUnderlineStyle.Single
        Else
            tx.Selection.ForeColor = Color.Black
            tx.Selection.Underline = TXTextControl.FontUnderlineStyle.None
        End If
        tx.Selection.Start = PreviousStart
        tx.Selection.Length = PreviousLength
    Next
End Sub

// C#
void HighlightHyperlinks(TXTextControl.TextControl tx, bool bHighlight)
{
    int PreviousStart = tx.Selection.Start, PreviousLength = tx.Selection.Length;

    foreach (TXTextControl.HypertextLink Link in tx.HypertextLinks)
    {
        tx.Selection.Start = Link.Start-1;
        tx.Selection.Length = Link.Length;
        if (bHighlight)
        {
            tx.Selection.ForeColor = Color.Blue;
            tx.Selection.Underline = TXTextControl.FontUnderlineStyle.Single;
        }
        else
        {
            tx.Selection.ForeColor = Color.Black;
            tx.Selection.Underline = TXTextControl.FontUnderlineStyle.None;
        }
    }
    tx.Selection.Start = PreviousStart;
    tx.Selection.Length = PreviousLength;
}

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 where 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 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 DocumentTargets Collection.

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

' Visual Basic
Dim Target As New TXTextControl.DocumentTarget(InsertTarget.TargetName)
TextControl1.DocumentTargets.Add(Target)

// C#
TXTextControl.DocumentTarget Target =
    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 let 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 TX Text Control's DocumentTargets collection:

' Visual Basic
For Each Target As TXTextControl.DocumentTarget In tx.DocumentTargets
    cboLinkTo.Items.Add("#" + Target.TargetName)
Next

// C#
foreach (TXTextControl.DocumentTarget Target in tx.DocumentTargets)
    cboLinkTo.Items.Add("#" + Target.TargetName);

Jumping to a Target

When a document link is clicked, text should automatically be scrolled so that the text part containing the link's target becomes visible. This is done by responding to TX Text Control's TextField.

' Visual Basic
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

// C#
private void textControl1_DocumentLinkClicked(object sender, _
    TXTextControl.DocumentLinkEventArgs e)
{
    e.DocumentLink.DocumentTarget.ScrollTo();
}

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, TX Text Control will scroll it out of view. However, this is 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

Unlike HTML editors, TX Text Control does not display an icon 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.

Best regards

The Newsletter Team