TX Words: Open Hyperlink

Hyperlinks in a document can refer to a URL as well as to different areas in the same document or another file. This sample shows how to create and handle a clicked hyperlink depending on its target: Open the link in a browser, if it is a URL, scroll to the document location, if it is a document target, or initializing a new instance of an application to open a linked file.

The source code for this example is contained in the following directories:

  • %USERPROFILE%\Documents\TX Text Control 32.0.NET for Windows Forms\CSharp\TX Words\Open Hyperlink
  • %USERPROFILE%\Documents\TX Text Control 32.0.NET for Windows Forms\VB.NET\TX Words\Open Hyperlink

Using the Sample

By running this sample, a document is loaded that contains three hyperlinks. When clicking the first one, the corresponding URL is opened by the system's default browser. The second one scrolls to the specified document target. The third one opens a linked document with a new instance of the application.

Image

Both a hyperlink to a URL and a hyperlink to a document target can be created and edited by using the corresponding dialog when clicking the Hyperlink button's Insert Hyperlink... respectively Edit Hyperlink... drop down menu button. A document target can be inserted, edited or deleted by clicking the corresponding Bookmark button's drop down menu item.

Image

The Code Behind

When clicking a hyperlink that refers to a document target, the TextControl.DocumentLinkClicked event is fired. A handler that is connected to this event invokes the ScrollTo method of the DocumentTarget that is provided by the event args' DocumentLink property.

private void TextControl_DocumentLinkClicked(object sender, DocumentLinkEventArgs e) {
        DocumentTarget dtTarget = e.DocumentLink.DocumentTarget;
        if (dtTarget != null &&
                // TextControl scrolls automatically to TOC targets
                // when pressing the Ctrl key and clicking the link.
                dtTarget.AutoGenerationType!=AutoGenerationType.TableOfContents) {
                dtTarget.ScrollTo();
        }
}
Private Sub TextControl_DocumentLinkClicked(ByVal sender As Object, ByVal e As DocumentLinkEventArgs)
        Dim dtTarget As DocumentTarget = e.DocumentLink.DocumentTarget
        ' TextControl scrolls automatically to TOC targets when pressing the Ctrl key and clicking the link.
        If dtTarget IsNot Nothing AndAlso dtTarget.AutoGenerationType <> AutoGenerationType.TableOfContents Then
                dtTarget.ScrollTo()
        End If
End Sub

If the clicked hyperlink refers to a file or a URL, the TextControl.HypertextLinkClicked event is fired. The corresponding handler handles the corresponding hypertext link target by checking in a first step whether it is a file or not.

private void OpenHyperlink(string hypertextLinkTarget) {
        if (!string.IsNullOrEmpty(hypertextLinkTarget)) {
                try {
                        // Create a Uri to determine the type of the linked target.
                        Uri uriTarget;
                        if ((Uri.TryCreate(hypertextLinkTarget, UriKind.RelativeOrAbsolute, out uriTarget) && uriTarget.IsAbsoluteUri) ||
                                Uri.TryCreate(Path.GetFullPath(hypertextLinkTarget), UriKind.RelativeOrAbsolute, out uriTarget) // Handle relative file paths
                                ) {
                                // Check whether the specified Uri is a file
                                if (uriTarget.IsFile) {
                                        // Open the file by a type-corresponding application.
                                        OpenFile(uriTarget);
                                }
                                else {
                                        // If it is not a file, the local system decides how to open the linked target.
                                        Process.Start(uriTarget.AbsoluteUri);
                                }
                        }
                        return;
                } catch { }
        }
        // Inform the user if something went wrong.
        MessageBox.Show(this,
                string.Format(Properties.Resources.MessageBox_OpenHyperlink_CouldNotOpenLink_Text, hypertextLinkTarget),
                Properties.Resources.MessageBox_OpenHyperlink_CouldNotOpenLink_Caption, MessageBoxButtons.OK, MessageBoxIcon.Error);
}
Private Sub OpenHyperlink(ByVal hyperlinkTarget As String)
        If Not String.IsNullOrEmpty(hyperlinkTarget) Then
                Try
                        ' Create a Uri to determine the type of the linked target.
                        Dim uriTarget As Uri
                        If Uri.TryCreate(hyperlinkTarget, UriKind.RelativeOrAbsolute, uriTarget) AndAlso uriTarget.IsAbsoluteUri OrElse Uri.TryCreate(Path.GetFullPath(hyperlinkTarget), UriKind.RelativeOrAbsolute, uriTarget) Then ' Handle relative file paths
                                ' Check whether the specified Uri is a file
                                If uriTarget.IsFile Then
                                        ' Open the file by a type-corresponding application.
                                        OpenFile(uriTarget)
                                Else
                                        ' If it is not a file, the local system decides how to open the linked target.
                                        Process.Start(uriTarget.AbsoluteUri)
                                End If
                        End If
                        Return
                Catch
                End Try
        End If
        ' Inform the user if something went wrong.
        MessageBox.Show(Me, String.Format(My.Resources.MessageBox_OpenHyperlink_CouldNotOpenLink_Text, hyperlinkTarget), My.Resources.MessageBox_OpenHyperlink_CouldNotOpenLink_Caption, MessageBoxButtons.OK, MessageBoxIcon.Error)
End Sub

If it is not a file, the method passes the link to the system that opens the associated application. In general, if it is identified as a URL, the link is opened by the system's default browser.

In case the hyperlink refers to a file, it is checked whether it can be loaded by TextControl. If the format is not supported, the path is passed to the Process.Start method to be handled by the system's associated application.

private void OpenFile(Uri fileTarget) {
        string strFileToOpen = fileTarget.LocalPath;

        // Remove internal links inside the target document.
        int iPos = strFileToOpen.IndexOf("#");
        if (iPos != -1) {
                strFileToOpen = strFileToOpen.Substring(0, iPos);
        }

        // Check whether the specified file exists.
        if (!File.Exists(strFileToOpen)) {
                MessageBox.Show(this, string.Format(Properties.Resources.MessageBox_OpenHyperlink_FileDoesNotExist_Text, strFileToOpen),
                        Properties.Resources.MessageBox_OpenHyperlink_FileDoesNotExist_Caption, MessageBoxButtons.OK, MessageBoxIcon.Error);
        }
        else {
                // If the file format is supported by TX Text Control...
                if (IsSupportedDocumentFormat(strFileToOpen)) {
                        // ... open the file with a new instance of this application.
                        OpenFileInNewInstance(strFileToOpen);
                }
                else {
                        // Otherwise open the file with the default application that
                        // is determined for the corresponding format.
                        Process.Start(strFileToOpen);
                }
        }
}
Private Sub OpenFile(ByVal fileTarget As Uri)
        Dim strFileToOpen As String = fileTarget.LocalPath

        ' Remove internal links inside the target document.
        Dim iPos As Integer = strFileToOpen.IndexOf("#")
        If iPos <> -1 Then
                strFileToOpen = strFileToOpen.Substring(0, iPos)
        End If

        ' Check whether the specified file exists.
        If Not File.Exists(strFileToOpen) Then
                MessageBox.Show(Me, String.Format(My.Resources.MessageBox_OpenHyperlink_FileDoesNotExist_Text, strFileToOpen), My.Resources.MessageBox_OpenHyperlink_FileDoesNotExist_Caption, MessageBoxButtons.OK, MessageBoxIcon.Error)
        Else
                ' If the file format is supported by TX Text Control...
                If IsSupportedDocumentFormat(strFileToOpen) Then
                        ' ... open the file with a new instance of this application.
                        OpenFileInNewInstance(strFileToOpen)
                Else
                        ' Otherwise open the file with the default application that
                        ' is determined for the corresponding format.
                        Process.Start(strFileToOpen)
                End If
        End If
End Sub

Otherwise, the file format is supported by TextControl. The path is set as an Arguments string to the Process.StartInfo property before the application is restarted...

private void OpenFileInNewInstance(string filePath) {
        // Get running demo's exe path
        string strExePath = Assembly.GetEntryAssembly().Location;

        // Start new demo instance
        Process pcPocess = new Process();
        pcPocess.StartInfo.FileName = strExePath;
        pcPocess.StartInfo.Arguments = "\"" + filePath + "\"";
        pcPocess.Start();
}
Private Sub OpenFileInNewInstance(ByVal filePath As String)
        ' Get running demo's exe path
        Dim strExePath As String = Assembly.GetEntryAssembly().Location

        ' Start new demo instance
        Dim pcPocess As Process = New Process()
        pcPocess.StartInfo.FileName = strExePath
        pcPocess.StartInfo.Arguments = """" & filePath & """"
        pcPocess.Start()
End Sub

... with the referenced file.

private void MainWindow_OpenHyperlink_Load(object sender, EventArgs e) {
        // Load file provided as a command line argument
        string[] rstrArgs = Environment.GetCommandLineArgs();
        if (rstrArgs.Length > 1) {
                string strFile = rstrArgs[1];
                if (File.Exists(strFile)) {
                        Open(strFile);
                }
        }
}
Private Sub MainWindow_OpenHyperlink_Load(ByVal sender As Object, ByVal e As EventArgs)
        ' Load file provided as a command line argument
        Dim rstrArgs As String() = Environment.GetCommandLineArgs()
        If rstrArgs.Length > 1 Then
                Dim strFile As String = rstrArgs(1)
                If File.Exists(strFile) Then
                        Open(strFile)
                End If
        End If
End Sub