Hypertext Links

Hypertext links in a TXTextControl document are marked text fields of a special type, and so are the targets they jump to. In four steps, a Visual Basic 6 program grows from a single inserted link to a small hypertext editor: it inserts and edits links in a dialog box, adds targets, and responds to the events that TX Text Control fires when the user clicks a link, including jumps to targets in other files.

The source code of the steps is in the subfolders Step1 to Step4 of the Samples\vb6\Hyperlnk sample source directory. Each step extends the program of the one before.

How Hypertext Links Work

A link is inserted with FieldInsert like any marked text field. The FieldType property then makes it a link, and FieldTypeData holds the place it points to:

The positions that internal links point to are called targets. HTML editors call them anchors, word processors bookmarks. Hypertext links are usually associated with HTML files, but they can also be stored in RTF and Microsoft Word files and in the proprietary format of TX Text Control.

Insert a Hypertext Link

The first program inserts a hypertext link into a document and saves the document as an HTML file that you can view in a browser.

The link is a field inserted with FieldInsert, whose type is then set with FieldType:

TXTextControl1.FieldInsert "Text Control Web Site"
TXTextControl1.FieldType(TXTextControl1.FieldCurrent) = _
         txFieldExternalLink

FieldTypeData stores the target the link points to:

TXTextControl1.FieldTypeData(TXTextControl1.FieldCurrent)=_
         "http://www.textcontrol.com"

The following line saves the document with the new link as an HTML file in the sample folder:

TXTextControl1.Save App.Path & "\step1.html", ,4 , 0

The third parameter of Save, 4, is the HTML format. When you open the file in a web browser, the browser displays the link as its settings specify. Clicking the link takes you to the Text Control web site.

The program has no code for the click events yet, so clicking the link inside TXTextControl has no effect. The link is also neither underlined nor colored.

Add a Dialog Box for Hypertext Links

The second program adds a dialog box in which the user inserts hypertext links more conveniently. It also edits and modifies links that were inserted before or loaded from a file.

The dialog box has two text boxes: the first holds the text that represents the link in the document, the second the address the link points to. In step 1, the text was "Text Control Web Site" and the address "http://www.textcontrol.com".

The same dialog box inserts new links and edits existing ones. If the current input position is inside an existing link, the dialog box modifies that link. Otherwise, it inserts a new one.

The properties tx and bShowHyperlinks of the dialog form pass it a reference to the TXTextControl and the information about how to display hypertext links:

Public Sub do_mnuInsert_Hyperlink_Click(tx As _
            TXTextControl, bShowHyperlinks As Boolean)
   Set frmHyperlink.tx = tx
   frmHyperlink.bShowHyperlinks = _
      (mnuView_Hyperlinks.Checked = True)
   frmHyperlink.Show 1
End Sub

When the form is loaded and the current input position is inside an existing link, the text boxes are filled with the link's text and address. Otherwise, the selected text becomes the linked text:

Private Sub Form_Load()
   If CaretInsideHyperlink(tx) <> 0 Then
      txtLinkedText = tx.FieldText
      txtLinkTarget = tx.FieldTypeData(tx.FieldCurrent)
   Else
      txtLinkedText = tx.SelText
   End If
End Sub

The user can change the displayed information. When the user clicks OK, the program transfers it to the document, either by modifying the existing link or by inserting a new one:

If tx.FieldAtInputPos <> 0 Then
   ' editing an existing hypertext link
   tx.FieldText = txtLinkedText
   tx.FieldType(tx.FieldCurrent) = txFieldExternalLink
   tx.FieldTypeData(tx.FieldCurrent) = txtLinkTarget
Else
   ' insert new hypertext link
   tx.FieldInsert txtLinkedText
   tx.FieldType(tx.FieldCurrent) = txFieldExternalLink
   tx.FieldTypeData(tx.FieldCurrent) = txtLinkTarget
   HighlightHyperlinks tx, bShowHyperlinks
End If

The code works as follows:

• FieldAtInputPos is not 0 when the input position is in a field, so the existing link gets the new text through FieldText, and its type and address are set again.
• Otherwise, FieldInsert inserts a new field, which becomes an external link with the address from the dialog box.

A menu item switches the character format of the link texts to blue and underlined. It calls the function HighlightHyperlinks, which is defined in the file HyperlinkFunctions.bas.

Add Targets

Steps 1 and 2 only handle references to external resources, the addresses of web pages or files. The third program adds internal links, which point to targets in the same document. To try it, type some text, add some targets with the Insert / Target... menu item, and then add links to them with Insert / Hypertext Link....

Insert a Target

The TargetInsert method inserts a target:

Dim targetName As String
targetName = InputBox("Target name:", "Insert target")
If targetName <> "" Then
    TXTextControl1.TargetInsert targetName, True
End If

A target needs only one text box for its name, so a plain InputBox statement is enough. The second parameter of TargetInsert, True, lets the user delete the target while editing the document.

Link to a Target

To insert links to these targets, the program extends the Hypertext Link dialog box with a list box that shows the names of all targets in the document. The TargetNext method fills it:

Dim targetId As Integer
List1.Clear
targetId = tx.TargetNext(0)
While targetId <> 0
    List1.AddItem tx.targetName(targetId)
    targetId = tx.TargetNext(targetId)
Wend

TargetNext returns the identifier of the next target, the first one for 0 and 0 after the last one, and TargetName returns its name. When the user selects a target, the Link To box is filled with the target's name.

After the user types the text of the link and clicks OK, the link is inserted. An internal link is inserted the same way as the external link of step 1, but FieldType is set to txFieldInternalLink and FieldTypeData to the name of the target.

Jump to a Target

With internal links and targets in place, the program has to carry out the jump. When the user clicks a marked text field that represents a hypertext link, TX Text Control fires a FieldLinkClicked event. The TargetGoto method uses the information the event provides to jump to the target:

Private Sub TXTextControl1_FieldLinkClicked( _
      ByVal FieldId As Integer, _
      ByVal FieldType As Integer, _
      TypeData As String)
   If FieldType = txFieldInternalLink Then
      TXTextControl1.TargetGoto TypeData
   End If
End Sub

TargetGoto handles targets in the same file. Links to external targets need different treatment: when FieldLinkClicked occurs and its FieldType parameter says that the link is external, what to do depends on the type of application. External links can point to files on the local hard disk or to addresses on the internet, for example.

The events only have to be handled to make the links work while the text is edited in TXTextControl. When the text is saved to a file and displayed in a browser, the links work as the browser supports them.

Add Jumps to External Targets

The fourth program adds jumps to other documents and to targets in these documents.

Choose a File and Its Targets

The program extends the Hypertext Link dialog box again, this time to choose an external file. A Choose File... button on the form opens a common dialog.

After the user chooses a file, the text box displays its name and the program searches the file for internal targets:

Private Sub CheckFileForTargets(file As String)
   tx(1).LoadSaveAttribute(txEnableLinks) = True
   tx(1).Load file, 0, 4
   FillListboxWithTargets (1)
   optSelFile.Value = True
   loadedFile = file
End Sub

The program loads the file into a second, invisible TXTextControl and then lists all of its targets in the same way as in step 3.

Jump to a Target in Another File

To jump to an external link, the program extends the FieldLinkClicked handler of step 3. The following code doesn't handle jumps to internet addresses; it only jumps to targets in other files. TX Text Control separates the name of a file from the name of a target with the # character. The code splits the two, loads the file with the Load method and jumps to the target with TargetGoto:

ElseIf FieldType = txFieldExternalLink Then
   'This sample does not feature links to www sites,
   'so exit sub
   If Left(TypeData, 7) = "http://" Then
      Exit Sub
   End If
   TXTextControl1.LoadSaveAttribute(txEnableLinks) = True
   pos = InStr(TypeData, "#")
   'File name includes an internal link
   If pos > 0 Then
      'Ask the user to save changes, if any
      If bDocDirty Then
      ret = MsgBox("Save changes?", vbYesNoCancel, _
               "Question")
         If ret = vbYes Then
            mnuFile_SaveAs_Click
         ElseIf ret = vbCancel Then
            Exit Sub
         End If
   End If
      'Extract file name & path from full path
   str = Left(TypeData, pos - 1)
      TXTextControl1.Load str, 0, 4
      'Extract file position from full path
      str = Mid(TypeData, pos + 1)
      TXTextControl1.TargetGoto str
   Else
      'File name doesn't include an internal link
      TXTextControl1.Load TypeData, 0, 4
   End If
End If

The code works as follows:

• An address that starts with http:// ends the procedure.
• If the address contains #, the program asks the user to save changes, if there are any, loads the file named before the # and jumps to the target named after it.
• An address without a target only loads the file. The third parameter of Load, 4, is the HTML format.

Load and Save Documents With Hypertext Links

When an HTML, RTF or Microsoft Word document is loaded, TX Text Control has to convert the hypertext links it contains to marked text fields as described above. To make it do so, set LoadSaveAttribute with txEnableLinks to True before calling Load, as both procedures of step 4 do. Otherwise, hypertext links and target fields are not converted.

When a document is saved, marked text fields that represent hypertext links are always converted to the appropriate format. In the proprietary format of TX Text Control, you don't need to set LoadSaveAttribute.

Next Steps

• Special Types of Marked Text Fields: all field types and the members for hypertext links.
• Link Targets and Bookmarks: the target properties and methods that replaced link target fields.
• Hypertext Links: the programming category with every member for links and targets.
• Using Marked Text Fields in Visual Basic: insert fields, respond to clicks and build bookmarks.