java.awt.event Documentation Differences

This file contains all the changes in documentation in the package java.awt.event as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

An event which indicates that a keystroke occurred in a component.

This low-level event is generated by a component object (such as a text field) when a key is pressed released or typed. The event is passed to every KeyListener or KeyAdapter object which registered to receive such events using the component's addKeyListener method. (KeyAdapter objects implement the KeyListener interface.) Each such listener object gets this KeyEvent when the event occurs.

"Key typed" events are higher-level and generally do not depend on the platform or keyboard layout. They are generated when a Unicode character is entered and are the preferred way to find out about character input. In the simplest case a key typed event is produced by a single key press (e.g. 'a'). Often however characters are produced by series of key presses (e.g. 'shift' + 'a') and the mapping from key pressed events to key typed events may be many-to-one or many-to-many. Key releases are not usually necessary to generate a key typed event but there are some cases where the key typed event is not generated until a key is released (e.g. entering ASCII sequences via the Alt-Numpad method in Windows). No key typed events are generated for keys that don't generate Unicode characters (e.g. action keys modifier keys etc.). The getKeyChar method always returns a valid Unicode character or CHAR_UNDEFINED. For key pressed and key released events the getKeyCode method returns the event's keyCode. For key typed events the getKeyCode method always returns VK_UNDEFINED.

"Key pressed" and "key released" events are lower-level and depend on the platform and keyboard layout. They are generated whenever a key is pressed or released and are the only way to find out about keys that don't generate character input (e.g. action keys modifier keys etc.). The key being pressed or released is indicated by the getKeyCode method which returns a virtual key code.

Virtual key codes are used to report which keyboard key has been pressed rather than a character generated by the combination of one or more keystrokes (such as "A" which comes from shift and "a").

For example pressing the Shift key will cause a KEY_PRESSED event with a VK_SHIFT keyCode while pressing the 'a' key will result in a VK_A keyCode. After the 'a' key is released a KEY_RELEASED event will be fired with VK_A. Separately a KEY_TYPED event with a keyChar value of 'A' is generated.

Notes:

• Key combinations which do not result in Unicode characters such as action keys like F1 and the HELP key do not generate KEY_TYPED events.
• Not all keyboards or systems are capable of generating all virtual key codes. No attempt is made in Java to artificially generate these keys.
• Virtual key codes do not identify a physical key they depend on the platform and keyboard layout. For example the key that on a Windows U.S. keyboard layout generates VK_Q generates VK_A on a Windows French keyboard layout.
• In order to support the platform-independent handling of action keys the Java platform uses a few additional virtual key constants for functions that would otherwise have to be recognized by interpreting virtual key codes and modifiers. For example for Japanese Windows keyboards VK_ALL_CANDIDATES is returned instead of VK_CONVERT with the ALT modifier.

WARNING: Aside from those keys that are defined by the Java language (VK_ENTER VK_BACK_SPACE and VK_TAB) do not rely on the values of the VK_ constants. Sun reserves the right to change these values as needed to accomodate a wider range of keyboards in the future. @author Carl Quinn @author Amy Fowler @author Norbert Lindenberg @version 1.58 1260 04/0325/0102 @see KeyAdapter @see KeyListener @see Tutorial: Writing a Key Listener @see Reference: The Java Class Libraries (update file) @since 1.1

An event which indicates that a mouse action occurred in a component. A mouse action is considered to occur in a particular component if and only if the mouse cursor is over the unobscured part of the component's bounds when the action happens. Component bounds can be obscurred by the visible component's children or by a menu or by a top-level window. This event is used both for mouse events (click enter exit) and mouse motion events (moves and drags).

This low-level event is generated by a component object for:

• Mouse Events
  • a mouse button is pressed
  • a mouse button is released
  • a mouse button is clicked (pressed and released)
  • the mouse cursor enters the unobscured part of component's geometry
  • the mouse cursor exits the unobscured part of component's geometry
• Mouse Motion Events
  • the mouse is moved
  • the mouse is dragged

A MouseEvent object is passed to every MouseListener or MouseAdapter object which is registered to receive the "interesting" mouse events using the component's addMouseListener method. (MouseAdapter objects implement the MouseListener interface.) Each such listener object gets a MouseEvent containing the mouse event.

A MouseEvent object is also passed to every MouseMotionListener or MouseMotionAdapter object which is registered to receive mouse motion events using the component's addMouseMotionListener method. (MouseMotionAdapter objects implement the MouseMotionListener interface.) Each such listener object gets a MouseEvent containing the mouse motion event.

When a mouse button is clicked events are generated and sent to the registered MouseListeners. The state of modal keys can be retrieved using InputEvent#getModifiers and InputEvent#getModifiersEx The button mask returned by InputEvent#getModifiers reflects only the button that changed state not the current state of all buttons. (Note: Due to overlap in the values of ALT_MASK/BUTTON2_MASK and META_MASK/BUTTON3_MASK this is not always true for mouse events involving modifier keys). To get the state of all buttons and modifier keys use InputEvent#getModifiersEx The button which has changed state is returned by MouseEvent#getButton

For example if the first mouse button is pressed events are sent in the following order:

 id  modifiers  button  MOUSE_PRESSED: BUTTON1_MASK BUTTON1 MOUSE_RELEASED: BUTTON1_MASK BUTTON1 MOUSE_CLICKED: BUTTON1_MASK BUTTON1 

When multiple mouse buttons are pressed each press release and click results in a separate event.

For example if the user presses button 1 followed by button 2 and then releases them in the same order the following sequence of events is generated:

 id  modifiers  button  MOUSE_PRESSED: BUTTON1_MASK BUTTON1 MOUSE_PRESSED: BUTTON2_MASK BUTTON2 MOUSE_RELEASED: BUTTON1_MASK BUTTON1 MOUSE_CLICKED: BUTTON1_MASK BUTTON1 MOUSE_RELEASED: BUTTON2_MASK BUTTON2 MOUSE_CLICKED: BUTTON2_MASK BUTTON2 

If button 2 is released first the MOUSE_RELEASED/MOUSE_CLICKED pair for BUTTON2_MASK arrives first followed by the pair for BUTTON1_MASK.

MOUSE_DRAGGED events are delivered to the Component in which the mouse button was pressed until the mouse button is released (regardless of whether the mouse position is within the bounds of the Component). Due to platform-dependent Drag&Drop implementations MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation. In a multi-screen environment mouse drag events are delivered to the Component even if the mouse position is outside the bounds of the GraphicsConfiguration associated with that Component. However the reported position for mouse drag events in this case may differ from the actual mouse position:

• In a multi-screen environment without a virtual device:
  The reported coordinates for mouse drag events are clipped to fit within the bounds of the GraphicsConfiguration associated with the Component.
• In a multi-screen environment with a virtual device:
  The reported coordinates for mouse drag events are clipped to fit within the bounds of the virtual device associated with the Component.

@author Carl Quinn 1.4142 12/03/0112/02 @see MouseAdapter @see MouseListener @see MouseMotionAdapter @see MouseMotionListener @see MouseWheelListener @see Tutorial: Writing a Mouse Listener @see Tutorial: Writing a Mouse Motion Listener @see Reference: The Java Class Libraries (update file) @since 1.1

The "mouse dragged" event. This MouseMotionEventMouseEvent occurs when the mouse position changes while a mouse button is pressed.

The "mouse moved" event. This MouseMotionEventMouseEvent occurs when the mouse position changes.

An abstract adapter class for receiving mouse motion events. The methods in this class are empty. This class exists as convenience for creating listener objects.

Mouse motion events occur when a mouse is moved or dragged. (Many such events will be generated in a normal program. To track clicks and other mouse events use the MouseAdapter.)

Extend this class to create a MouseMotionEventMouseEvent listener and override the methods for the events of interest. (If you implement the MouseMotionListener interface you have to define all of the methods in it. This abstract class defines null methods for them all so you can only have to define methods for events you care about.)

Create a listener object using the extended class and then register it with a component using the component's addMouseMotionListener method. When the mouse is moved or dragged the relevant method in the listener object is invoked and the MouseEvent is passed to it. @author Amy Fowler @version 1.1213 12/03/0112/02 @see MouseEvent @see MouseMotionListener @see Tutorial: Writing a Mouse Motion Listener @see Reference: The Java Class Libraries (update file) @since 1.1

The listener interface for receiving mouse motion events on a component. (For clicks and other mouse events use the MouseListener.)

The class that is interested in processing a mouse motion event either implements this interface (and all the methods it contains) or extends the abstract MouseMotionAdapter class (overriding only the methods of interest).

The listener object created from that class is then registered with a component using the component's addMouseMotionListener method. A mouse motion event is generated when the mouse is moved or dragged. (Many such events will be generated). When a mouse motion event occurs the relevant method in the listener object is invoked and the MouseEvent is passed to it. @author Amy Fowler @version 1.12 1213 04/0317/0102 @see MouseMotionAdapter @see MouseEvent @see Tutorial: Writing a Mouse Motion Listener @see Reference: The Java Class Libraries (update file) @since 1.1

Invoked when the mouse buttoncursor has been moved ononto a component (withbut no buttons down)have been pushed.

An event which indicates that the mouse wheel was rotated in a component.

A wheel mouse is a mouse which has a wheel in place of the middle button. This wheel can be rotated towards or away from the user. Mouse wheels are most often used for scrolling though other uses are possible.

A MouseWheelEvent object is passed to every MouseWheelListener object which registered to receive the "interesting" mouse events using the component's addMouseWheelListener method. Each such listener object gets a MouseEvent containing the mouse event.

Due to the mouse wheel's special relationship to scrolling Components MouseWheelEvents are delivered somewhat differently than other MouseEvents. This is because while other MouseEvents usually affect a change on the Component directly under the mouse cursor (for instance when clicking a button) MouseWheelEvents often have an effect away from the mouse cursor (moving the wheel while over a Component inside a ScrollPane should scroll one of the Scrollbars on the ScrollPane).

MouseWheelEvents start delivery from the Component underneath the mouse cursor. If MouseWheelEvents are not enabled on the Component the event is delivered to the first ancestor Container with MouseWheelEvents enabled. This will usually be a ScrollPane with wheel scrolling enabled. The source Component and x y coordinates will be relative to the event's final destination (the ScrollPane). This allows a complex GUI to be installed without modification into a ScrollPane and for all MouseWheelEvents to be delivered to the ScrollPane for scrolling.

Some AWT Components are implemented using native widgets which display their own scrollbars and handle their own scrolling. The particular Components for which this is true will vary from platform to platform. When the mouse wheel is moved over one of these Components the event is delivered straight to the native widget and not propagated to ancestors.

Platforms offer customization of the amount of scrolling that should take place when the mouse wheel is moved. The two most common settings are to scroll a certain number of "units" (commonly lines of text in a text-based component) or an entire "block" (similar to page-up/page-down). The MouseWheelEvent offers methods for conforming to the underlying platform settings. These platform settings can be changed at any time by the user. MouseWheelEvents reflect the most recent settings. @author Brent Christian @version 1.56 12/03/0115/02 @see MouseWheelListener @see java.awt.ScrollPane @see java.awt.ScrollPane#enableWheelScrollingsetWheelScrollingEnabled(boolean) @see javax.swing.JScrollPane @see javax.swing.JScrollPane#enableWheelScrollingsetWheelScrollingEnabled(boolean) @since 1.4