Hyperlinks and Bookmarks

• Dec 21, 2021
• 6 minutes to read

Hyperlinks

The HyperlinkCollection contains all document hyperlinks. Use the SubDocument.Hyperlinks property to access a specific hyperlink by its index. Call the ReadOnlyHyperlinkCollection.Get method to retrieve the hyperlink related to the specified range.

Create a Hyperlink

Call the HyperlinkCollection.Create method to create a new Hyperlink.

The code snippet below finds a specific range in the document and converts it to a hyperlink with the specified URI and tooltip:

C#

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;

using (var wordProcessor = new RichEditDocumentServer())
{
  wordProcessor.LoadDocument("Documents//Document.docx");
  Document document = wordProcessor.Document;

  // Find a specific text string
  DocumentRange[] foundRanges =
          document.FindAll("DevExpress WinForms Rich Text Editor",
  SearchOptions.CaseSensitive);

  if (foundRanges.Length > 0)
  {
      // Convert the found range to a hyperlink
      Hyperlink hyperlink =  document.Hyperlinks.Create(foundRanges[0]);

      // Specify the URI and the tooltip
      hyperlink.NavigateUri =
           "https://www.devexpress.com/Products/NET/Controls/WinForms/Rich_Editor/";
      hyperlink.ToolTip = "WinForms Rich Text Editor";
  }
}

VB

Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native

Using wordProcessor = New RichEditDocumentServer()
  wordProcessor.LoadDocument("Documents//Document.docx")
  Dim document As Document = wordProcessor.Document

  ' Find a specific text string
  Dim foundRanges() As DocumentRange =
       document.FindAll("DevExpress WinForms Rich Text Editor", SearchOptions.CaseSensitive)

  If foundRanges.Length > 0 Then
      ' Convert the found range to a hyperlink
      Dim hyperlink As Hyperlink = document.Hyperlinks.Create(foundRanges(0))

      ' Specify the URI and the tooltip
      hyperlink.NavigateUri =
           "https://www.devexpress.com/Products/NET/Controls/WinForms/Rich_Editor/"
      hyperlink.ToolTip = "WinForms Rich Text Editor"
  End If
End Using

Tip

You can use the Create method to convert static URIs to hyperlinks. Refer to the following article for a code sample:

Read Tutorial: How to: Convert a Static URI to a Hyperlink

Set Hyperlink Options

Use the HyperlinkOptions class properties to complete the following tasks:

• Change modifier flags required to activate a hyperlink (ModifierKeys);
• Show/hide a hyperlink tooltip (ShowToolTip);
• Disable/enable automatic URI correction (EnableUriCorrection).

The code snippet below shows how to specify these properties in code:

C#

using XtraRichEdit.API.Native;

using (var wordProcessor = new RichEditDocumentServer())
{
    //...
    hyperlinkOptions = wordProcessor.Options.Hyperlinks;

    hyperlinkOptions.EnableUriCorrection = false;
    hyperlinkOptions.ModifierKeys = Keys.Shift;
    hyperlinkOptions.ShowToolTip = true;
}

VB

Imports XtraRichEdit.API.Native

Using wordProcessor = New RichEditDocumentServer()
    '...
    hyperlinkOptions = wordProcessor.Options.Hyperlinks

    hyperlinkOptions.EnableUriCorrection = False
    hyperlinkOptions.ModifierKeys = Keys.Shift
    hyperlinkOptions.ShowToolTip = True
End Using

Note

The HYPERLINK field represents hyperlinks in the RichEditDocumentServer, therefore the DocumentCapabilitiesOptions.Fields property affects the hyperlink loading process when importing the document. Set the RichEditControlCompatibility.LoadHyperlinkAsField property to false before calling the InitializeComponent method to correct this behavior and allow loading hyperlinks when loading fields are disabled.

Remove a Hyperlink

Call the HyperlinkCollection.Remove to delete the hyperlink. The HyperlinkCollection.RemoveAt method deletes the hyperlink at the specified index in the collection.

The code sample below locates and removes all hyperlinks in the first section:

C#

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;

using (var wordProcessor = new RichEditDocumentServer())
{
    // Load a document
    wordProcessor.LoadDocument("Documents//Document.docx");
    Document document = wordProcessor.Document;

    // Obtain all hyperlinks in the first section
    var hyperlinks = document.Hyperlinks.Get(document.Sections[0].Range);
    if (hyperlinks != null)
    {
        // Remove all hyperlinks
        foreach (Hyperlink hyperlink in hyperlinks)
        {
            document.Hyperlinks.Remove(hyperlink);
        }
    }
}

VB.NET

Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native

Using wordProcessor = New RichEditDocumentServer()
    ' Load a document
    wordProcessor.LoadDocument("Documents//Document.docx")
    Dim document As Document = wordProcessor.Document

    ' Obtain all hyperlinks in the first section
    Dim hyperlinks = document.Hyperlinks.Get(document.Sections(0).Range)
    If hyperlinks IsNot Nothing Then
        ' Remove all hyperlinks
        For Each hyperlink As Hyperlink In hyperlinks
            document.Hyperlinks.Remove(hyperlink)
        Next hyperlink
    End If
End Using

Bookmarks

The BookmarkCollection contains all document bookmarks. Use the SubDocument.Bookmarks property to access a specific bookmark by its index. Call the ReadOnlyBookmarkCollection.Get method to retrieve the bookmark related to the specified range.

Create a Bookmark

The following code snippet creates a Bookmark and a hyperlink associated with this bookmark:

C#

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;

using (var wordProcessor = new RichEditDocumentServer())
{
    wordProcessor.LoadDocument("Documents//Document.docx");
    Document document = wordProcessor.Document;

    // Create a bookmark at the document start
    DocumentRange start = document.CreateRange(document.Range.Start, 1);
    document.Bookmarks.Create(start, "Top");

    // Insert the hyperlink anchored to the created bookmark
    DocumentRange[] foundRanges = document.FindAll("To the Top", SearchOptions.CaseSensitive);
    if (foundRanges.Length > 0)
    {
        Hyperlink hyperlink = document.Hyperlinks.Create(foundRanges[0]);
        hyperlink.Anchor = "Top";
    }
}

VB

Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native

Using wordProcessor = New RichEditDocumentServer()
    wordProcessor.LoadDocument("Documents//Document.docx")
    Dim document As Document = wordProcessor.Document

    ' Create a bookmark at the document start
    Dim start As DocumentRange = document.CreateRange(document.Range.Start, 1)
    document.Bookmarks.Create(start, "Top")

    ' Insert the hyperlink anchored to the created bookmark
    Dim foundRanges() As DocumentRange = document.FindAll("To the Top", SearchOptions.CaseSensitive)
    If foundRanges.Length > 0 Then
        Dim hyperlink As Hyperlink = document.Hyperlinks.Create(foundRanges(0))
        hyperlink.Anchor = "Top"
    End If
End Using

Note

If a new bookmark name duplicates the existing one, an InvalidOperationException exception is thrown with the message obtained from the XtraRichEditStringId.Msg_DuplicateBookmark resource string that reads “Bookmark with that name already exists in the document”. Use the BookmarkOptions.ConflictNameResolution property to process bookmarks with duplicate names.

Visualize the Bookmark

Use the following properties to highlight bookmarks:

• BookmarkOptions.Visibility - to enable/disable bookmark highlighting;
• BookmarkOptions.Color - to set the highlighting color.

With these properties specified, the bookmarks are displayed the following way:

C#

using DevExpress.XtraRichEdit;
using System.Drawing;

using (var wordProcessor = new RichEditDocumentServer())
{
  //...
  BookmarkOptions bookmarkOptions = wordProcessor.Options.Bookmarks;
  bookmarkOptions.Visibility = RichEditBookmarkVisibility.Visible;
  bookmarkOptions.Color = Color.Sienna;
}

VB.NET

Imports DevExpress.XtraRichEdit
Imports System.Drawing

Using wordProcessor = New RichEditDocumentServer()
  '...
  Dim bookmarkOptions As BookmarkOptions = wordProcessor.Options.Bookmarks
  bookmarkOptions.Visibility = RichEditBookmarkVisibility.Visible
  bookmarkOptions.Color = Color.Sienna
End Using

Export Bookmarks to the PDF format

You can specify what bookmarks can be displayed in the Bookmarks panel when you export the document to PDF format. Set the BookmarkOptions.DisplayBookmarksInPdfNavigationPane property to one of the DevExpress.XtraRichEdit.PdfBookmarkDisplayMode enumeration values, as shown below:

C#

using DevExpress.XtraRichEdit;

using (var wordProcessor = new RichEditDocumentServer())
{
    //...
    BookmarkOptions bookmarkOptions = wordProcessor.Options.Bookmarks;
    bookmarkOptions.DisplayBookmarksInPdfNavigationPane =
         PdfBookmarkDisplayMode.TocBookmarks;
}

VB.NET

Imports DevExpress.XtraRichEdit

Using wordProcessor = New RichEditDocumentServer()
    '...
    Dim bookmarkOptions As BookmarkOptions = wordProcessor.Options.Bookmarks
    bookmarkOptions.DisplayBookmarksInPdfNavigationPane =
         PdfBookmarkDisplayMode.TocBookmarks
End Using

Use the BookmarkOptions.DisplayUnreferencedPdfBookmarks property to determine whether to show bookmarks without references (i.e., without hyperlinks anchored to these bookmarks) in the Bookmarks navigation pane. The DisplayBookmarksInPdfNavigationPane property set PdfBookmarkDisplayMode.None controls the unreferenced bookmarks when the DisplayUnreferencedPdfBookmarks property is set to true.

Remove a Bookmark

Utilize the BookmarkCollection.Remove method to delete the bookmark.

The code sample below shows how to locate and remove bookmarks in the 6th paragraph:

C#

using DevExpress.XtraRichEdit.API.Native;

using (var wordProcessor = new RichEditDocumentServer())
{
  wordProcessor.LoadDocument("Documents//Document.docx");
  Document document = wordProcessor.Document;

  var bookmarks =
     document.Bookmarks.Get(document.Paragraphs[5].Range);
  if (bookmarks != null)
  {
      foreach (Bookmark bookmark in bookmarks)
      {
        document.Bookmarks.Remove(bookmark);
      }
  }
}

VB.NET

Imports DevExpress.XtraRichEdit.API.Native

Using wordProcessor As New RichEditDocumentServer()
  Dim document As Document = wordProcessor.Document
  Dim bookmarks = document.Bookmarks.Get(document.Paragraphs(5).Range)
  If bookmarks IsNot Nothing Then
    For Each bookmark As Bookmark In bookmarks
        document.Bookmarks.Remove(bookmark)
    Next bookmark
  End If
End Using