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.

The listener interface for receiving notification of events dispatched to objects that are instances of Component or MenuComponent or their subclasses. Unlike the other EventListeners in this package AWTEventListeners passively observe events being dispatched in the AWT system-wide. Most applications should never use this class; applications which might use AWTEventListeners include event recorders for automated testing and facilities such as the Java Accessibility package.

The class that is interested in monitoring AWT events implements this interface and the object created with that class is registered with the Toolkit using the Toolkit's addAWTEventListener method. When an event is dispatched anywhere in the AWT that object's eventDispatcheded method is invoked. @see java.awt.AWTEvent @see java.awt.Toolkit#addAWTEventListener @see java.awt.Toolkit#removeAWTEventListener @author Fred Ecks @version 1.6 027 12/0203/0001 @since 1.2

A semantic event which indicates that a component-defined action occured. This high-level event is generated by a component (such as a Button) when the component-specific action occurs (such as being pressed). The event is passed to every every ActionListener object that registered to receive such events using the component's addActionListener method.

The object that implements the ActionListener interface gets this ActionEvent when the event occurs. The listener is therefore spared the details of processing individual mouse movements and mouse clicks and can instead process a "meaningful" (semantic) event like "button pressed". @see ActionListener @see Tutorial: Java 1.1 Event Model @see Reference: The Java Class Libraries (update file) @author Carl Quinn @version 1.21 0224 12/0203/0001 @since 1.1

Constructs an ActionEvent object.

Note that passing in an invalid id results in unspecified behavior. @param source the object that originated the event @param id an integer that identifies the event @param command a string that may specify a command (possibly one of several) associated with the event

Constructs an ActionEvent object with modifier keys.

Note that passing in an invalid id results in unspecified behavior. @param source the object that originated the event @param id an integer that identifies the event @param command a string that may specify a command (possibly one of several) associated with the event @param modifiers the modifier keys held down during this action

Returns the modifier keys held down during this action event. @return the integerbitwise-or sum of the modifier constants

The listener interface for receiving action events. The class that is interested in processing an action event implements this interface and the object created with that class is registered with a component using the component's addActionListener method. When the action event occurs that object's actionPerformed method is invoked. @see ActionEvent @see Tutorial: Java 1.1 Event Model @see Reference: The Java Class Libraries (update file) @author Carl Quinn @version 1.13 0214 12/0203/0001 @since 1.1

The adjustment event emitted by Adjustable objects. @see java.awt.Adjustable @see AdjustmentListener @author Amy Fowler @version 1.21 0224 12/0203/0001 @since 1.1

Constructs aan AdjustmentEvent object with the specified Adjustable source event type adjustment type and value. type

Note andthat valuepassing in an invalid id results in unspecified behavior. @param source the Adjustable object where the event originated @param id the event type @param type the adjustment type @param value the current value of the adjustment

Returns the Adjustable object where this event originated. @return the Adjustable object where this event originated

Returns the type of adjustment which caused the value changed event. It will have one of the following values:

• {@seelink #UNIT_INCREMENT}
• {@seelink #UNIT_DECREMENT}
• {@seelink #BLOCK_INCREMENT}
• {@seelink #BLOCK_DECREMENT}
• {@seelink #TRACK}

@return one of the adjustment values listed above

Returns the current value in the adjustment event. @return the current value in the adjustment event

The listener interface for receiving adjustment events. @author Amy Fowler @version 1.11 0212 12/0203/0001 @since 1.1

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

Extend this class to create a ComponentEvent listener and override the methods for the events of interest. (If you implement the ComponentListener 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 your class and then register it with a component using the component's addComponentListener method. When the component's size location or visibility changes the relevant method in the listener object is invoked and the ComponentEvent is passed to it. @see ComponentEvent @see ComponentListener @see Tutorial: Writing a Component Listener @see Reference: The Java Class Libraries (update file) @author Carl Quinn @version 1.13 0214 12/0203/0001 @since 1.1

A low-level event which indicates that a component moved changed size or changed visibility (also the root class for the other component-level events).

Component events are provided for notification purposes ONLY; The AWT will automatically handle component moves and resizes internally so that GUI layout works properly regardless of whether a program is receiving these events or not.

In addition to serving as the base class for other component-related events (InputEvent FocusEvent WindowEvent ContainerEvent) this class defines the events that indicate changes in a component's size position or visibility.

This low-level event is generated by a component object (such as a List) when the component is moved resized rendered invisible or made visible again. The event is passed to every ComponentListener or ComponentAdapter object which registered to receive such events using the component's addComponentListener method. (ComponentAdapter objects implement the ComponentListener interface.) Each such listener object gets this ComponentEvent when the event occurs. @see ComponentAdapter @see ComponentListener @see Tutorial: Writing a Component Listener @see Reference: The Java Class Libraries (update file) @author Carl Quinn @version 1.21 0224 12/0203/0001 @since 1.1

Constructs a ComponentEvent object.

Note that passing in an invalid id results in unspecified behavior. @param source the Component object that originated the event @param id an integer indicating the type of event

Returns the originator of the event. @return the Component object that originated the event or null if the object is not a Component.

The listener interface for receiving component events. The class that is interested in processing a component event either implements this interface (and all the methods it contains) or extends the abstract ComponentAdapter class (overriding only the methods of interest). The listener object created from that class is then registered with a component using the component's addComponentListener method. When the component's size location or visibility changes the relevant method in the listener object is invoked and the ComponentEvent is passed to it.

Component events are provided for notification purposes ONLY; The AWT will automatically handle component moves and resizes internally so that GUI layout works properly regardless of whether a program registers a ComponentListener or not. @see ComponentAdapter @see ComponentEvent @see Tutorial: Writing a Component Listener @see Reference: The Java Class Libraries (update file) @author Carl Quinn @version 1.13 0214 12/0203/0001 @since 1.1

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

Extend this class to create a ContainerEvent listener and override the methods for the events of interest. (If you implement the ContainerListener 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 addContainerListener method. When the container's contents change because a component has been added or removed the relevant method in the listener object is invoked and the ContainerEvent is passed to it. @see ContainerEvent @see ContainerListener @see Tutorial: Writing a Container Listener @see Reference: The Java Class Libraries (update file) @author Amy Fowler @version 1.9 0210 12/0203/0001 @since 1.1

A low-level event which indicates that a container's contents changed because a component was added or removed.

Container events are provided for notification purposes ONLY; The AWT will automatically handle changes to the containers contents internally so that the program works properly regardless of whether the program is receiving these events or not.

This low-level event is generated by a container object (such as a Panel) when a component is added to it or removed from it. The event is passed to every ContainerListener or ContainerAdapter object which registered to receive such events using the component's addContainerListener method. (ContainerAdapter objects implement the ContainerListener interface.) Each such listener object gets this ContainerEvent when the event occurs. @see ContainerAdapter @see ContainerListener @see Tutorial: Writing a Container Listener @see Reference: The Java Class Libraries (update file) @author Tim Prinzing @author Amy Fowler @version 1.11 0213 12/0203/0001 @since 1.1

Constructs a ContainerEvent object.

Note that passing in an invalid id results in unspecified behavior. @param source the Component object (container) that originated the event @param id an integer indicating the type of event @param child the component that was added or removed

The listener interface for receiving container events. The class that is interested in processing a container event either implements this interface (and all the methods it contains) or extends the abstract ContainerAdapter class (overriding only the methods of interest). The listener object created from that class is then registered with a component using the component's addContainerListener method. When the container's contents change because a component has been added or removed the relevant method in the listener object is invoked and the ContainerEvent is passed to it.

Container events are provided for notification purposes ONLY; The AWT will automatically handle add and remove operations internally so the program works properly regardless of whether the program registers a ComponentListener or not. @see ContainerAdapter @see ContainerEvent @see Tutorial: Writing a Container Listener @see Reference: The Java Class Libraries (update file) @author Tim Prinzing @author Amy Fowler @version 1.8 029 12/0203/0001 @since 1.1

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

Extend this class to create a FocusEvent listener and override the methods for the events of interest. (If you implement the FocusListener 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 addFocusListener method. When the component gains or loses the keyboard focus the relevant method in the listener object is invoked and the FocusEvent is passed to it. @see FocusEvent @see FocusListener @see Tutorial: Writing a Focus Listener @see Reference: The Java Class Libraries (update file) @author Carl Quinn @version 1.13 0214 12/0203/0001 @since 1.1

A low-level event which indicates that a componentComponent has gained or lost the keyboardinput focus. This low-level event is generated by a componentComponent (such as a text fieldTextField). The event is passed to every FocusListener or FocusAdapter object which registered to receive such events using the componentComponent's addFocusListener method. ( FocusAdapter objects implement the FocusListener interface.) Each such listener object gets this FocusEvent when the event occurs.

There are two levels of focus change events: permanent and temporary. Permanent focus change events occur when focus is directly moved from one componentComponent to another such as through callsa call to requestFocus() or as the user uses the TabTAB key to traverse componentsComponents. Temporary focus change events occur when focus is temporarily gained or lost for a componentComponent as the indirect result of another operation such as windowWindow deactivation or a scrollbarScrollbar drag. In this case the original focus state will automatically be restored once that operation is finished or for the case of windowWindow deactivation when the windowWindow is reactivated. Both permanent and temporary focus events are delivered using the FOCUS_GAINED and FOCUS_LOST event ids; the levelslevel may be distinguished in the event using the isTemporary() method. @see FocusAdapter @see FocusListener @see Tutorial: Writing a Focus Listener @see Reference: The Java Class Libraries (update file) @author Carl Quinn @author Amy Fowler @version 1.22 0225 12/0203/0001 @since 1.1

Constructs a FocusEvent object and identifies it as a permanent change in focus.

Note that passing in an invalid id results in unspecified behavior. @param source the Component that originated the event @param id an integer indicating the type of event

Constructs a FocusEvent object and identifies whether or not the change is temporary.

Note that passing in an invalid id results in unspecified behavior. @param source the Component that originated the event @param id an integer indicating the type of event @param temporary a boolean true if the focus change is temporary; false otherwise

Identifies the focus change event as temporary or permanent. @return a boolean value true if the focus change is temporary; false otherwise

This event indicates that the component gained the keyboardComponent is now the focus owner.

This event indicates that the component lostComponent is theno longer keyboardthe focus owner.

The listener interface for receiving keyboard focus events on a component. The class that is interested in processing a focus event either implements this interface (and all the methods it contains) or extends the abstract FocusAdapter class (overriding only the methods of interest). The listener object created from that class is then registered with a component using the component's addFocusListener method. When the component gains or loses the keyboard focus the relevant method in the listener object is invoked and the FocusEvent is passed to it. @see FocusAdapter @see FocusEvent @see Tutorial: Writing a Focus Listener @see Reference: The Java Class Libraries (update file) @author Carl Quinn @version 1.12 0213 12/0203/0001 @since 1.1

An abstract adapter class for receiving ancestor moved and resized events. The methods in this class are empty. This class exists as a convenience for creating listener objects.

Extend this class and override the method for the event of interest. (If you implement the HierarchyBoundsListener interface you have to define both methods in it. This abstract class defines null methods for them both so you only have to define the method for the event you care about.)

Create a listener object using your class and then register it with a Component using the Component's addHierarchyBoundsListener method. When the hierarchy to which the Component belongs changes by resize or movement of an ancestor the relevant method in the listener object is invoked and the HierarchyEvent is passed to it. @author David Mendenhall @version 1.4 025 12/0203/0001 @see HierarchyBoundsListener @see HierarchyEvent @since 1.3

The listener interface for receiving ancestor moved and resized events. The class that is interested in processing these events either implements this interface (and all the methods it contains) or extends the abstract HierarchyBoundsAdapter class (overriding only the method of interest). The listener object created from that class is then registered with a Component using the Component's addHierarchyBoundsListener method. When the hierarchy to which the Component belongs changes by the resizing or movement of an ancestor the relevant method in the listener object is invoked and the HierarchyEvent is passed to it.

Hierarchy events are provided for notification purposes ONLY; The AWT will automatically handle changes to the hierarchy internally so that GUI layout works properly regardless of whether a program registers an HierarchyBoundsListener or not. @author David Mendenhall @version 1.4 025 12/0203/0001 @see HierarchyBoundsAdapter @see HierarchyEvent @since 1.3

An event which indicates a change to the Component hierarchy to which a Component belongs.

• Hierarchy Change Events (HierarchyListener)
  • addition of an ancestor
  • removal of an ancestor
  • hierarchy made displayable
  • hierarchy made undisplayable
  • hierarchy shown on the screen (both visible and displayable)
  • hierarchy hidden on the screen (either invisible or undisplayable)
• Ancestor Reshape Events (HierarchyBoundsListener)
  • an ancestor was resized
  • an ancestor was moved

Hierarchy events are provided for notification purposes ONLY;. The AWT will automatically handle changes to the hierarchy internally so that GUI layout and displayability works properly regardless of whether a program is receiving these events or not.

This event is generated by a Container object (such as a Panel) when the Container is added removed moved or resized and passed down the hierarchy. It is also generated by a Component object when that object's addNotify removeNotify show or hide method is called. ANCESTOR_MOVED and ANCESTOR_RESIZED events are dispatched to every HierarchyBoundsListener or HierarchyBoundsAdapter object which registered to receive such events using the Component's addHierarchyBoundsListener method. (HierarchyBoundsAdapter objects implement the HierarchyBoundsListener interface.) HIERARCHY_CHANGED events are dispatched to every HierarchyListener object which registered to receive such events using the Component's addHierarchyListener method. Each such listener object gets this HierarchyEvent when the event occurs. @author David Mendenhall @version 1.59 0212/0203/0001 @see HierarchyListener @see HierarchyBoundsAdapter @see HierarchyBoundsListener @since 1.3

Constructs an HierarchyEvent object to identify a change in the Component hierarchy.

Note that passing in an invalid id results in unspecified behavior. @param source the Component object that originated the event @param id an integer indicating the type of event @param changed the Component at the top of the hierarchy which was changed @param changedParent the parent of changed. This; this may be the parent before or after the change depending on the type of change.

Constructs an HierarchyEvent object to identify a change in the Component hierarchy.

Note that passing in an invalid id results in unspecified behavior. @param source the Component object that originated the event @param id an integer indicating the type of event @param changed the Component at the top of the hierarchy which was changed @param changedParent the parent of changed. This; this may be the parent before or after the change depending on the type of change. @param changeFlags a bitmask which indicates the type(s) of HIERARCHY_CHANGED events represented in this event object

Returns the originator of the event. @return the Component object that originated the event or null if the object is not a Component.

AnThe event id indicating an ancestor-Container was moved.

AnThe event id indicating an ancestor-Container was resized.

TheIndicates that the HIERARCHY_CHANGED event was generated due to a change in the displayability of the hierarchy changed. To discern the current displayability of the hierarchy call Component.isDisplayable(). Displayability changes occur in response to explicit or implicit calls to Component.addNotify() and Component.removeNotify(). @see java.awt.Component#isDisplayable() @see java.awt.Component#addNotify() @see java.awt.Component#removeNotify()

AThe event id indicating that modification was made to the entire hierarchy tree.

The hierarchy changedIndicates that the throughHIERARCHY_CHANGED event was generated by a reparentreparenting operation.

TheIndicates that the HIERARCHY_CHANGED event was generated due to a change in the showing state of the hierarchy changed. To discern the current showing state of the hierarchy call Component.isShowing(). Showing state changes occur when either the displayability or visibility of the hierarchy occurs. Displayability changes occur in response to explicit or implicit calls to Component.addNotify() and Component.removeNotify(). Visibility changes occur in response to explicit or implicit calls to Component.show() and Component.hide(). @see java.awt.Component#isShowing() @see java.awt.Component#addNotify() @see java.awt.Component#removeNotify() @see java.awt.Component#show() @see java.awt.Component#hide()

The listener interface for receiving hierarchy changed events. The class that is interested in processing a hierarchy changed event should implement this interface. The listener object created from that class is then registered with a Component using the Component's addHierarchyListener method. When the hierarchy to which the Component belongs changes the hierarchyChanged method in the listener object is invoked and the HierarchyEvent is passed to it.

Hierarchy events are provided for notification purposes ONLY; The AWT will automatically handle changes to the hierarchy internally so that GUI layout displayability and visibility work properly regardless of whether a program registers a HierarchyListener or not. @author David Mendenhall @version 1.5 026 12/0203/0001 @see HierarchyEvent @since 1.3

The root event class for all component-level input events. Input events are delivered to listeners before they are processed normally by the source where they originated. This allows listeners and component subclasses to "consume" the event so that the source will not process them in their default manner. For example consuming mousePressed events on a Button component will prevent the Button from being activated. @author Carl Quinn @version 1.22 0227 12/0203/0001 @see KeyEvent @see KeyAdapter @see MouseEvent @see MouseAdapter @see MouseMotionAdapter @since 1.1

The alt key modifier constant. It is recommended that ALT_DOWN_MASK to be used instead.

The mouse button1 modifier constant. It is recommended that BUTTON1_DOWN_MASK to be used instead.

The mouse button2 modifier constant. It is recommended that BUTTON2_DOWN_MASK to be used instead.

The mouse button3 modifier constant. It is recommended that BUTTON3_DOWN_MASK to be used instead.

The control key modifier constant. It is recommended that CTRL_DOWN_MASK to be used instead.

The meta key modifier constant. It is recommended that META_DOWN_MASK to be used instead.

The shift key modifier constant. It is recommended that SHIFT_DOWN_MASK to be used instead.

Input method events contain information about text that is being composed using an input method. Whenever the text changes the input method sends an event. If the text component that's currently using the input method is an active client the event is dispatched to that component. Otherwise it is dispatched to a separate composition window.

The text included with the input method event consists of two parts: committed text and composed text. Either part may be empty. The two parts together replace any uncommitted composed text sent in previous events or the currently selected committed text. Committed text should be integrated into the text component's persistent data it will not be sent again. Composed text may be sent repeatedly with changes to reflect the user's editing operations. Committed text always precedes composed text. @author JavaSoft Asia/Pacific @version 1.16 0219 12/0203/0001 @since 1.2

Constructs an InputMethodEvent with the specified source component type text caret and visiblePosition.

The offsets of caret and visiblePosition are relative to the current composed text; that is the composed text within text if this is an INPUT_METHOD_TEXT_CHANGED event the composed text within the text of the preceding INPUT_METHOD_TEXT_CHANGED event otherwise. The time stamp for this event is initialized by invoking java.awt.EventQueue#getMostRecentEventTime() @param source Thethe object where the event originated. @param id Thethe event type. @param text Thethe combined committed and composed text committed text first.; Mustmust be null when the event type is CARET_POSITION_CHANGED; may be null for INPUT_METHOD_TEXT_CHANGED if there's no committed or composed text. @param committedCharacterCount Thethe number of committed characters in the text. @param caret the caret (a.k.a. insertion point).; Nullnull if there's no caret within current composed text. @param visiblePosition Thethe position that's most important to be visible.; Nullnull if there's no recommendation for a visible position within current composed text. @exception IllegalArgumentException if id is not in the range INPUT_METHOD_FIRST..INPUT_METHOD_LAST; or if id is CARET_POSITION_CHANGED and text is not null; or if committedCharacterCount is not in the range 0..(text.getEndIndex() - text.getBeginIndex())

Constructs an InputMethodEvent with the specified source component type caret and visiblePosition. The text is set to null committedCharacterCount to 0.

The offsets of caret and visiblePosition are relative to the current composed text; that is the composed text within the text of the preceding INPUT_METHOD_TEXT_CHANGED event if the event being constructed as a CARET_POSITION_CHANGED event. For an INPUT_METHOD_TEXT_CHANGED event without text caret and visiblePosition must be null. The time stamp for this event is initialized by invoking java.awt.EventQueue#getMostRecentEventTime() @param source Thethe object where the event originated. @param id Thethe event type. @param caret the caret (a.k.a. insertion point).; Nullnull if there's no caret within current composed text. @param visiblePosition Thethe position that's most important to be visible.; Nullnull if there's no recommendation for a visible position within current composed text @exception IllegalArgumentException if id is not in the range INPUT_METHOD_FIRST..INPUT_METHOD_LAST

The listener interface for receiving input method events. A text editing component has to install an input method event listener in order to work with input methods.

The text editing component also has to provide an instance of InputMethodRequests. @author JavaSoft Asia/Pacific @version 1.8 029 12/0203/0001 @see InputMethodEvent @see java.awt.im.InputMethodRequests @since 1.2

An event which executes the run() method on a Runnable when dispatched by the AWT event dispatcher thread. This class can be used as a reference implementation of ActiveEvent rather than declaring a new class and defining dispatch().

Instances of this class are placed on the EventQueue by calls to invokeLater and invokeAndWait. Client code can use this fact to write replacement functions for invokeLater and invokeAndWait without writing special-case code in any AWTEventListener objects. @author Fred Ecks @author David Mendenhall @version 1.9 0213 12/0203/0001 @see java.awt.ActiveEvent @see java.awt.EventQueue#invokeLater @see java.awt.EventQueue#invokeAndWait @see AWTEventListener @since 1.2

Constructs an InvocationEvent with the specified source which will execute the runnable's run() method when dispatched. @param source the Object that originated the event @param runnable the Runnable whose run() method will be executed

Constructs an InvocationEvent with the specified source which will execute the runnable's run() method when dispatched. If notifier is non-null notifyAll() will be called on it immediately after run() returns. @param source the Object that originated the event @param runnable the Runnable whose run() method will be executed @param notifier the Object whose notifyAll() method will be called after Runnable.run() has returned @param catchExceptions specifies whether dispatch() should catch Exception when executing the Runnable's run() method or should instead propagate those Exceptions to the EventDispatchThread's dispatch loop

Constructs an InvocationEvent with the specified source and ID which will execute the runnable's run() method when dispatched. If notifier is non-null notifyAll() will be called on it immediately after run() returns.

Note that passing in an invalid id results in unspecified behavior. @param source the Object that originated the event @param id the ID for the Eventevent @param runnable the Runnable whose run() method will be executed @param notifier the Object whose notifyAll() method will be called after Runnable.run() has returned @param catchExceptions specifies whether dispatch() should catch Exception when executing the Runnable's run() method or should instead propagate those Exceptions to the EventDispatchThread's dispatch loop