UI Events

The events used to handle user interaction with UI elements.

Included in: dx.phonejs.js, dx.webappjs.js, dx.chartjs.js, dx.all.js

When developing an application you may often need to process a user gesture or another kind of interaction with a specific UI element. DevExtreme suggests UI events for this purpose. You can subscribe to an event of the required element to execute the specified function when the element is swiped, held, clicked, etc. You can use jQuery, Knockout, or AngularJS approach to subscribe to a required event.

  • jQuery

    If you use jQuery, you may use standard jQuery facilities to subscribe to and unsubscribe from events.

    JavaScript
    var clickEventHandler = function(event) {
        alert("The '" + $(event.target).text() + "' element has been clicked");
    };
    $("#myElement").on("dxclick", clickEventHandler);

    In the case of jQuery approach, the event handler function accepts an event argument, which holds a jQuery.event object.

    You can also specify additional event options if the event supports them.

    JavaScript
    $("#myElement").on("dxhold", { timeout: 1000 }, holdEventHandler);
  • Knockout

    To subscribe the required event using Knockout, apply one of the following bindings to the element.

    HTML
    <div id="myElement" data-bind="event: { dxclick: clickEventHandler }">
        My Element
    </div>

    or

    HTML
    <div id="myElement" data-bind="dxclick: clickEventHandler">
        My Element
    </div>
    JavaScript
    var viewModel = {
        clickEventHandler: function(data, event) {
            alert("The '" + $(event.target).text() + "' element has been clicked");
        }
    }

    In the case of Knockout approach, the event handler function accepts the following arguments.

    • data
      An object holding the current view model.

    • event
      A jQuery.event object.

    Refer to the Knockout documentation for more information on event binding.

    The Knockout approach accepts the following syntax for specifying event options.

    HTML
    <div id="myElement" data-bind="dxHold: { execute: holdEventHandler, timeout: 1000 }">
    </div>
  • AngularJS

    AngularJS enables you to subscribe to an event in the following way.

    HTML
    <div id="myElement" dx-click="clickEventHandler($event)">
    </div>

    In the case of the AngularJS approach, to access the jQuery.Event object associated with the current event, pass the $event argument to the handler function as shown above.

    You can access this object within a handler function the event parameter as demonstrated in the following example.

    JavaScript
    var myApp = angular.module('myApp', ['dx']);
    myApp.controller("demoController", function ($scope) {
        $scope.clickEventHandler = function(event) {
            alert("The '" + $(event.target).text() + "' element has been clicked");
        }
    });

    The AngularJS approach also enables you to specify additional event options using the following syntax.

    HTML
    <div id="myElement" dx-hold="{ execute: 'holdEventHandler($event)', timeout: 1000 }">
    </div>
NOTE
An event handling function for certain DevExtreme UI events may support additional parameters described in the required event description.

dxclick

Raised when the element is clicked.

Type: jQuery.Event

The native click event waits 300 ms after the element was clicked. This time interval is required to wait for the second click. If a user clicks the element one more time during this time span, the dblclick event is raised instead of click. The dxclick event is raised immediately after the element is clicked.

Show Example:
jQuery

dxcontextmenu

Raised when the right mouse button is clicked on the element or when the element is held during a specified time period.

dxdrag

Raised when the drag gesture has been performed.

Event Handler Argument:
:
Object structure:
offset: Number

Indicates which distance has been passed during the dragging gesture, measured as a ratio to the target element's width.

cancel: Boolean

Indicates whether to prevent the drag gesture. Set this field to true to cancel the gesture.

Show Example:
jQuery

dxdragend

Raised when the drag gesture has been completed.

Event Handler Argument:
:
Object structure:
offset: Number

Indicates which distance has been passed during the dragging gesture, measured as a ratio to the target element's width.

cancel: Boolean

Indicates whether to prevent the drag gesture. Set this field to true to cancel the gesture.

Show Example:
jQuery

dxdragenter

Raised when a user moves the pointer into the element, provided that the drag gesture is being performed.

Type: jQuery.Event
Event Handler Argument:
:
Object structure:
draggingElement: Element

The element which is being dragged.

Show Example:
jQuery

dxdragleave

Raised when a user moves the pointer out of the element, provided that the drag gesture is being performed.

Type: jQuery.Event
Event Handler Argument:
:
Object structure:
draggingElement: Element

The element which is being dragged.

Show Example:
jQuery

dxdragstart

Raised when the drag gesture has been started.

Event Handler Argument:
:
Object structure:
cancel: Boolean

Indicates whether to prevent the drag gesture. Set this field to true to cancel the gesture.

Show Example:
jQuery

dxdrop

Raised when dragged data has been dropped on the element.

Type: jQuery.Event
Event Handler Argument:
:
Object structure:
draggingElement: Element

The element which is being dragged.

Show Example:
jQuery

dxhold

Raised when the element is being held during a specified time.

Type: jQuery.Event

To specify the time span after which the event is raised, pass the object containing the timeout property to the function subscribing to the event.

JavaScript
$("#myElement").on("dxhold", { timeout: 1000 }, function() {
    alert("The element is being held during 1000 milliseconds");
});
Show Example:
jQuery

dxhoverend

Raised when the mouse pointer leaves the element.

Type: jQuery.Event
NOTE
This event requires the mouse pointer, and is hence supported only by desktop browsers.
Show Example:
jQuery

dxhoverstart

Raised when the mouse pointer appears over the element.

Type: jQuery.Event
NOTE
This event requires the mouse pointer, and is hence supported only by desktop browsers.
Show Example:
jQuery

dxpinch

Raised when the pinch gesture has been performed.

Event Handler Argument:
:
Object structure:
scale: Number

Indicates a scale transformation against the initial scale.

deltaScale: Number

Indicates a scale transformation against the last gesture update.

cancel: Boolean

Specifies whether or not to cancel gesture processing.

dxpinchend

Raised when the pinch gesture has been completed.

Event Handler Argument:
:
Object structure:
scale: Number

Indicates a scale transformation against the initial scale.

deltaScale: Number

Indicates a scale transformation against the last gesture update.

cancel: Boolean

Specifies whether or not to cancel gesture processing.

dxpinchstart

Raised when the pinch gesture has been started.

Event Handler Argument:
:
Object structure:
cancel: Boolean

Specifies whether or not to cancel gesture processing.

dxpointercancel

Raised when the pointer is no longer likely to produce events.

Type: jQuery.Event
Event Handler Argument:
:
Object structure:
pointerType: String

Specifies the hardware agnostic pointer input type: a mouse, pen or touchscreen.

The event can be raised because of a hardware event; such as, if a device changes the screen orientation while the pointer is active or the number of simultaneous pointers exceeds the supported number, etc.

dxpointerdown

Raised when the pointer takes on the active buttons state.

Type: jQuery.Event
Event Handler Argument:
:
Object structure:
pointerType: String

Specifies the hardware agnostic pointer input type: a mouse, pen or touchscreen.

For a mouse pointer, this event is raised when the mouse state changes from no buttons pressed to at least one button pressed. For touch and pen pointers, the event is raised when physical contact is made with the digitizer.

Show Example:
jQuery

dxpointerenter

Raised when a pointer is moved to either the hit test area of an element or one of its descendants.

Type: jQuery.Event
Event Handler Argument:
:
Object structure:
pointerType: String

Indicates the type of the device that caused the event. (Mouse, pen, or touch)

dxpointerleave

Raised when a pointer is moved from either the hit test area of an element or one of its descendants.

Type: jQuery.Event
Event Handler Argument:
:
Object structure:
pointerType: String

Indicates the type of the device that caused the event. (Mouse, pen, or touch)

dxpointermove

Raised when any pointer parameter has been changed. (Position, tilt, pressure, button state, or contact geometry).

Type: jQuery.Event
Event Handler Argument:
:
Object structure:
pointerType: String

Specifies the hardware agnostic pointer input type: a mouse, pen or touchscreen.

Show Example:
jQuery

dxpointerout

Raised when a pointer is moved from either the hit test area of an element or one of its descendants.

Type: jQuery.Event
Event Handler Argument:
:
Object structure:
pointerType: String

Indicates the type of the device that caused the event. (Mouse, pen, or touch)

dxpointerover

Raised when a pointer is moved to the hit test area of an element or one of its descendants.

Type: jQuery.Event
Event Handler Argument:
:
Object structure:
pointerType: String

Indicates the type of the device that caused the event. (Mouse, pen, or touch)

dxpointerup

Raised when the pointer loses the active buttons state.

Type: jQuery.Event
Event Handler Argument:
:
Object structure:
pointerType: String

Specifies the hardware agnostic pointer input type: a mouse, pen or touchscreen.

For a mouse pointer, this event is raised when the mouse state changes from at least one button pressed to no buttons pressed. For touch and pen pointers, the event is raised when physical contact is removed from the digitizer.

Show Example:
jQuery

dxrotate

Raised when the rotate gesture has been performed.

Event Handler Argument:
:
Object structure:
rotation: Number

Indicates the rotation angle against the initial position.

deltaRotation: Number

Indicates the rotation angle against the last gesture update.

cancel: Boolean

Specifies whether or not to cancel gesture processing.

dxrotateend

Raised when the rotate gesture has been completed.

Event Handler Argument:
:
Object structure:
rotation: Number

Indicates the rotation angle against the initial position.

deltaRotation: Number

Indicates the rotation angle against the last gesture update.

cancel: Boolean

Specifies whether or not to cancel gesture processing.

dxrotatestart

Raised when the rotate gesture has been started.

Event Handler Argument:
:
Object structure:
cancel: Boolean

Specifies whether or not to cancel gesture processing.

dxswipe

Raised when the swipe gesture has been performed.

Type: jQuery.Event
Event Handler Argument:
:
Object structure:
offset: Number

Indicates which distance has been passed during the swipe gesture, measured as a ratio to the target element's width.

cancel: Boolean

Indicates whether or not to prevent the swipe gesture. Set this field to true to cancel the gesture.

The event supports the direction option that specifies whether the event is raised for horizontal or vertical scrolling. The option can take on the "vertical" and "horizontal" values. The default option value is "horizontal".

Show Example:
jQuery

dxswipeend

Raised when the swipe gesture is finished.

Type: jQuery.Event
Event Handler Argument:
:
Object structure:
offset: Number

Indicates which distance has been passed during the swipe gesture, measured as a ratio to the target element's width.

targetOffset: Number

Indicates which distance will be passed to completely finish the motion, measured as a ratio to the target element's width.

The event supports the direction option, which specifies whether the event is raised for horizontal or vertical scrolling. The option can take on the "vertical" and "horizontal" values. The default option value is "horizontal".

Show Example:
jQuery

dxswipestart

Raised when the swipe gesture is started.

Type: jQuery.Event
Event Handler Argument:
:
Object structure:
cancel: Boolean

Indicates whether to prevent the swipe gesture. Set this field to true to cancel the gesture.

The event supports the direction option, which specifies whether the event is raised for horizontal or vertical scrolling. The option can take on the "vertical" and "horizontal" values. The default option value is "horizontal".

Show Example:
jQuery

dxtransform

Raised when the transform gesture has been performed.

Event Handler Argument:
:
Object structure:
scale: Number

Indicates a scale transformation against the initial scale.

deltaScale: Number

Indicates a scale transformation against the last gesture update.

rotation: Number

Indicates the rotation angle against the initial position.

deltaRotation: Number

Indicates the rotation angle against the last gesture update.

translation: Object

Indicates the translation distance against the initial position.

deltaTranslation: Object

Indicates the translation distance against the last gesture update.

cancel: Boolean

Specifies whether or not to cancel gesture processing.

dxtransformend

Raised when the transform gesture has been completed.

Event Handler Argument:
:
Object structure:
scale: Number

Indicates a scale transformation against the initial scale.

deltaScale: Number

Indicates a scale transformation against the last gesture update.

rotation: Number

Indicates the rotation angle against the initial position.

deltaRotation: Number

Indicates the rotation angle against the last gesture update.

translation: Object

Indicates the translation distance against the initial position.

deltaTranslation: Object

Indicates the translation distance against the last gesture update.

cancel: Boolean

Specifies whether or not to cancel gesture processing.

dxtransformstart

Raised when the transform gesture has been started.

Event Handler Argument:
:
Object structure:
cancel: Boolean

Specifies whether or not to cancel gesture processing.

dxtranslate

Raised when the translate gesture has been performed.

Event Handler Argument:
:
Object structure:
translation: Object

Indicates the translation distance against the initial position.

deltaTranslation: Object

Indicates the translation distance against the last gesture update.

cancel: Boolean

Specifies whether or not to cancel gesture processing.

dxtranslateend

Raised when the translate gesture has been completed.

Event Handler Argument:
:
Object structure:
translation: Object

Indicates the translation distance against the initial position.

deltaTranslation: Object

Indicates the translation distance against the last gesture update.

cancel: Boolean

Specifies whether or not to cancel gesture processing.

dxtranslatestart

Raised when the translate gesture has been started.

Event Handler Argument:
:
Object structure:
cancel: Boolean

Specifies whether or not to cancel gesture processing.

dxzoom

Deprecated

Use the dxpinch event instead.

Raised when the zoom gesture has been performed.

Event Handler Argument:
:
Object structure:
scale: Number

Indicates a scale transformation against the initial scale.

deltaScale: Number

Indicates a scale transformation against the last gesture update.

cancel: Boolean

Specifies whether or not to cancel gesture processing.

dxzoomend

Deprecated

Use the dxpinchend event instead.

Raised when the zoom gesture has been completed.

Event Handler Argument:
:
Object structure:
scale: Number

Indicates a scale transformation against the initial scale.

deltaScale: Number

Indicates a scale transformation against the last gesture update.

cancel: Boolean

Specifies whether or not to cancel gesture processing.

dxzoomstart

Deprecated

Use the dxpinchstart event instead.

Raised when the zoom gesture has been started.

Event Handler Argument:
:
Object structure:
cancel: Boolean

Specifies whether or not to cancel gesture processing.