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

Event Attributes

In hosted mode, most accessors (eg. EventgetKeyCode() and getButton()) assert that the requested attribute is reliable across all supported browsers. This means that attempting to retrieve an attribute for an Event that does not support that attribute will throw an AssertionError. For example, an Event of type ONCLICK will throw an AssertionError if you attempt to get the mouse button that was clicked using getButton() because the mouse button attribute is not defined for ONCLICK on Internet Explorer.


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 ONCONTEXTMENU
          Fired when the user requests an element's context menu (usually by right-clicking).
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
          Deprecated. 
 
Constructor Summary
protected Event()
          Not directly instantiable.
 
Method Summary
static void addEventPreview(EventPreview preview)
          Adds an event preview to the preview stack.
 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)
          Gets the current set of events sunk by a given element.
 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 releaseCapture(Element elem)
          Releases mouse capture on the given element.
static void removeEventPreview(EventPreview preview)
          Removes an element from the preview stack.
static void setCapture(Element elem)
          Sets mouse-capture on the given element.
static void sinkEvents(Element elem, int eventBits)
          Sets the current set of events sunk by a given element.
 
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

ONCONTEXTMENU

public static final int ONCONTEXTMENU
Fired when the user requests an element's context menu (usually by right-clicking). Note that not all browsers will fire this event (notably Opera, as of 9.5).

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

@Deprecated
public static final int UNDEFINED
Deprecated. 
Value returned by accessors when the actual integer value is undefined. In hosted mode, most accessors assert that the requested attribute is reliable across all supported browsers.

See Also:
Event, 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

addEventPreview

public static void addEventPreview(EventPreview preview)
Adds an event preview to the preview stack. As long as this preview remains on the top of the stack, it will receive all events before they are fired to their listeners. Note that the event preview will receive all events, including those received due to bubbling, whereas normal event handlers only receive explicitly sunk events.

Parameters:
preview - the event preview to be added to the stack.

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)
Gets the current set of events sunk by a given element.

Parameters:
elem - the element whose events are to be retrieved
Returns:
a bitfield describing the events sunk on this element (its possible values are described in Event)

releaseCapture

public static void releaseCapture(Element elem)
Releases mouse capture on the given element. Calling this method has no effect if the element does not currently have mouse capture.

Parameters:
elem - the element to release capture
See Also:
setCapture(Element)

removeEventPreview

public static void removeEventPreview(EventPreview preview)
Removes an element from the preview stack. This element will no longer capture events, though any preview underneath it will begin to do so.

Parameters:
preview - the event preview to be removed from the stack

setCapture

public static void setCapture(Element elem)
Sets mouse-capture on the given element. This element will directly receive all mouse events until releaseCapture(Element) is called on it.

Parameters:
elem - the element on which to set mouse capture

sinkEvents

public static void sinkEvents(Element elem,
                              int eventBits)
Sets the current set of events sunk by a given element. These events will be fired to the nearest EventListener specified on any of the element's parents.

Parameters:
elem - the element whose events are to be retrieved
eventBits - a bitfield describing the events sunk on this element (its possible values are described in Event)

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()
                        throws java.lang.AssertionError
Gets whether the ALT key was depressed when the given event occurred.

Returns:
true if ALT was depressed when the event occurred
Throws:
java.lang.AssertionError - if event type is not one of MOUSEEVENTS, ONCLICK, ONDBLCLICK, KEYEVENTS, or ONCONTEXTMENU

getButton

public final int getButton()
                    throws java.lang.AssertionError
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
Throws:
java.lang.AssertionError - if event type is not one of ONMOUSEDOWN or ONMOUSEUP

getClientX

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

Returns:
the mouse x-position
Throws:
java.lang.AssertionError - if event type is not one of MOUSEEVENTS, ONCLICK, ONDBLCLICK, ONMOUSEWHEEL, or ONCONTEXTMENU

getClientY

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

Returns:
the mouse y-position
Throws:
java.lang.AssertionError - if event type is not one of MOUSEEVENTS, ONCLICK, ONDBLCLICK, ONMOUSEWHEEL, or ONCONTEXTMENU

getCtrlKey

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

Returns:
true if CTRL was depressed when the event occurred
Throws:
java.lang.AssertionError - if event type is not one of MOUSEEVENTS, ONCLICK, ONDBLCLICK, KEYEVENTS, or ONCONTEXTMENU

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()
                             throws java.lang.AssertionError
Gets the element from which the mouse pointer was moved (only valid for ONMOUSEOVER).

Returns:
the element from which the mouse pointer was moved
Throws:
java.lang.AssertionError - if event type is not one of ONMOUSEOVER or ONMOUSEOUT

getKeyCode

public final int getKeyCode()
                     throws java.lang.AssertionError
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.
Throws:
java.lang.AssertionError - if event type is not one of KEYEVENTS
See Also:
KeyboardListener

getMetaKey

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

Returns:
true if META was depressed when the event occurred
Throws:
java.lang.AssertionError - if event type is not one of MOUSEEVENTS, ONCLICK, ONDBLCLICK, KEYEVENTS, or ONCONTEXTMENU

getMouseWheelVelocityY

public final int getMouseWheelVelocityY()
                                 throws java.lang.AssertionError
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.
Throws:
java.lang.AssertionError - if event type is not ONMOUSEWHEEL

getRepeat

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

Returns:
true if this key event was an auto-repeat
Throws:
java.lang.AssertionError - if event type is not ONKEYDOWN

getScreenX

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

Returns:
the mouse x-position
Throws:
java.lang.AssertionError - if event type is not one of MOUSEEVENTS, ONMOUSEWHEEL, ONCLICK, ONDBLCLICK, or ONCONTEXTMENU

getScreenY

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

Returns:
the mouse y-position
Throws:
java.lang.AssertionError - if event type is not one of MOUSEEVENTS, ONMOUSEWHEEL, ONCLICK, ONDBLCLICK, or ONCONTEXTMENU

getShiftKey

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

Returns:
true if shift was depressed when the event occurred
Throws:
java.lang.AssertionError - if event type is not one of MOUSEEVENTS, ONCLICK, ONDBLCLICK, KEYEVENTS, or ONCONTEXTMENU

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()
                           throws java.lang.AssertionError
Gets the element to which the mouse pointer was moved (only valid for ONMOUSEOUT).

Returns:
the element to which the mouse pointer was moved
Throws:
java.lang.AssertionError - if event type is not one of ONMOUSEOVER or ONMOUSEOUT

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.