DirectXFormBase.HtmlElementMouseClick Event

Occurs when a user clicks any element within an HTML template.

Namespace: DevExpress.XtraEditors

Assembly: DevExpress.Utils.v24.2.dll

Declaration

C#

[DXCategory("Events")]
public event DxHtmlElementMouseEventHandler HtmlElementMouseClick

VB.NET

<DXCategory("Events")>
Public Event HtmlElementMouseClick As DxHtmlElementMouseEventHandler

Event Data

The HtmlElementMouseClick event's data class is DxHtmlElementMouseEventArgs. The following properties provide information specific to this event:

Property	Description
Bounds	Returns actual bounds of a clicked element. The returned value depends on the screen scaling. For example, the Bounds property for a square div element with 50px sides returns Height and Width values of 100px when shown on a display with a 200% Windows scaling option.
Bubbles	Returns whether this element can pass an event up along the tree, to its parent HTML elements. You can enable the CancelBubble property to stop an event at this control level. See any “HtmlElementMouse~” event description for more details on bubbling (for example, WinExplorerView.HtmlElementMouseClick). Inherited from DxHtmlElementEventArgs.
Button	Returns the clicked mouse button.
CancelBubble	Specifies whether this element should pass an event to its parent elements. See any “HtmlElementMouse~” event description for more information about bubbling (for example, WinExplorerView.HtmlElementMouseClick). Inherited from DxHtmlElementEventArgs.
Clicks	Returns the number of clicks.
CurrentTarget	Inherited from DxHtmlElementEventArgs.
Element	Inherited from DxHtmlElementEventArgs.
ElementId	Returns the unique identifier of an HTML element. Element IDs are set in HTML markup (the “id” property). See any “HtmlElementMouse~” event description for more information (for example, WinExplorerView.HtmlElementMouseClick). Inherited from DxHtmlElementEventArgs.
HitInfo	Returns information about a clicked element.
IsClick
MouseArgs	Returns information about a mouse pointer.
NodeName	Inherited from DxHtmlElementEventArgs.
RootElement	Inherited from DxHtmlElementEventArgs.
SourceItem
SuppressOwnerEvent	Specifies whether a control whose HTML element triggered this event should raise its own related event. See any “HtmlElementMouse~” event description for more information (for example, WinExplorerView.HtmlElementMouseClick). Inherited from DxHtmlElementEventArgs.
TagName	Inherited from DxHtmlElementEventArgs.
Target	Inherited from DxHtmlElementEventArgs.
X	Returns the X coordinate of a mouse pointer.
Y	Returns the Y coordinate of a mouse pointer.

The event data class exposes the following methods:

Method
HasClassName(String, Boolean)
HasId(String, Boolean)
HasTag(String, Boolean)

Remarks

Objects of the DxHtmlElementMouseEventArgs class (and its parent DxHtmlElementEventArgs class) are used inside events and methods that allow you to handle user interactions with HTML elements.

Common Properties

X, Y, Clicks, and Button properties return information about mouse clicks: the mouse button that was clicked, the coordinates of the mouse pointer, and the number of clicks.

You can also read the MouseArgs property to get the same information in an aggregated MouseEventArgs object.

The Bounds property returns the location and actual screen size of an HTML element. For example, the Bounds property for a square <div> element with 50px sides returns Height and Width values of 100 when shown on a display with a 200% Windows scaling option.

Element ID

When you handle template-related control events (for example, HtmlContentControl.ElementMouseClick), these events are raised for any HTML element with which a user interacts.

<div class='buttonPanel'>
    <img src="PhoneCall" />
    <img src="VideoCall" />
    <img src="Message" />
</div>

C#

htmlContentControl.ElementMouseClick += (s, e) => {
    // Raises for all three IMG elements
};

VB.NET

AddHandler htmlContentControl.ElementMouseClick, Sub(s, e)
    ' Raises for all three IMG elements
End Sub

To identify which element has triggered an event, assign unique IDs in HTML markup.

<div class='buttonPanel'>
    <img id="btnPhone" src="PhoneCall"/>
    <img id="btnVideo" src="VideoCall"/>
    <img id="btnText" src="Message"/>
</div>

Then you can check the ElementId property value to identify HTML elements.

C#

htmlContentControl.ElementMouseClick += (s, e) => {
    if(e.ElementId == "btnPhone")
        // Action #1
    if(e.ElementId == "btnVideo")
        // Action #2
    if(e.ElementId == "btnText")
        // Action #3
};

VB.NET

AddHandler htmlContentControl.ElementMouseClick, Sub(s, e)
    If e.ElementId = "btnPhone" Then
        ' Action #1
    End If
    If e.ElementId = "btnVideo" Then
        ' Action #2
    End If
    If e.ElementId = "btnText" Then
        ' Action #3
    End If

Bubbling

The following markup illustrates four <div> elements nested one inside the other. Each element has its own onclick method called when users click this specific element.

<div class="container1" onclick="func1">
    <div class="container2" onclick="func2">
        <div class="container3" onclick="func3">
            <div class="container4" onclick="func4">
                Click Me
            </div>
        </div>
    </div>
</div>

C#

/* Important
 * Event handlers must be defined within a container control that hosts the HtmlContentControl.
 */
public partial class Form1 : DevExpress.XtraEditors.XtraForm {
    // ...

    void func1(object sender, DxHtmlElementMouseEventArgs args) {
        // Action #1
    }

    void func2(object sender, DxHtmlElementMouseEventArgs args) {
        // Action #2
    }
}

VB.NET

Private Sub func1(ByVal sender As Object, ByVal args As DxHtmlElementMouseEventArgs)
    ' Action #1
End Sub

Private Sub func2(ByVal sender As Object, ByVal args As DxHtmlElementMouseEventArgs)
    ' Action #2
End Sub

' ...

Important

Event handlers must be defined within a container control that hosts the HtmlContentControl (for example, a form or user control).

When a user clicks any element, the onclick method of this element fires first. After that, each parent HTML element subsequently calls its own onclick method. For example, if a user clicked the inner div element with the container4 style, all four methods are called in a sequence (func4 - func3 - func2 - func1).

This process of subsequent child-to-parent element activation is called bubbling, similar to how a bubble of air floats up in the water. The Bubbles property allows you to identify whether an element can pass the mouse event up through the elements tree. You can set the CancelBubble property to true to stop bubbling at this element.

C#

void func1(object sender, DxHtmlElementMouseEventArgs args) {
    // Not called automatically when the element with "func2" is clicked
}

void func2(object sender, DxHtmlElementMouseEventArgs args) {
    args.CancelBubble = true;
}

VB.NET

Private Sub func1(ByVal sender As Object, ByVal args As DxHtmlElementMouseEventArgs)
    ' Not called automatically when the element with "func2" is clicked
End Sub

Private Sub func2(ByVal sender As Object, ByVal args As DxHtmlElementMouseEventArgs)
    args.CancelBubble = True
End Sub

Note that the Bubbles property is an indicator that tells you whether this element has parent elements that can potentially handle the corresponding mouse event. If so, this property returns true even if you enable the CancelBubble property.

Suppress Control Events

When a user interacts with an HTML & CSS template element, a mouse event bubbles up through the elements tree and finally reaches the templated control itself. For example, when a Data Grid template element is clicked, Data Grid events fire after a sequence of element onclick methods (for instance, BaseView.Click).

You can enable the SuppressOwnerEvent property to prevent mouse events from reaching a control. In this case the control will not fire its native events.

Mouse Events for Elements in the Title Bar

Elements located in the title bar of the DirectX Form do not raise the HtmlElementMouseClick event. Only standard Minimize, Maximize, and Close buttons trigger this event when clicked.

The following markup from the DirectX Form demo adds five elements to the title bar. Of these five elements, only the Close button can trigger the HtmlElementMouseClick event.

<div class="shadowframe">
    <div class="frame" id="frame">
        <div class="titlebar">
            <img class="logo" src="Logo" /> <!--No Click event-->
            <div class="searchbox"> <!--No Click event-->
                <img class="searchimage" src="Search" />
            </div>
            <div class="addbutton"> <!--No Click event-->
                <div class="addbuttoncontainer">
                    <img class="addimage" src="Add" />
                    <div class="addbuttontext">Add New</div>
                </div>
            </div>
            <img class="button" src="User" id="loginbutton" /> <!--No Click event-->
            <img class="button" src="Close" id="closebutton"/> <!--Raises the Click event-->
        </div>
        <!--...-->
    </div>
</div>

This happens because the parent title bar intercepts all mouse events. When a pointer is over a title bar and a user presses a mouse button, the form considers this action to be the start of a drag-and-drop (move) operation. To make header elements interactive (allow them to raise their onclick methods and trigger the HtmlElementMouseClick event), you need to set their HtmlElementMouseDown events as handled.

For example, the code below checks element IDs, and if an ID starts with “button”, enables the Handled property for this element.

C#

this.HtmlElementMouseDown += (s, e) => {
    var args = e.MouseArgs as DXMouseEventArgs;
    if (e.ElementId.StartsWith("button"))
        args.Handled = true;
};

VB.NET

AddHandler Me.HtmlElementMouseDown, Sub(s, e)
    Dim args = TryCast(e.MouseArgs, DXMouseEventArgs)
    If e.ElementId.StartsWith("button") Then
        args.Handled = True
    End If
End Sub