com.google.gwt.user.client
Class Event

java.lang.Object
  extended by com.google.gwt.core.client.JavaScriptObject
      extended by com.google.gwt.user.client.Event

public final class Event
extends JavaScriptObject

An opaque handle to a native DOM Event. An Event cannot be created directly. Instead, use the Event type when returning a native DOM event from JSNI methods. An Event passed back into JSNI becomes the original DOM event the Event was created from, and can be accessed in JavaScript code as expected. This is typically done by calling methods in the DOM class.


Field Summary
static int BUTTON_LEFT
          The left mouse button (used in DOM.eventGetButton(Event)).
static int BUTTON_MIDDLE
          The middle mouse button (used in DOM.eventGetButton(Event)).
static int BUTTON_RIGHT
          The right mouse button (used in DOM.eventGetButton(Event)).
static int FOCUSEVENTS
          A bit-mask covering both focus events (focus and blur).
static int KEYEVENTS
          A bit-mask covering all keyboard events (down, up, and press).
static int MOUSEEVENTS
          A bit-mask covering all mouse events (down, up, move, over, and out), but not click, dblclick, or wheel events.
static int ONBLUR
          Fired when an element loses keyboard focus.
static int ONCHANGE
          Fired when the value of an input element changes.
static int ONCLICK
          Fired when the user clicks on an element.
static int ONDBLCLICK
          Fired when the user double-clicks on an element.
static int ONERROR
          Fired when an image encounters an error.
static int ONFOCUS
          Fired when an element receives keyboard focus.
static int ONKEYDOWN
          Fired when the user depresses a key.
static int ONKEYPRESS
          Fired when the a character is generated from a keypress (either directly or through auto-repeat).
static int ONKEYUP
          Fired when the user releases a key.
static int ONLOAD
          Fired when an element (normally an IMG) finishes loading.
static int ONLOSECAPTURE
          Fired when an element that has mouse capture loses it.
static int ONMOUSEDOWN
          Fired when the user depresses a mouse button over an element.
static int ONMOUSEMOVE
          Fired when the mouse is moved within an element's area.
static int ONMOUSEOUT
          Fired when the mouse is moved out of an element's area.
static int ONMOUSEOVER
          Fired when the mouse is moved into an element's area.
static int ONMOUSEUP
          Fired when the user releases a mouse button over an element.
static int ONMOUSEWHEEL
          Fired when the user scrolls the mouse wheel over an element.
static int ONSCROLL
          Fired when a scrollable element's scroll offset changes.
static int UNDEFINED
          Error code returned by DOM.getEventXXX methods when the actual integer value is undefined.
 
Constructor Summary
protected Event()
          Not directly instantiable.
 
Method Summary
 void cancelBubble(boolean cancel)
          Cancels bubbling for the given event.
 boolean getAltKey()
          Gets whether the ALT key was depressed when the given event occurred.
 int getButton()
          Gets the mouse buttons that were depressed when the given event occurred.
 int getClientX()
          Gets the mouse x-position within the browser window's client area.
 int getClientY()
          Gets the mouse y-position within the browser window's client area.
 boolean getCtrlKey()
          Gets whether the CTRL key was depressed when the given event occurred.
static Event getCurrentEvent()
          Gets the current event that is being fired.
 Element getCurrentTarget()
          Gets the current target element of this event.
static int getEventsSunk(Element elem)
          TODO: doc.
 Element getFromElement()
          Gets the element from which the mouse pointer was moved (only valid for ONMOUSEOVER).
 int getKeyCode()
          Gets the key code associated with this event.
 boolean getMetaKey()
          Gets whether the META key was depressed when the given event occurred.
 int getMouseWheelVelocityY()
          Gets the velocity of the mouse wheel associated with the event along the Y axis.
 boolean getRepeat()
          Gets the key-repeat state of this event.
 int getScreenX()
          Gets the mouse x-position on the user's display.
 int getScreenY()
          Gets the mouse y-position on the user's display.
 boolean getShiftKey()
          Gets whether the shift key was depressed when the given event occurred.
 java.lang.String getString()
          Gets a string representation of this event.
 Element getTarget()
          Returns the element that was the actual target of the given event.
 Element getToElement()
          Gets the element to which the mouse pointer was moved (only valid for ONMOUSEOUT).
 java.lang.String getType()
          Gets the enumerated type of this event (as defined in Event).
 int getTypeInt()
          Gets the enumerated type of this event, as defined by ONCLICK, ONMOUSEDOWN, and so forth.
 void preventDefault()
          Prevents the browser from taking its default action for the given event.
static void sinkEvents(Element elem, int eventBits)
          TODO: doc.
 
Methods inherited from class com.google.gwt.core.client.JavaScriptObject
cast, createArray, createFunction, createObject, equals, hashCode, toString
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

BUTTON_LEFT

public static final int BUTTON_LEFT
The left mouse button (used in DOM.eventGetButton(Event)).

See Also:
Constant Field Values

BUTTON_MIDDLE

public static final int BUTTON_MIDDLE
The middle mouse button (used in DOM.eventGetButton(Event)).

See Also:
Constant Field Values

BUTTON_RIGHT

public static final int BUTTON_RIGHT
The right mouse button (used in DOM.eventGetButton(Event)).

See Also:
Constant Field Values

ONBLUR

public static final int ONBLUR
Fired when an element loses keyboard focus.

See Also:
Constant Field Values

ONCHANGE

public static final int ONCHANGE
Fired when the value of an input element changes.

See Also:
Constant Field Values

ONCLICK

public static final int ONCLICK
Fired when the user clicks on an element.

See Also:
Constant Field Values

ONDBLCLICK

public static final int ONDBLCLICK
Fired when the user double-clicks on an element.

See Also:
Constant Field Values

ONERROR

public static final int ONERROR
Fired when an image encounters an error.

See Also:
Constant Field Values

ONFOCUS

public static final int ONFOCUS
Fired when an element receives keyboard focus.

See Also:
Constant Field Values

ONKEYDOWN

public static final int ONKEYDOWN
Fired when the user depresses a key.

See Also:
Constant Field Values

ONKEYPRESS

public static final int ONKEYPRESS
Fired when the a character is generated from a keypress (either directly or through auto-repeat).

See Also:
Constant Field Values

ONKEYUP

public static final int ONKEYUP
Fired when the user releases a key.

See Also:
Constant Field Values

ONLOAD

public static final int ONLOAD
Fired when an element (normally an IMG) finishes loading.

See Also:
Constant Field Values

ONLOSECAPTURE

public static final int ONLOSECAPTURE
Fired when an element that has mouse capture loses it.

See Also:
Constant Field Values

ONMOUSEDOWN

public static final int ONMOUSEDOWN
Fired when the user depresses a mouse button over an element.

See Also:
Constant Field Values

ONMOUSEMOVE

public static final int ONMOUSEMOVE
Fired when the mouse is moved within an element's area.

See Also:
Constant Field Values

ONMOUSEOUT

public static final int ONMOUSEOUT
Fired when the mouse is moved out of an element's area.

See Also:
Constant Field Values

ONMOUSEOVER

public static final int ONMOUSEOVER
Fired when the mouse is moved into an element's area.

See Also:
Constant Field Values

ONMOUSEUP

public static final int ONMOUSEUP
Fired when the user releases a mouse button over an element.

See Also:
Constant Field Values

ONMOUSEWHEEL

public static final int ONMOUSEWHEEL
Fired when the user scrolls the mouse wheel over an element.

See Also:
Constant Field Values

ONSCROLL

public static final int ONSCROLL
Fired when a scrollable element's scroll offset changes.

See Also:
Constant Field Values

FOCUSEVENTS

public static final int FOCUSEVENTS
A bit-mask covering both focus events (focus and blur).

See Also:
Constant Field Values

KEYEVENTS

public static final int KEYEVENTS
A bit-mask covering all keyboard events (down, up, and press).

See Also:
Constant Field Values

MOUSEEVENTS

public static final int MOUSEEVENTS
A bit-mask covering all mouse events (down, up, move, over, and out), but not click, dblclick, or wheel events.

See Also:
Constant Field Values

UNDEFINED

public static final int UNDEFINED
Error code returned by DOM.getEventXXX methods when the actual integer value is undefined. For example, DOM.getEventKeyCode returns UNDEFINED for some non-keyboard events. For some events, some browsers return undefined while others return data for certain events.

See Also:
Constant Field Values
Constructor Detail

Event

protected Event()
Not directly instantiable. Subclasses should also define a protected no-arg constructor to prevent client code from directly instantiating the class.

Method Detail

getCurrentEvent

public static Event getCurrentEvent()
Gets the current event that is being fired. The current event is only available within the lifetime of the onBrowserEvent function. Once the onBrowserEvent method returns, the current event is reset to null.

Returns:
the current event

getEventsSunk

public static int getEventsSunk(Element elem)
TODO: doc.


sinkEvents

public static void sinkEvents(Element elem,
                              int eventBits)
TODO: doc.


cancelBubble

public final void cancelBubble(boolean cancel)
Cancels bubbling for the given event. This will stop the event from being propagated to parent elements.

Parameters:
cancel - true to cancel bubbling

getAltKey

public final boolean getAltKey()
Gets whether the ALT key was depressed when the given event occurred.

Returns:
true if ALT was depressed when the event occurred

getButton

public final int getButton()
Gets the mouse buttons that were depressed when the given event occurred.

Returns:
a bit-field, defined by BUTTON_LEFT, BUTTON_MIDDLE, and BUTTON_RIGHT

getClientX

public final int getClientX()
Gets the mouse x-position within the browser window's client area.

Returns:
the mouse x-position

getClientY

public final int getClientY()
Gets the mouse y-position within the browser window's client area.

Returns:
the mouse y-position

getCtrlKey

public final boolean getCtrlKey()
Gets whether the CTRL key was depressed when the given event occurred.

Returns:
true if CTRL was depressed when the event occurred

getCurrentTarget

public final Element getCurrentTarget()
Gets the current target element of this event. This is the element whose listener fired last, not the element which fired the event initially.

Returns:
the event's current target element

getFromElement

public final Element getFromElement()
Gets the element from which the mouse pointer was moved (only valid for ONMOUSEOVER).

Returns:
the element from which the mouse pointer was moved

getKeyCode

public final int getKeyCode()
Gets the key code associated with this event.

For ONKEYPRESS, this method returns the Unicode value of the character generated. For ONKEYDOWN and ONKEYUP, it returns the code associated with the physical key.

Returns:
the Unicode character or key code.
See Also:
KeyboardListener

getMetaKey

public final boolean getMetaKey()
Gets whether the META key was depressed when the given event occurred.

Returns:
true if META was depressed when the event occurred

getMouseWheelVelocityY

public final int getMouseWheelVelocityY()
Gets the velocity of the mouse wheel associated with the event along the Y axis.

The velocity of the event is an artifical measurement for relative comparisons of wheel activity. It is affected by some non-browser factors, including choice of input hardware and mouse acceleration settings. The sign of the velocity measurement agrees with the screen coordinate system; negative values are towards the origin and positive values are away from the origin. Standard scrolling speed is approximately ten units per event.

Returns:
The velocity of the mouse wheel.

getRepeat

public final boolean getRepeat()
Gets the key-repeat state of this event.

Returns:
true if this key event was an auto-repeat

getScreenX

public final int getScreenX()
Gets the mouse x-position on the user's display.

Returns:
the mouse x-position

getScreenY

public final int getScreenY()
Gets the mouse y-position on the user's display.

Returns:
the mouse y-position

getShiftKey

public final boolean getShiftKey()
Gets whether the shift key was depressed when the given event occurred.

Returns:
true if shift was depressed when the event occurred

getString

public final java.lang.String getString()
Gets a string representation of this event. We do not override JavaScriptObject.toString() because it is final in JavaScriptObject.

Returns:
the string representation of this event

getTarget

public final Element getTarget()
Returns the element that was the actual target of the given event.

Returns:
the target element

getToElement

public final Element getToElement()
Gets the element to which the mouse pointer was moved (only valid for ONMOUSEOUT).

Returns:
the element to which the mouse pointer was moved

getType

public final java.lang.String getType()
Gets the enumerated type of this event (as defined in Event).

Returns:
the event's enumerated type

getTypeInt

public final int getTypeInt()
Gets the enumerated type of this event, as defined by ONCLICK, ONMOUSEDOWN, and so forth.

Returns:
the event's enumerated type

preventDefault

public final void preventDefault()
Prevents the browser from taking its default action for the given event.