Hyperlinks and Bookmarks in Rich Text Documents

  • 5 minutes to read

The following members allow you to create a Hyperlink in code:

Member Description
SubDocument.FindAll Searches for every range that contains the given text string.
HyperlinkCollection.Create Creates a new item in the HyperlinkCollection.
Hyperlink.NavigateUri Specifies the URI for the hyperlink to navigate to.
DocumentHyperlink.ToolTip Specifies a tooltip - a text displayed when the mouse hovers over a hyperlink.

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

DXRichEdit_Hyperlinks_Result

View Example

Document document = richEdit.Document;

//Find the specific text string in a document
DocumentRange[] foundRanges = document.FindAll("DevExpress WinForms Rich Text Editor",
SearchOptions.CaseSensitive);
if (foundRanges.Length > 0)
{
    //Create a hyperlink from a found range
    document.Hyperlinks.Create(foundRanges[0]);

    //Set the URI and the tooltip for the created hyperlink
    document.Hyperlinks[0].NavigateUri = "https://www.devexpress.com/Products/NET/Controls/WinForms/Rich_Editor/";
    document.Hyperlinks[0].ToolTip = "WinForms Rich Text Editor";
}

Use the DXRichEditHyperlinkOptions class properties to complete the following tasks:

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

View Example

Handle the RichEditControl.HyperlinkClick event to perform custom actions when a hyperlink is activated. Refer to the How to: Handle the HyperlinkClick Event to Invoke the Custom Form topic for more details.

Note

The hyperlink is a specific kind of a document field, therefore the DXRichEditDocumentCapabilitiesOptions.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.

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

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

Document document = richEditControl.Document;
ReadOnlyHyperlinkCollection hyperlinks = document.Hyperlinks.Get(document.Sections[0].Range);
if (hyperlinks != null)
{
    foreach (Hyperlink hyperlink in hyperlinks)
    {
        document.Hyperlinks.Remove(hyperlink);
    }
}

Bookmarks

Create a Bookmark

The following code snippet creates a Bookmark and a hyperlink which navigates to the created bookmark using API from the table below:

Member Description
SubDocument.BeginUpdate Enables document modification.
BookmarkCollection.Create Creates a bookmark at the given document position.
DocumentHyperlink.Anchor Connects a bookmark with a specific hyperlink.
SubDocument.EndUpdate Finalizes the document update.

View Example

Document document = richEdit.Document;
document.BeginUpdate();
DocumentPosition pos = document.Range.Start;

//Create a bookmark to a given position
document.Bookmarks.Create(document.CreateRange(pos, 1), "Top");

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

The animation below shows the result:

DXRichEdit_Bookmarks_Result

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 DXRichEditBookmarkOptions.ConflictNameResolution property to programmatically process bookmarks with duplicate names which may appear in your document.

Visualize the Bookmark

Use the following properties to highlight bookmarks within the document:

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

DXRichEdit_Bookmarks_HIghlighted

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 DXRichEditBookmarkOptions.DisplayBookmarksInPdfNavigationPane property to one of the DevExpress.XtraRichEdit.PdfBookmarkDisplayMode enumeration values, as shown below:

<dxre:RichEditControl x:Name="richEditControl1">
<dxre:RichEditControl.BookmarkOptions>
    <dxre:DXRichEditBookmarkOptions DisplayBookmarksInPdfNavigationPane="TocBookmarks"/>
</dxre:RichEditControl.BookmarkOptions>
</dxre:RichEditControl>

Use the DXRichEditBookmarkOptions.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(Bookmark) method to delete the bookmark.

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

using DevExpress.XtraRichEdit.API.Native;


using (RichEditDocumentServer wordProcessor = new RichEditDocumentServer())
{
    Document document = wordProcessor.Document;
    ReadOnlyBookmarkCollection bookmarks =
       document.Bookmarks.Get(document.Paragraphs[5].Range);
    if (bookmarks != null)
    {
        foreach (Bookmark bookmark in bookmarks)
        {
            document.Bookmarks.Remove(bookmark);

        }
    }
}

End-users can insert a bookmark or hyperlink in the document using the Links group of the Insert ribbon tab. Refer to the Create a Simple Rich Text Editor topic for details on how to provide the application with the Ribbon Command UI.

DXRichEdit_BookmarksAndHyperlinks_Ribbon

Additionally, RichEditControl provides the following dialogs which allow end-users to manage hyperlinks or bookmarks:

Tip

Set the DXRichEditDocumentCapabilitiesOptions.Hyperlinks or DXRichEditDocumentCapabilitiesOptions.Bookmarks property to DocumentCapability.Disabled to restrict end-users’ use of hyperlinks or bookmarks.

See Also