Version

Adding Hyperlinks (xamRichTextEditor)

Topic Overview

Purpose

This topic provides information on how to create hyperlinks using the xamRichTextEditor ™ from the developer’s perspective.

Required background

The following topics are prerequisites to understanding this topic:

Topic Purpose

This topic provides an overview of the features supported by the xamRichTextEditor control.

This topic explains the document’s content logical structure you can use to edit the contents in the xamRichTextEditor programmatically.

This topic provides detailed instructions to help you get up and running as quickly as possible with the xamRichTextEditor .

In this topic

This topic contains the following sections:

Introduction

Hyperlinks summary

The xamRichTextEditor supports internal hyperlinks within the document navigating the user to a website. Hyperlinks are rendered with a different style so they can easily be distinguished from the text amongst the other rich content.

You can use the TrackHistory property to enable a link to be rendered in a different color when it is once visited.

The user may visit a hyperlink by clicking on it while holding the control key pressed. This will trigger a HyperlinkExecuting event, which can be used to inspect and/or modify the URI address or cancel the hyperlink opening.

Adding Hyperlinks Summary

Adding Hyperlinks summary chart

There are three ways for adding a hyperlink in the RichTextDocument using code. Further details are available after the table.

Adding Hyperlinks Details

This method creates hyperlink by inserting new text in the document content.

This method creates hyperlink using existing document content.

This method involves the creation of objects in the document body’s node hierarchy.

By Invoking the InsertHyperlink Method

Overview

By invoking the InsertHyperlink method, you can insert a hyperlink at any offset of the document.

Property settings

The following table maps the desired configuration to its respective property settings.

In order to create a hyper link: And set the following properties:

Invoke the InsertHyperlink method

  • documentOffset

  • targetUri

  • error

  • displayText (optional)

  • tooltip (optional)

Example

The code snippet below demonstrates how to create a hyperlink using the InserHyperlink method:

In C#:

string error = null;
this.xamRichTextEditor1.Document.InsertHyperlink(0,
    "http://es.infragistics.com/", out error, "Infragistics",
    "Link to the Infragistics website.");

In Visual Basic:

Dim [error] As String = Nothing
Me.xamRichTextEditor1.Document.InsertHyperlink(0, _
    "http://es.infragistics.com/", _
        [error], _
        "Infragistics", _
        "Link to the Infragistics website.")

By Invoking the MakeHyperlink Method

Overview

By invoking the MakeHyperlink method, you can insert a hyperlink using an existing document span by providing the document span which will be used. This case uses the content of the document as display text, the target URI and the tooltip will be provided as arguments to the method.

Property settings

The following table maps the desired configuration to its respective property settings.

In order to create a hyper link: And set the following properties:

Invoke the MakeHyperlink method

  • document span

  • targetUri

  • error

  • tooltip (optional)

Example

The code snippet below demonstrates how to create a hyperlink by invoking the MakeHyperlink method using the current active view selection as link content:

In C#:

string error = null;
this.xamRichTextEditor1.Document.MaketHyperlink(
    this.xamRichTextEditor1.ActiveDocumentView.Selection.DocumentSpan,
    "http://www.example.com/", out error, "Example.com"
);

In Visual Basic:

Dim [error] As String = Nothing
Me.xamRichTextEditor1.Document.MaketHyperlink( _
    Me.xamRichTextEditor1.ActiveDocumentView.Selection.DocumentSpan, _
    "http://www.example.com/", [error], "Example.com")

By Creating a HyperlinkNode Instance

Overview

You can also create a hyperlink by creating a HyperlinkNode instance.

Example

The code snippet below demonstrates how to create a hyperlink and add it in the a new paragraph at the end of the document’s content:

In C#:

var hNode = new HyperlinkNode();
hNode.Tooltip = "Link to the Infragistics website.";
hNode.Uri = "http://es.infragistics.com/";
hNode.SetText("Infragistics");
hNode.TrackHistory = true;
var pNode = new ParagraphNode();
pNode.ChildNodes.Add(hNode);
this.xamRichTextEditor1.Document.RootNode.Body.ChildNodes.Add(pNode);

In Visual Basic:

Dim hNode = New HyperlinkNode()
hNode.Tooltip = "Link to the Infragistics website."
hNode.Uri = "http://es.infragistics.com/"
hNode.SetText("Infragistics")
hNode.TrackHistory = True
Dim pNode = New ParagraphNode()
pNode.ChildNodes.Add(hNode)
Me.xamRichTextEditor1.Document.RootNode.Body.ChildNodes.Add(pNode)
Note
Note

Using the SetText method of the HyperlinkNode for creating link content is also setting the StyleId property to a value "Hyperlink" and will apply the default hyperlink style to this hyperlink. If you do not use this method and still want to apply a style you will have to manually set the hyperlink style using the StyleId property.
Note
Note

The "Hyperlink" style is not initially available in the DocumentRootNode.Styles collection and if you want to use it you will have to add it from the RichTextDocument.AvailableStyles collection:

In C#:

this.xamRichTextEditor.Document.RootNode.Styles.Add(
    this.xamRichTextEditor.Document.AvailableStyles["Hyperlink"].Clone()
    as CharacterStyle);

In Visual Basic:

Me.xamRichTextEditor.Document.RootNode.Styles.Add(_
    TryCast(Me.xamRichTextEditor.Document.AvailableStyles("Hyperlink").Clone(), _
    CharacterStyle))

To avoid this you can use the InsertHyperlink or MakeHyperlink methods.

Managing Hyperlink Click Event

Overview

When the user clicks a link while holding the control key, the HyperlinkExecuting event is fired. You can perform the follwoing operation in the event handler using the provided argument of type HyperlinkExecutingEventArgs:

Example

The following table maps the desired operation to its respective property:

In order to: Use this property on the HyperlinkExecutingEventArgs argument: And:

Cancel the HyperlinkExecuting event

Set it to true

Obtain or change the URI which will be opened

Uri

Read the current or set a new value

Obtain or change the working directory used in conjunction with a relative file set in the Uri property

Read the current or set a new value

Related Topics

The following topics provide additional information related to this topic.

Topic Purpose

This topic provides information on how to create text using the xamRichTextEditor from a developer’s perspective.

This topic provides information on how to create lists using the xamRichTextEditor from the developer’s perspective.

This topic provides information on how to create images using the xamRichTextEditor from the developer’s perspective.

This topic provides information on how to use the xamRichTextEditor to create tables from the developer’s perspective.