Hyperlinks and Bookmarks
- 4 minutes to read
This topic consists of the following sections:
Hyperlinks
Create a Hyperlink
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:
Note
A complete sample project is available at https://github.com/DevExpress-Examples/bookmarks-and-hyperlinks-simple-example-t548777
Document document = richEditControl1.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";
}
Set Hyperlink Options
Use the HyperlinkOptions class properties to complete the following tasks:
- Change modifier flags required to activate a hyperlink (HyperlinkOptions.ModifierKeys);
- Show/hide the hyperlink tooltip (HyperlinkOptions.ShowToolTip);
- Disable/enable automatic URI correction (HyperlinkOptions.EnableUriCorrection).
The code snippet below shows how to specify these properties in code:
Note
A complete sample project is available at https://github.com/DevExpress-Examples/bookmarks-and-hyperlinks-simple-example-t548777
hyperlinkOptions = richEditControl1.Options.Hyperlinks;
hyperlinkOptions.EnableUriCorrection = false;
hyperlinkOptions.ModifierKeys = Keys.Shift;
hyperlinkOptions.ShowToolTip = true;
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.
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. |
Note
A complete sample project is available at https://github.com/DevExpress-Examples/bookmarks-and-hyperlinks-simple-example-t548777
Document document = richEditControl1.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:
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 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:
- 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:
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:
richEditDocumentServer.Options.Bookmarks.DisplayBookmarksInPdfNavigationPane = PdfBookmarkDisplayMode.TocBookmarks;
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.