How to: Handle the HyperlinkClick Event to Invoke the Custom Form

• Nov 28, 2023
• 5 minutes to read

The following example demonstrates how to manually implement complex hyperlink behavior by handling the RichEditControl.HyperlinkClick event. In this example, this event handler is used to invoke a form with the data list. The end-user can select the item from the pop-up list and it automatically replaces the hyperlink content.

Show Animation

To accomplish this task, do the following:

• Create a document with hyperlinks.
• Create a custom form, implement it depending on your current needs and provide it with the members, allowing you to retrieve the selected item value and associate it with the hyperlink.
• Handle the main form’s RichEditControl.HyperlinkClick event to invoke the created form. In this event handler, call the SubDocument.Replace method to substitute the hyperlink content with the desired value.

Tip

If you want to change the modifier key used to activate the hyperlink, specify the main form’s HyperlinkOptions.ModifierKeys property. You can select any of the available keys or set the property to None to activate the hyperlink by a click.

The steps below provide more detailed information about how to display a custom pop-up list by clicking a hyperlink.

Create a Custom Form

Create a custom form with the ListBoxControl that will be shown when a hyperlink is clicked. In Visual Studio’s Solution Explorer window, right-click your project and select “Add DevExpress Item | Form…” to add a skinable XtraForm. Then, open the Toolbox and drop the ListBoxControl onto the new form.

Create two properties, EditValue and Range. The first property gets the value of the selected list item, the second property is used to point to the document range which will be replaced with the selected value.

SelectProductForm.cs

object editValue;
DocumentRange range;
public virtual object EditValue { get { return editValue; } }
public DocumentRange Range { get { return range; }  set { range = value; } }

SelectProductForm.vb

Private editValue_Renamed As Object

Private range_Renamed As DocumentRange
Public Overridable ReadOnly Property EditValue() As Object
    Get
        Return editValue_Renamed
    End Get
End Property
Public Property Range() As DocumentRange
    Get
        Return range_Renamed
    End Get
    Set(ByVal value As DocumentRange)
        range_Renamed = value
    End Set
End Property

Declare the Commit event, raised when the form is going to be invoked. This event is used to catch the moment when the item is selected from the list.

SelectProductForm.cs

EventHandler onCommit;
public event EventHandler Commit { add { onCommit += value; } remove { onCommit -= value; } }

SelectProductForm.vb

Private Event onCommit_Renamed As EventHandler
Public Custom Event Commit As EventHandler
    AddHandler(ByVal value As EventHandler)
        AddHandler onCommit_Renamed, value
    End AddHandler
    RemoveHandler(ByVal value As EventHandler)
        RemoveHandler onCommit_Renamed, value
    End RemoveHandler
    RaiseEvent(ByVal sender As System.Object, ByVal e As System.EventArgs)
    End RaiseEvent
End Event

Handle Events in the Main Form

In the main form class, handle the RichEditControl.HyperlinkClick event to create a new instance of a custom form and supply it with the start-up location and hyperlink range. The form’s location is determined by the caret position, which can be accessed using the RichEditControl.GetBoundsFromPosition method.

Form1.cs

public Hyperlink activeLink;
void OnHyperlinkClick(object sender, HyperlinkClickEventArgs e)
{
    activeLink = e.Hyperlink;
    SelectProductForm form = new SelectProductForm(products);
    // Set the Commit event handler:
    form.Commit += OnProductFormCommit;
    // Set the Range property to the hyperlink range:
    form.Range =  activeLink.Range;
    // Set the Location property to specify the location where the form is going to be invoked:  
    form.Location = GetFormLocation();
    form.Show();
    e.Handled = true;            
}

// This method places the form to the right of the cursor position: 
Point GetFormLocation()
{
    DocumentPosition position = this.richEditControl1.Document.CaretPosition;
    Rectangle rect = this.richEditControl1.GetBoundsFromPosition(position);
    Point location = new Point(rect.Right, rect.Bottom);
    Point localPoint = Units.DocumentsToPixels(location, this.richEditControl1.DpiX, this.richEditControl1.DpiY);
    return this.richEditControl1.PointToScreen(localPoint);
}

Form1.vb

Public activeLink As Hyperlink
Private Sub OnHyperlinkClick(ByVal sender As Object, ByVal e As HyperlinkClickEventArgs)
    activeLink = e.Hyperlink
    Dim form As New SelectProductForm(products)
    ' Set the Commit event handler:
    AddHandler form.Commit, AddressOf OnProductFormCommit
    ' Set the Range property to the hyperlink range:
    form.Range = activeLink.Range
    ' Specify the Location property to specify the location where the form is going to be invoked:  
    form.Location = GetFormLocation()
    form.Show()
    e.Handled = True
End Sub

' This method places the form to the right of the cursor position: 
Private Function GetFormLocation() As Point
    Dim position As DocumentPosition = Me.richEditControl1.Document.CaretPosition
    Dim rect As Rectangle = Me.richEditControl1.GetBoundsFromPosition(position)
    Dim location As New Point(rect.Right, rect.Bottom)
    Dim localPoint As Point = Units.DocumentsToPixels(location, Me.richEditControl1.DpiX, Me.richEditControl1.DpiY)
    Return Me.richEditControl1.PointToScreen(localPoint)
End Function

Finally, declare the Commit event handler which substitutes the document range obtained from the Range property with the selected item’s value obtained from the EditValue property.

Form1.cs

// Handle the event to replace the hyperlink with the selected item value: 
void OnProductFormCommit(object sender, EventArgs e)
{
    SelectProductForm form = (SelectProductForm)sender;
    string value = (string)form.EditValue;
    Document document = this.richEditControl1.Document;
    document.BeginUpdate();
    document.Replace(form.Range, value);

    // Uncomment this line to remove the clicked hyperlink once a desired value has been selected
    // richEditControl1.Document.Hyperlinks.Remove(activeLink);
    document.EndUpdate();
}

Form1.vb

' Handle the event to replace the hyperlink with the selected item value: 
Private Sub OnProductFormCommit(ByVal sender As Object, ByVal e As EventArgs)
    Dim form As SelectProductForm = DirectCast(sender, SelectProductForm)
    Dim value As String = DirectCast(form.EditValue, String)
    Dim document As Document = Me.richEditControl1.Document
    document.BeginUpdate()
    document.Replace(form.Range, value)

    ' Uncomment this line to remove the clicked hyperlink once a desired value has been selected
    'richEditControl1.Document.Hyperlinks.Remove(activeLink);
    document.EndUpdate()
End Sub