com.smartgwt.client.util
Class EventHandler

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

public class EventHandler
extends Object

The ISC system provides a predictable cross-browser event-handling mechanism for ISC widgets. Events can be handled both at the page level (i.e., globally), and at the level of individual widgets.

With the exception of a few page-specific events ('load', 'unload', 'idle' and 'resize'), events are processed in the following sequence:

1. The event is sent to any global (page-level) event handlers. These handlers can cancel further propagation of the event by returning false. You can register to listen for any of the events linked in the seeAlso section (below) by calling Page.setEvent method.

2. If the event occurred on a form element or a link, it is passed on to the browser so that the element will perform its default action. No widget receives the event.

3. If the event occurred on an enabled widget (but not on a form element or link inside the 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. Interceptable events are defined in the "widgetEvents" section of Canvas.

4. 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 returning false. 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. In brief, the ISC event model offers the best features of browser event models:

Note: Canceling propagation of an event may cancel its side effects as well, including the generation of other (synthetic) events. For example, if a global mouseDown handler returns false, drag-and-drop events will not be generated. Specific effects are discussed in the descriptions of the various events in the following sections.

Smart GWT 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.

You can use isc.Event as an alias for isc.EventHandler.

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

Constructor Summary
EventHandler()
           
 
Method Summary
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 String getKey()
          Return the name of the key for the event passed in.
static String getKeyEventCharacter()
          Return the character for the current key being pressed.
static int getKeyEventCharacterValue()
          Returns the numeric characterValue reported by the browser.
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 Canvas getTarget()
          Return the canvas that is the target of the mouse event.
static float getWheelDelta()
          Deprecated. in favor of EventHandler.getWheelDeltaY
static double getWheelDeltaAsDouble()
          Deprecated. in favor of EventHandler.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 rightButtonDown()
          Returns true if the right mouse button is being pressed.
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 Detail

EventHandler

public EventHandler()
Method Detail

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()

getKeyEventCharacter

public static String getKeyEventCharacter()
Return the character for the current key being pressed. Note that this is only set reliably for keyPress events on character keys.

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

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

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

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

rightButtonDown

public static Boolean rightButtonDown()
Returns true if the right mouse button is being pressed.

Returns:
true == right button is down, false == up

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:

Parameters:
src - image source. See SCImgURL

setDragTrackerImage

public static void setDragTrackerImage(String src,
                                       int x)
See Also:
EventHandler#setDragTrackerImage()}

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:

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