Package com.smartgwt.client.util

# Class EventHandler

java.lang.Object
com.smartgwt.client.util.EventHandler

public class EventHandler extends Object
SmartGWT provides a predictable cross-browser event-handling mechanism for SmartGWT widgets, and the EventHandler class provides various static APIs for retrieving details about events which have occurred.

Events may be intercepted at the page level using standard GWT methods such as addNativePreviewHandler() on the `com.google.gwt.user.client.Event` class.

If the event occurred on an enabled widget it is sent to that widget's event handler, if any. This handler can cancel further propagation of the event by returning false. An "enabled" widget is any widget that defines an event handler for one of the supported events.

The event is "bubbled" up to the widget's parent in the containment hierarchy, if any. Again, the parent's handler for the event can cancel further propagation by calling `event.cancel()`. This step is repeated, with the event "bubbling" up through the containment hierarchy, until a top-level widget is reached or the event is explicitly canceled.

Where applicable, canceling an event will also typically suppress the native behavior (for example canceling a keypress while focused in a form item may prevent the key character being inserted in the text box).

SmartGWT libraries will not interfere with native event handling when events occur outside of a target widget. You can therefore have HTML that is not ISC-based on the same page as widget objects that will react to native events as you would expect.

See Also:
  - `PageEvent`
  - `com.smartgwt.client.util.Page#setEvent`
  - `com.smartgwt.client.util.Page#clearEvent`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `EventHandler()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Boolean`
  `altKeyDown()`
  Return true if the alt (option) key is being held down.
  `static Boolean`
  `ctrlKeyDown()`
  Return true if the control key is being held down.
  `static Rectangle`
  `getDragRect()`
  During a drag with dragAppearance of either "target" or "outline", returns the page-relative coordinates of whatever element is being dragged.
  `static Canvas`
  `getDragTarget()`
  Returns the current dragTarget.
  `static Canvas`
  `getFocusCanvas()`
  Method to return the `canvasFocus:true` canvas with current keyboard focus.
  `static String`
  `getKey()`
  Return the name of the key for the event passed in.
  `static String`
  `getKeyEventCharacter()`
  Returns the character for a keypress event, derived from the `event.characterValue`.
  `static int`
  `getKeyEventCharacterValue()`
  Returns the numeric characterValue reported by the browser.
  `static String`
  `getKeyEventCode()`
  Return the natively reported event.code value for the current event (keyboard) event.
  `static String`
  `getKeyEventKey()`
  Return the natively reported event.key value for the current event.
  `static Integer`
  `getMouseDownX()`
  Return the page-relative X (horizontal) coordinate of an event.
  `static Integer`
  `getMouseDownY()`
  Return the page-relative Y (vertical) coordinate of an event.
  `static Object`
  `getNativeDragData()`
  `static Element`
  `getNativeMouseTarget()`
  Returns the natively reported target (or source) DOM element for the current mouse event.
  `static String`
  `getReportedKey()`
  This method is a synonym for `getKeyEventKey()`
  `static Canvas`
  `getTarget()`
  Return the canvas that is the target of the mouse event.
  `static float`
  `getWheelDelta()`
  Deprecated.
  in favor of `getWheelDeltaY()`
  `static double`
  `getWheelDeltaAsDouble()`
  Deprecated.
  in favor of `getWheelDeltaY()`
  `static double`
  `getWheelDeltaX()`
  Horizontal scroll delta reported by a `mouseWheel` event (such as a horizontal swipe on a track-pad).
  `static double`
  `getWheelDeltaY()`
  Applies to `mouseWheel` events only.
  `static int`
  `getX()`
  Return the page-relative X (horizontal) coordinate of an event.
  `static int`
  `getY()`
  Return the page-relative Y (vertical) coordinate of an event.
  `static Boolean`
  `leftButtonDown()`
  Returns true if the left mouse button is being pressed.
  `static boolean`
  `middleButtonDown()`
  Returns true if the middle mouse button is being pressed.
  `static Boolean`
  `rightButtonDown()`
  Returns true if the right mouse button is being pressed.
  `static void`
  `setDragOffset(int offsetX, int offsetY)`
  Sets the initial coordinate offset of the last event, typically a mouseDown or touchStart, from the drag target.
  `static void`
  `setDragTracker(String html)`
  Set the HTML for the drag tracker that follows the mouse during a drag and drop interaction.
  `static void`
  `setDragTracker(String html, int newWidth, int newHeight, int offsetX, int offsetY)`
  Set the HTML for the drag tracker that follows the mouse during a drag and drop interaction.
  `static void`
  `setDragTrackerImage(String src)`
  This API may be called to set the native HTML5 drag tracker image.
  `static void`
  `setDragTrackerImage(String src, int x)`
  `static void`
  `setDragTrackerImage(String src, int x, int y)`
  This API may be called to set the native HTML5 drag tracker image.
  `static void`
  `setNativeDragData(Object data)`
  `static void`
  `setNativeDragData(Object data, String strData)`
  `static Boolean`
  `shiftKeyDown()`
  Return true if the shift key is being held down.
  `static Boolean`
  `targetIsMasked(Canvas target)`
  Return whether this Canvas is masked by a clickMask (see `Canvas.showClickMask()`).

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### EventHandler

    public EventHandler()

- ## Method Details

  - ### altKeyDown

    public static Boolean altKeyDown()
    Return true if the alt (option) key is being held down. Note that this is only set reliably for keyboard events.
    Returns:
      true == alt key is down

  - ### ctrlKeyDown

    public static Boolean ctrlKeyDown()
    Return true if the control key is being held down. Note that this is only set reliably for keyboard events.
    Returns:
      true == control key is down

  - ### getDragTarget

    public static Canvas getDragTarget()
    Returns the current dragTarget. This is the component on which the drag and drop interaction was initiated. This only returns something meaningful during a drag and drop interaction.
    Returns:
      The dragTarget.
    See Also:
      - `Canvas.getDragTarget()`

  - ### getFocusCanvas

    public static Canvas getFocusCanvas()
    Method to return the `canvasFocus:true` canvas with current keyboard focus.
    Returns:
      Current focus canvas

  - ### getKeyEventCharacter

    public static String getKeyEventCharacter()
    Returns the character for a keypress event, derived from the `event.characterValue`.

    Only available on keyPress events, and only for character (or ascii control) keys.

    See the `Keyboard Events Overview` for related APIs and more information on keyboard event handling in Smart GWT.

    Returns:
      Character the user entered. May be null for non-character keys.

  - ### getKeyEventCharacterValue

    public static int getKeyEventCharacterValue()
    Returns the numeric characterValue reported by the browser.

    Only available on keyPress events, and only for character (or ascii control) keys.

    See the `Keyboard Events Overview` for related APIs and more information on keyboard event handling in Smart GWT.

    Returns:
      Numeric character value reported by the browser (ASCII value of the key pressed)

  - ### getKeyEventCode

    public static String getKeyEventCode()
    Return the natively reported event.code value for the current event (keyboard) event.

    Note that `EventHandler.getReportedKey()` simply provides access to the `event.code` value reported by the browser. Smart GWT has no control over whether these values are accurate or vary by browser.

    See the `Keyboard Events Overview` for related APIs and more information on keyboard event handling in Smart GWT.

    Returns:
      Native event.code for the current keyboard event.

  - ### getKeyEventKey

    public static String getKeyEventKey()
    Return the natively reported event.key value for the current event.

    Note that this differs from `getKey()` in a couple of important ways:

    - The actual key values returned for specific keys differ in a number of ways. For example alpha characters keys are natively reported as either upper or lower case depending on what would actually by typed, (whereas `getKey()` is always uppercase for alpha keys) and the reported name for various 'named' keys (such as the arrow keys differ).
      The full set of native key names is available here, and the Smart GWT key names is available String.
    - `EventHandler.getKeyEventKey()` simply provides access to the `event.key` value. As such the reported values are generated by the browser itself and Smart GWT has no control over whether they may vary by browser, etc.

    See the `Keyboard Events Overview` for related APIs and more information on keyboard event handling in Smart GWT.

    Returns:
      Native event.key for the current keyboard event.

  - ### getNativeMouseTarget

    public static Element getNativeMouseTarget()
    Returns the natively reported target (or source) DOM element for the current mouse event. NOTE: Smart GWT cannot guarantee that the same element will be reported in all browser/platform configurations for all event types. If you wish to make use of this value, we recommend testing your use case in all target browser configurations.
    Returns:
      native DOM element over which the mouse event occurred

  - ### getReportedKey

    public static String getReportedKey()
    This method is a synonym for `getKeyEventKey()`
    Returns:
      Native event.key for the current keyboard event.

  - ### getTarget

    public static Canvas getTarget()
    Return the canvas that is the target of the mouse event. Returns null if no canvas found.
    Returns:
      event target canvas

  - ### getWheelDelta

    public static float getWheelDelta()
    Deprecated.
    in favor of `getWheelDeltaY()`
    Applies to `mouseWheel` events only. Returns a numeric value indicating how far the mouse wheel was rotated. This value will be positive if the user scrolled the mousewheel forward or up, or negative if scrolled in the other direction. For a standard wheel-mouse, an increment of 1 relates to the smallest possible rotation of the mouse wheel. For other scrolling devices, such as scroll gestures on a track pad, wheel delta may be reported in finer grained increments (causing this method to return a fractional value).

    Note that behavior for trackpad scroll-gestures may differ by browser, but where separate vertical and horizontal scroll information is available, this method refers to a vertical scroll gesture.

    Developers should also be aware that some browsers and operating systems allow the user to configure the sensitivity of the mouse wheel or trackpad, which may change this value.

    Returns:
      numeric value indicating how far the mouse wheel was rotated.

  - ### getWheelDeltaAsDouble

    public static double getWheelDeltaAsDouble()
    Deprecated.
    in favor of `getWheelDeltaY()`
    Applies to `mouseWheel` events only. Returns a numeric value indicating how far the mouse wheel was rotated. This value will be positive if the user scrolled the mousewheel forward or up, or negative if scrolled in the other direction. For a standard wheel-mouse, an increment of 1 relates to the smallest possible rotation of the mouse wheel. For other scrolling devices, such as scroll gestures on a track pad, wheel delta may be reported in finer grained increments (causing this method to return a fractional value).

    Note that behavior for trackpad scroll-gestures may differ by browser, but where separate vertical and horizontal scroll information is available, this method refers to a vertical scroll gesture.

    Developers should also be aware that some browsers and operating systems allow the user to configure the sensitivity of the mouse wheel or trackpad, which may change this value.

    Returns:
      numeric value indicating how far the mouse wheel was rotated.

  - ### getWheelDeltaX

    public static double getWheelDeltaX()
    Horizontal scroll delta reported by a `mouseWheel` event (such as a horizontal swipe on a track-pad).

    Returns a numeric value indicating how far the mouse wheel was rotated / the magnitude of the scroll gesture. This value will be positive if the user scrolled the mousewheel to the right, negative if scrolled in the other direction.

    Returns:
      numeric value indicating how far the mouse wheel was rotated.
    See Also:
      - `getWheelDeltaY()`

  - ### getWheelDeltaY

    public static double getWheelDeltaY()
    Applies to `mouseWheel` events only. Returns a numeric value indicating how far the mouse wheel was rotated. This value will be positive if the user scrolled the mousewheel forward or up, or negative if scrolled in the other direction. For a standard wheel-mouse, an increment of 1 relates to the smallest possible rotation of the mouse wheel. For other scrolling devices, such as scroll gestures on a track pad, wheel delta may be reported in finer grained increments (causing this method to return a fractional value).

    Note that behavior for trackpad scroll-gestures may differ by browser, but where separate vertical and horizontal scroll information is available, this method refers to a vertical scroll gesture.

    Developers should also be aware that some browsers and operating systems allow the user to configure the sensitivity of the mouse wheel or trackpad, which may change this value.

    Returns:
      numeric value indicating how far the mouse wheel was rotated.
    See Also:
      - `getWheelDeltaX()`

  - ### getX

    public static int getX()
    Return the page-relative X (horizontal) coordinate of an event.
    Returns:
      x-coordinate in page coordinate space

  - ### getY

    public static int getY()
    Return the page-relative Y (vertical) coordinate of an event.
    Returns:
      y-coordinate in page coordinate space

  - ### leftButtonDown

    public static Boolean leftButtonDown()
    Returns true if the left mouse button is being pressed.
    Returns:
      true == left button is down, false == up
    See Also:
      - `middleButtonDown()`
      - `rightButtonDown()`

  - ### middleButtonDown

    public static boolean middleButtonDown()
    Returns true if the middle mouse button is being pressed.

    Checking whether the middle mouse button is pressed can be used to implement power user shortcuts; however, note that many pointing devices do not have a middle button. Thus, the application should not require the user to press a middle button in order to perform some action.

    Returns:
      true if the middle mouse button is pressed; false otherwise.
    See Also:
      - `leftButtonDown()`
      - `rightButtonDown()`

  - ### rightButtonDown

    public static Boolean rightButtonDown()
    Returns true if the right mouse button is being pressed.
    Returns:
      true == right button is down, false == up
    See Also:
      - `leftButtonDown()`
      - `middleButtonDown()`

  - ### setDragOffset

    public static void setDragOffset(int offsetX, int offsetY)
    Sets the initial coordinate offset of the last event, typically a mouseDown or touchStart, from the drag target. For example, when grabbing and dragging a `Scrollbar` thumb with the mouse, you'd expect positive coordinates that reflect your position relative to the top, left corner of the thumb. If a drag tracker will be used, call `setDragTracker()` instead, which takes optional arguments `offsetX` and `offsetY` that act similarly to those passed to this method.

    Your canvas can call this method to set the initial drag offset to whatever you want like so:

             dragStart : function () {
                 isc.EventHandler.setDragOffset(5, 20);
             }

    Parameters:
      `offsetX` - initial x-offset for the drag
      `offsetY` - initial y-offset for the drag
    See Also:
      - `DragStartEvent`

  - ### setDragTrackerImage

    public static void setDragTrackerImage(String src)
    This API may be called to set the native HTML5 drag tracker image. The `x` and `y` parameters may be specified to affect the placement of the drag tracker image relative to the mouse cursor. The size of the drag tracker image is the intrinsic size of the image. Browsers may apply certain visual effects (such as a slight transparency) to this image.

    Can only be called during the `Canvas.dragStart()` event (or methods called during the handling of that event).

    NOTES:

    - Not supported in Opera 12.x or Safari.
    - For best results, this image should be preloaded. Otherwise, the image might not appear for the first drag using this image.
    - This API does not work in Chrome or Firefox on Windows 7 if the "Use visual styles on windows and buttons" setting is turned off.
    Parameters:
      `src` - image source. See `SCImgURL`
    See Also:
      - `SCImgURL`

  - ### setDragTrackerImage

    public static void setDragTrackerImage(String src, int x)
    See Also:
      - `setDragTrackerImage(java.lang.String)`

  - ### setDragTrackerImage

    public static void setDragTrackerImage(String src, int x, int y)
    This API may be called to set the native HTML5 drag tracker image. The `x` and `y` parameters may be specified to affect the placement of the drag tracker image relative to the mouse cursor. The size of the drag tracker image is the intrinsic size of the image. Browsers may apply certain visual effects (such as a slight transparency) to this image.

    Can only be called during the `Canvas.dragStart()` event (or methods called during the handling of that event).

    NOTES:

    - Not supported in Opera 12.x or Safari.
    - For best results, this image should be preloaded. Otherwise, the image might not appear for the first drag using this image.
    - This API does not work in Chrome or Firefox on Windows 7 if the "Use visual styles on windows and buttons" setting is turned off.
    Parameters:
      `src` - image source. See `SCImgURL`
      `x` - offset-x from the mouse cursor
      `y` - offset-y from the mouse cursor

  - ### shiftKeyDown

    public static Boolean shiftKeyDown()
    Return true if the shift key is being held down. Note that this is only set reliably for keyboard events.
    Returns:
      true == shift key is down

  - ### targetIsMasked

    public static Boolean targetIsMasked(Canvas target)
    Return whether this Canvas is masked by a clickMask (see `Canvas.showClickMask()`).
    Parameters:
      `target` - widget to check.
    Returns:
      true if masked, false if not masked.

  - ### setDragTracker

    public static void setDragTracker(String html)
    Set the HTML for the drag tracker that follows the mouse during a drag and drop interaction.

    Your canvas can use this routine to set the drag tracker to whatever HTML you want like so:

            dragStart : function
         () {        isc.EventHandler.setDragTracker('Your contents here');    }

    Parameters:
      `html` - HTML for the tracker

  - ### setDragTracker

    public static void setDragTracker(String html, int newWidth, int newHeight, int offsetX, int offsetY)
    Set the HTML for the drag tracker that follows the mouse during a drag and drop interaction.

    Your canvas can use this routine to set the drag tracker to whatever HTML you want like so:

            dragStart : function
         () {        isc.EventHandler.setDragTracker('Your contents here');    }

    Parameters:
      `html` - HTML for the tracker
      `newWidth` - new width for the tracker
      `newHeight` - new height for the tracker
      `offsetX` - x-offset for the tracker
      `offsetY` - y-offset for the tracker

  - ### getDragRect

    public static Rectangle getDragRect()
    During a drag with dragAppearance of either "target" or "outline", returns the page-relative coordinates of whatever element is being dragged. Calling this method allows you to write drag and drop logic that works identically even if dragAppearance is subsequently changed.
    Returns:
      lobal (page-relative) coordinates and size of the dragged element, as a 4-element array [left,top,width,height], or null if not dragging

  - ### getMouseDownX

    public static Integer getMouseDownX()
    Return the page-relative X (horizontal) coordinate of an event.
    Returns:
      x-coordinate in page coordinate space

  - ### getMouseDownY

    public static Integer getMouseDownY()
    Return the page-relative Y (vertical) coordinate of an event.
    Returns:
      y-coordinate in page coordinate space

  - ### getNativeDragData

    public static Object getNativeDragData()

  - ### setNativeDragData

    public static void setNativeDragData(Object data)

  - ### setNativeDragData

    public static void setNativeDragData(Object data, String strData)

  - ### getKey

    public static String getKey()
    Return the name of the key for the event passed in. Note that this is only set reliably for keyboard events.

         Strings to identify the various keys on the keyboard.

         For alpha keys, the single (uppercase) character value is used, such as "Q"
         For Numeric keys, the number is used as in a single character string, like "1"
         Function keys are identified as "f1" - "f12"
         Non alpha-numeric character keys (such as the key for "[" / "{") are identified by their unmodified character value (the value obtained by hitting the key without holding shift down), by default - exceptions are listed below.
         Additional key names:
         - Space
         - Tab
         - Enter
         - Escape
         - Backspace
         - Insert
         - Delete
         - Arrow_Up
         - Arrow_Down
         - Arrow_Left
         - Arrow_Right
         - Home
         - End
         - Page_Up
         - Page_Down
         - Shift
         - Ctrl
         - Alt
         [Note: Some keys may not be available for capture on every platform]

    Returns:
      the key name
    See Also:
      - `KeyNames`