Skip to main content

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

  • 6 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. An end-user can select the desired item from the pop-up list. The value of the selected item automatically replaces the hyperlink content.

Show Animation


To accomplish this task, perform the following actions.

  • Create a document with hyperlinks.
  • Implement a custom form depending on your current needs and provide it with the members allowing you to retrieve the selected item value, associate it with the hyperlink and determine the form’s startup location.
  • 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.


If you want to change the modifier key used to activate the hyperlink, specify the main form’s DXRichEditHyperlinkOptions.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 on how to display a custom pop-up list by clicking a hyperlink.

Custom Form

  1. First, create a custom form with the ListBoxEdit, which will be shown when a hyperlink is clicked. In Visual Studio’s Solution Explorer window, right-click your project and select “Add | User Control…”. Then, open the Toolbox and drop the ListBoxEdit onto the new form. HyperlinkClickHandling_CreateCustomForm
  2. Create two properties, EditValue and Range. The first property gets the value of the selected list item; the second property is used to refer to the document range which will be replaced with the selected value.

    View Example

    Private fEditValue As Object
    Private fRange As DocumentRange
    Public Overridable ReadOnly Property EditValue() As Object
            Return fEditValue
        End Get
    End Property
    Public Property Range() As DocumentRange
            Return fRange
        End Get
        Set(ByVal value As DocumentRange)
            fRange = value
        End Set
    End Property
  3. Additionally, add the OwnerWindow property of a FloatingContainer class. This property allows you to set the startup position of a custom form.

    View Example

    Private fOwnerWindow As FloatingContainer
    Public Property OwnerWindow() As FloatingContainer
            Return fOwnerWindow
        End Get
        Set(ByVal value As FloatingContainer)
            If fOwnerWindow Is value Then
            End If
            fOwnerWindow = value
        End Set
    End Property
    Protected Sub OnOwnerWindowChanged()
        If OwnerWindow IsNot Nothing Then
            OwnerWindow.Caption = "Select a product"
        End If
    End Sub
  4. Declare the Commit event, which is raised when the form is going to be invoked. This event is used to catch the moment when an item is selected from the list.

    View Example

    Private onCommit As EventHandler
    Public Custom Event Commit As EventHandler
        AddHandler(ByVal value As EventHandler)
            onCommit = DirectCast(System.Delegate.Combine(onCommit, value), EventHandler)
        End AddHandler
        RemoveHandler(ByVal value As EventHandler)
            onCommit = DirectCast(System.Delegate.Remove(onCommit, value), EventHandler)
        End RemoveHandler
        RaiseEvent(ByVal sender As System.Object, ByVal e As System.EventArgs)
            If onCommit IsNot Nothing Then
                For Each d As EventHandler In onCommit.GetInvocationList()
                    d.Invoke(sender, e)
                Next d
            End If
        End RaiseEvent
    End Event

Main Form

  1. In the main form class, handle the RichEditControl.HyperlinkClick event as shown in the code snippet below.

    View Example

    Private Sub richEditControl1_HyperlinkClick(ByVal sender As Object, ByVal e As HyperlinkClickEventArgs)
        If e.ModifierKeys <> Me.richEditControl1.Options.Hyperlinks.ModifierKeys Then
        End If
        'Initialize the custom form            
        Dim control As New SelectProductForm(products)
        'Subscribe it to the OnCommit event
        AddHandler control.Commit, AddressOf OnProductFormCommit
        'Connect the form with the hyperlink range
        control.Range = e.Hyperlink.Range
        'Associate the form with the FloatingContainer instance
        Dim container As FloatingContainer = FloatingContainerFactory.Create(FloatingMode.Window)
        control.OwnerWindow = container
        container.Content = control
        container.Owner = Me.richEditControl1
        DirectCast(Me.richEditControl1, ILogicalOwner).AddChild(container)
        'Set the form's location and size
        container.SizeToContent = SizeToContent.WidthAndHeight
        container.ContainerStartupLocation = WindowStartupLocation.Manual
        container.FloatLocation = GetFormLocation()
        container.IsOpen = True
        Me.activeWindow = container
        e.Handled = True
    End Sub
  2. Implement a method which determines the form’s startup location relative to the caret position (can be accessed using the RichEditControl.GetBoundsFromPosition method).

    View Example

    Private Function GetFormLocation() As System.Windows.Point
        'Retrive the caret position
        Dim position As DocumentPosition = Me.richEditControl1.Document.CaretPosition
        Dim rect As Rectangle = Me.richEditControl1.GetBoundsFromPosition(position)
        'Set the startup location relative to the retrieved position
        'within the application bounds
        Dim richViewBounds As Rectangle = GetRichEditViewBounds()
        Dim location As New System.Drawing.Point(rect.Right - richViewBounds.X, rect.Bottom - richViewBounds.Y)
        Dim localPoint As System.Drawing.Point = Units.DocumentsToPixels(location, Me.richEditControl1.DpiX, Me.richEditControl1.DpiY)
        Return New System.Windows.Point(localPoint.X, localPoint.Y)
    End Function
    Private Function GetRichEditViewBounds() As Rectangle
        Dim documentLayoutUnitConverter As DocumentLayoutUnitConverter = New DocumentLayoutUnitDocumentConverter(Me.richEditControl1.DpiX, Me.richEditControl1.DpiY)
        Return documentLayoutUnitConverter.LayoutUnitsToDocuments(richEditControl1.ViewBounds)
    End Function
  3. Finally, declare the Commit event handler as follows.

    View Example

    Private Sub OnProductFormCommit(ByVal sender As Object, ByVal e As EventArgs)
        Dim form As SelectProductForm = DirectCast(sender, SelectProductForm)
        'Retrieve the selected item value
        Dim value As String = DirectCast(form.EditValue, String)
        Dim document As Document = Me.richEditControl1.Document
        'Start the document modification
        'Replace the hyperlink range content
        'with the retireved value
        document.Replace(form.Range, value)
        'Finish the document update
    End Sub