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

  • 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.

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.

  1. First, 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.

    RichEditExamples - HyperlinkClick

  2. Provide the custom form class with the following members.

    • 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.

      object editValue;
      DocumentRange range;
      public virtual object EditValue { get { return editValue; } }
      public DocumentRange Range { get { return range; }  set { range = value; } }
    • 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.

      EventHandler onCommit;
      public event EventHandler Commit { add { onCommit += value; } remove { onCommit -= value; } }
  3. 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.

    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();
        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);
  4. 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.

    // 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.Replace(form.Range, value);
        //Uncomment this line to remove the clicked hyperlink once a desired value has been selected