windowsforms-7397-controls-and-libraries-rich-text-editor-rich-edit-control-document-hyperlinks-and-bookmarks.md
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. |
| Hyperlink.ToolTip | Specifies a tooltip - a text displayed when the mouse hovers over a hyperlink. |
The following code snippet finds a specific range in the document and converts it to a hyperlink with a given URI and a tooltip:
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";
}
Dim document As Document = richEditControl1.Document
'Find the specific text string in a document
Dim foundRanges() As DocumentRange = document.FindAll("DevExpress WinForms Rich Text Editor", SearchOptions.CaseSensitive)
If foundRanges.Length > 0 Then
'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"
End If
Use the HyperlinkOptions class properties to complete the following tasks:
The following code snippet specifies these properties in code:
hyperlinkOptions = richEditControl1.Options.Hyperlinks;
hyperlinkOptions.EnableUriCorrection = false;
hyperlinkOptions.ModifierKeys = Keys.Shift;
hyperlinkOptions.ShowToolTip = true;
hyperlinkOptions = richEditControl1.Options.Hyperlinks
hyperlinkOptions.EnableUriCorrection = False
hyperlinkOptions.ModifierKeys = Keys.Shift
hyperlinkOptions.ShowToolTip = True
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 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 load hyperlinks if field load operations 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 following code snippet 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);
}
}
Dim document As Document = wordProcessor.Document
Dim hyperlinks As ReadOnlyHyperlinkCollection = document.Hyperlinks.Get(document.Sections(0).Range)
If hyperlinks IsNot Nothing Then
For Each hyperlink As Hyperlink In hyperlinks
document.Hyperlinks.Remove(hyperlink)
Next hyperlink
End If
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. |
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();
Dim document As Document = richEditControl1.Document
document.BeginUpdate()
Dim pos As DocumentPosition = 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:
Dim foundRanges() As DocumentRange = document.FindAll("To the Top", SearchOptions.CaseSensitive)
If foundRanges.Length > 0 Then
document.Hyperlinks.Create(foundRanges(0))
document.Hyperlinks(1).Anchor = "Top"
End If
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.
Use the following properties to highlight bookmarks within the document:
BookmarkOptions.Visibility - to enable/disable bookmark highlighting;
BookmarkOptions.Color - to set the highlighting color.
BookmarkOptions bookmarkOptions;
bookmarkOptions = richEditControl1.Options.Bookmarks;
bookmarkOptions.Visibility = RichEditBookmarkVisibility.Visible;
bookmarkOptions.Color = Color.Sienna;
bookmarkOptions = richEditControl1.Options.Bookmarks
bookmarkOptions.Visibility = RichEditBookmarkVisibility.Visible
bookmarkOptions.Color = Color.Sienna
With these properties specified, the bookmarks are displayed the following way:
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:
richEditControl.Options.Bookmarks.DisplayBookmarksInPdfNavigationPane = PdfBookmarkDisplayMode.TocBookmarks;
richEditControl.Options.Bookmarks.DisplayBookmarksInPdfNavigationPane = PdfBookmarkDisplayMode.TocBookmarks
Use the BookmarkOptions.DisplayUnreferencedPdfBookmarks property to determine whether to show bookmarks without references (that is, 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.
Utilize the BookmarkCollection.Remove(Bookmark) method to delete the bookmark.
The following code snippet locates 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);
}
}
}
Imports DevExpress.XtraRichEdit.API.Native
Using wordProcessor As New RichEditDocumentServer()
Dim document As Document = wordProcessor.Document
Dim bookmarks As ReadOnlyBookmarkCollection =
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
End-users can insert a bookmark or hyperlink in the document using the Links group of the Insert ribbon tab. Refer to the How to: Create the RichEditControl with a Ribbon UI topic for details on how to add the Ribbon Command UI to the application.
Additionally, RichEditControl ships with the following dialogs used to manage hyperlinks or bookmarks:
Tip
Set the DocumentCapabilitiesOptions.Hyperlinks or DocumentCapabilitiesOptions.Bookmarks property to DocumentCapability.Disabled to restrict end-users’ use of hyperlinks or bookmarks.
See Also
How to: Handle the HyperlinkClick Event to Invoke the Custom Form