Component that it is tracking.
*
+ * The {@code action} field of any {@code DragGestureEvent} instance should take one of the following
+ * values:
+ * DragGestureEvent given the
- * DragGestureRecognizer firing this event,
- * an int representing
- * the user's preferred action, a Point
- * indicating the origin of the drag, and a List
- * of events that comprise the gesture.
+ * Constructs a DragGestureEvent object given by the
+ * DragGestureRecognizer instance firing this event,
+ * an {@code act} parameter representing
+ * the user's preferred action, an {@code ori} parameter
+ * indicating the origin of the drag, and a {@code List} of
+ * events that comprise the gesture({@code evs} parameter).
*
* @param dgr The DragGestureRecognizer firing this event
- * @param act The the user's preferred action
+ * @param act The user's preferred action.
+ * For information on allowable values, see
+ * the class description for {@link DragGestureEvent}
* @param ori The origin of the drag
* @param evs The List of events that comprise the gesture
*
- * @throws IllegalArgumentException if input parameters are {@code null}
+ * @throws IllegalArgumentException if any parameter equals {@code null}
+ * @throws IllegalArgumentException if the act parameter does not comply with
+ * the values given in the class
+ * description for {@link DragGestureEvent}
+ * @see java.awt.dnd.DnDConstants
*/
public DragGestureEvent(DragGestureRecognizer dgr, int act, Point ori,
diff --git a/src/share/classes/java/awt/dnd/DropTargetEvent.java b/src/share/classes/java/awt/dnd/DropTargetEvent.java
index 64d0b44d17022c12804ebe671d48df00ccbc9e82..42fd397c7019cbe1f81c9b0004ffa76176fbf940 100644
--- a/src/share/classes/java/awt/dnd/DropTargetEvent.java
+++ b/src/share/classes/java/awt/dnd/DropTargetEvent.java
@@ -45,10 +45,13 @@ public class DropTargetEvent extends java.util.EventObject {
private static final long serialVersionUID = 2821229066521922993L;
/**
- * Construct a DropTargetEvent with
- * a specified DropTargetContext.
+ * Construct a DropTargetEvent object with
+ * the specified DropTargetContext.
*
- * @param dtc the DropTargetContext
+ * @param dtc The DropTargetContext
+ * @throws NullPointerException if {@code dtc} equals {@code null}.
+ * @see #getSource()
+ * @see #getDropTargetContext()
*/
public DropTargetEvent(DropTargetContext dtc) {
diff --git a/src/share/classes/java/awt/event/ActionEvent.java b/src/share/classes/java/awt/event/ActionEvent.java
index 41ed7d6488ce9a6cfba3a08e2f24851ab1daf4cc..b81ab8a8f4fd604ab0c69d04ca313013df4d2888 100644
--- a/src/share/classes/java/awt/event/ActionEvent.java
+++ b/src/share/classes/java/awt/event/ActionEvent.java
@@ -1,5 +1,5 @@
/*
- * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -45,6 +45,10 @@ import java.awt.Event;
* is therefore spared the details of processing individual mouse movements
* and mouse clicks, and can instead process a "meaningful" (semantic)
* event like "button pressed".
+ *
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code ActionEvent} instance is not
+ * in the range from {@code ACTION_FIRST} to {@code ACTION_LAST}.
*
* @see ActionListener
* @see Tutorial: Java 1.1 Event Model
@@ -134,18 +138,22 @@ public class ActionEvent extends AWTEvent {
/**
* Constructs an ActionEvent object.
*
- * Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ * This method throws an
* IllegalArgumentException if source
* is null.
* A null command string is legal,
* but not recommended.
*
- * @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
+ * @param source The object that originated the event
+ * @param id An integer that identifies the event.
+ * For information on allowable values, see
+ * the class description for {@link ActionEvent}
+ * @param command A string that may specify a command (possibly one
* of several) associated with the event
* @throws IllegalArgumentException if source is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getActionCommand()
*/
public ActionEvent(Object source, int id, String command) {
this(source, id, command, 0);
@@ -154,19 +162,27 @@ public class ActionEvent extends AWTEvent {
/**
* Constructs an ActionEvent object with modifier keys.
*
- * Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ * This method throws an
* IllegalArgumentException if source
* is null.
* A null command string is legal,
* but not recommended.
*
- * @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
+ * @param source The object that originated the event
+ * @param id An integer that identifies the event.
+ * For information on allowable values, see
+ * the class description for {@link ActionEvent}
+ * @param command A string that may specify a command (possibly one
+ * of several) associated with the event
+ * @param modifiers The modifier keys down during event
+ * (shift, ctrl, alt, meta).
+ * Passing negative parameter is not recommended.
+ * Zero value means that no modifiers were passed
* @throws IllegalArgumentException if source is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getActionCommand()
+ * @see #getModifiers()
*/
public ActionEvent(Object source, int id, String command, int modifiers) {
this(source, id, command, 0, modifiers);
@@ -176,20 +192,31 @@ public class ActionEvent extends AWTEvent {
* Constructs an ActionEvent object with the specified
* modifier keys and timestamp.
*
- * Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ * This method throws an
* IllegalArgumentException if source
* is null.
* A null command string is legal,
* but not recommended.
*
- * @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 when the time the event occurred
- * @param modifiers the modifier keys held down during this action
+ * @param source The object that originated the event
+ * @param id An integer that identifies the event.
+ * For information on allowable values, see
+ * the class description for {@link ActionEvent}
+ * @param command A string that may specify a command (possibly one
+ * of several) associated with the event
+ * @param modifiers The modifier keys down during event
+ * (shift, ctrl, alt, meta).
+ * Passing negative parameter is not recommended.
+ * Zero value means that no modifiers were passed
+ * @param when A long that gives the time the event occurred.
+ * Passing negative or zero value
+ * is not recommended
* @throws IllegalArgumentException if source is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getActionCommand()
+ * @see #getModifiers()
+ * @see #getWhen()
*
* @since 1.4
*/
diff --git a/src/share/classes/java/awt/event/AdjustmentEvent.java b/src/share/classes/java/awt/event/AdjustmentEvent.java
index b928899b2ecd9e2373a2663ef6e49182af9c0d49..590dae60ffb7a221fdc5e6eb97b6fe61c0ad2d08 100644
--- a/src/share/classes/java/awt/event/AdjustmentEvent.java
+++ b/src/share/classes/java/awt/event/AdjustmentEvent.java
@@ -29,7 +29,25 @@ import java.awt.Adjustable;
import java.awt.AWTEvent;
/**
- * The adjustment event emitted by Adjustable objects.
+ * The adjustment event emitted by Adjustable objects like
+ * {@link java.awt.Scrollbar} and {@link java.awt.ScrollPane}.
+ * When the user changes the value of the scrolling component,
+ * it receives an instance of {@code AdjustmentEvent}.
+ *
+ * An unspecified behavior will be caused if the {@code id} parameter + * of any particular {@code AdjustmentEvent} instance is not + * in the range from {@code ADJUSTMENT_FIRST} to {@code ADJUSTMENT_LAST}. + *
+ * The {@code type} of any {@code AdjustmentEvent} instance takes one of the following + * values: + *
AdjustmentEvent object with the
* specified Adjustable source, event type,
* adjustment type, and value.
- * Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the Adjustable object where the
+ * @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
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link AdjustmentEvent}
+ * @param type An integer indicating the adjustment type.
+ * For information on allowable values, see
+ * the class description for {@link AdjustmentEvent}
+ * @param value The current value of the adjustment
* @throws IllegalArgumentException if source is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getAdjustmentType()
+ * @see #getValue()
*/
public AdjustmentEvent(Adjustable source, int id, int type, int value) {
this(source, id, type, value, false);
@@ -149,22 +174,29 @@ public class AdjustmentEvent extends AWTEvent {
/**
* Constructs an AdjustmentEvent object with the
* specified Adjustable source, event type, adjustment type, and value.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
-
*
- * @param source the Adjustable object where the
+ * @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
- * @param isAdjusting true if the event is one
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link AdjustmentEvent}
+ * @param type An integer indicating the adjustment type.
+ * For information on allowable values, see
+ * the class description for {@link AdjustmentEvent}
+ * @param value The current value of the adjustment
+ * @param isAdjusting A boolean that equals true if the event is one
* of a series of multiple adjusting events,
* otherwise false
* @throws IllegalArgumentException if source is null
* @since 1.4
+ * @see #getSource()
+ * @see #getID()
+ * @see #getAdjustmentType()
+ * @see #getValue()
+ * @see #getValueIsAdjusting()
*/
public AdjustmentEvent(Adjustable source, int id, int type, int value, boolean isAdjusting) {
super(source, id);
diff --git a/src/share/classes/java/awt/event/ComponentEvent.java b/src/share/classes/java/awt/event/ComponentEvent.java
index a0264b81af044222d5e4de1d7d7f87454b8a89be..bd51d262ef75cd8f462e74265538ebc5438a26fa 100644
--- a/src/share/classes/java/awt/event/ComponentEvent.java
+++ b/src/share/classes/java/awt/event/ComponentEvent.java
@@ -52,6 +52,10 @@ import java.awt.Rectangle;
* (ComponentAdapter objects implement the
* ComponentListener interface.) Each such listener object
* gets this ComponentEvent when the event occurs.
+ *
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code ComponentEvent} instance is not
+ * in the range from {@code COMPONENT_FIRST} to {@code COMPONENT_LAST}.
*
* @see ComponentAdapter
* @see ComponentListener
@@ -99,14 +103,17 @@ public class ComponentEvent extends AWTEvent {
/**
* Constructs a ComponentEvent object.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the Component that originated the event
- * @param id an integer indicating the type of event
+ * @param source The Component that originated the event
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link ComponentEvent}
* @throws IllegalArgumentException if source is null
+ * @see #getComponent()
+ * @see #getID()
*/
public ComponentEvent(Component source, int id) {
super(source, id);
diff --git a/src/share/classes/java/awt/event/ContainerEvent.java b/src/share/classes/java/awt/event/ContainerEvent.java
index f927312ba0bc5fde617de0bc6ced8aaa2bcbb1ba..16ef5b1c92f771a8b5744b428eea3f441b40dc50 100644
--- a/src/share/classes/java/awt/event/ContainerEvent.java
+++ b/src/share/classes/java/awt/event/ContainerEvent.java
@@ -45,6 +45,10 @@ import java.awt.Component;
* (ContainerAdapter objects implement the
* ContainerListener interface.) Each such listener object
* gets this ContainerEvent when the event occurs.
+ *
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code ContainerEvent} instance is not
+ * in the range from {@code CONTAINER_FIRST} to {@code CONTAINER_LAST}.
*
* @see ContainerAdapter
* @see ContainerListener
@@ -92,16 +96,20 @@ public class ContainerEvent extends ComponentEvent {
/**
* Constructs a ContainerEvent object.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the Component object (container)
+ * @param source The Component object (container)
* that originated the event
- * @param id an integer indicating the type of event
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link ContainerEvent}
* @param child the component that was added or removed
* @throws IllegalArgumentException if source is null
+ * @see #getContainer()
+ * @see #getID()
+ * @see #getChild()
*/
public ContainerEvent(Component source, int id, Component child) {
super(source, id);
diff --git a/src/share/classes/java/awt/event/FocusEvent.java b/src/share/classes/java/awt/event/FocusEvent.java
index 188ce44b720ddc7231d3584979adaedde61fb2d7..ec018e0126ebbdcf9d369b40a89ebbe6c45925a2 100644
--- a/src/share/classes/java/awt/event/FocusEvent.java
+++ b/src/share/classes/java/awt/event/FocusEvent.java
@@ -50,6 +50,10 @@ import sun.awt.SunToolkit;
* reactivated. Both permanent and temporary focus events are delivered using
* the FOCUS_GAINED and FOCUS_LOST event ids; the level may be distinguished in
* the event using the isTemporary() method.
+ *
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code FocusEvent} instance is not
+ * in the range from {@code FOCUS_FIRST} to {@code FOCUS_LAST}.
*
* @see FocusAdapter
* @see FocusListener
@@ -121,18 +125,23 @@ public class FocusEvent extends ComponentEvent {
* application, with a Java application in a different VM,
* or with no other Component, then the opposite
* Component is null.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the Component that originated the event
- * @param id FOCUS_GAINED or FOCUS_LOST
- * @param temporary true if the focus change is temporary;
+ * @param source The Component that originated the event
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link FocusEvent}
+ * @param temporary Equals true if the focus change is temporary;
* false otherwise
- * @param opposite the other Component involved in the focus change,
+ * @param opposite The other Component involved in the focus change,
* or null
- * @throws IllegalArgumentException if source is null
+ * @throws IllegalArgumentException if source equals {@code null}
+ * @see #getSource()
+ * @see #getID()
+ * @see #isTemporary()
+ * @see #getOppositeComponent()
* @since 1.4
*/
public FocusEvent(Component source, int id, boolean temporary,
@@ -145,16 +154,20 @@ public class FocusEvent extends ComponentEvent {
/**
* Constructs a FocusEvent object and identifies
* whether or not the change is temporary.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the Component that originated the event
- * @param id an integer indicating the type of event
- * @param temporary true if the focus change is temporary;
+ * @param source The Component that originated the event
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link FocusEvent}
+ * @param temporary Equals true if the focus change is temporary;
* false otherwise
- * @throws IllegalArgumentException if source is null
+ * @throws IllegalArgumentException if source equals {@code null}
+ * @see #getSource()
+ * @see #getID()
+ * @see #isTemporary()
*/
public FocusEvent(Component source, int id, boolean temporary) {
this(source, id, temporary, null);
@@ -163,14 +176,17 @@ public class FocusEvent extends ComponentEvent {
/**
* Constructs a FocusEvent object and identifies it
* as a permanent change in focus.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the Component that originated the event
- * @param id an integer indicating the type of event
- * @throws IllegalArgumentException if source is null
+ * @param source The Component that originated the event
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link FocusEvent}
+ * @throws IllegalArgumentException if source equals {@code null}
+ * @see #getSource()
+ * @see #getID()
*/
public FocusEvent(Component source, int id) {
this(source, id, false);
diff --git a/src/share/classes/java/awt/event/HierarchyEvent.java b/src/share/classes/java/awt/event/HierarchyEvent.java
index d57256a45a2f6c836a9dd8ed659b104db7a58484..6ed6ab18edb2458c6e5ae8ca451e76b51dbb99d9 100644
--- a/src/share/classes/java/awt/event/HierarchyEvent.java
+++ b/src/share/classes/java/awt/event/HierarchyEvent.java
@@ -1,5 +1,5 @@
/*
- * Copyright 1999-2004 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright 1999-2008 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -31,7 +31,7 @@ import java.awt.Container;
/**
* An event which indicates a change to the Component
- * hierarchy to which a Component belongs.
+ * hierarchy to which Component belongs.
*
addNotify, removeNotify, show, or
- * hide method is called. ANCESTOR_MOVED and ANCESTOR_RESIZED
+ * hide method is called. The {@code ANCESTOR_MOVED} and
+ * {@code 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
+ * HierarchyBoundsListener interface.) The {@code 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.
+ *
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code HierarchyEvent} instance is not
+ * in the range from {@code HIERARCHY_FIRST} to {@code HIERARCHY_LAST}.
+ *
+ * The {@code changeFlags} parameter of any {@code HierarchyEvent} instance takes one of the following
+ * values:
+ *
HIERARCHY_CHANGED event
+ * A change flag indicates that the HIERARCHY_CHANGED event
* was generated by a reparenting operation.
*/
public static final int PARENT_CHANGED = 0x1;
/**
- * Indicates that the HIERARCHY_CHANGED event
- * was generated due to a change in the displayability
- * of the hierarchy. To discern the
- * current displayability of the hierarchy, call
- * Component.isDisplayable. Displayability changes occur
- * in response to explicit or implicit calls to
+ * A change flag indicates that the HIERARCHY_CHANGED event
+ * was generated due to the changing of the hierarchy displayability.
+ * To discern the
+ * current displayability of the hierarchy, call the
+ * Component.isDisplayable method. Displayability changes occur
+ * in response to explicit or implicit calls of the
* Component.addNotify and
- * Component.removeNotify.
+ * Component.removeNotify methods.
*
* @see java.awt.Component#isDisplayable()
* @see java.awt.Component#addNotify()
@@ -130,15 +144,15 @@ public class HierarchyEvent extends AWTEvent {
public static final int DISPLAYABILITY_CHANGED = 0x2;
/**
- * Indicates that the HIERARCHY_CHANGED event
- * was generated due to a change in the showing state
- * of the hierarchy. To discern the
- * current showing state of the hierarchy, call
- * Component.isShowing. Showing state changes occur
+ * A change flag indicates that the HIERARCHY_CHANGED event
+ * was generated due to the changing of the hierarchy showing state.
+ * To discern the
+ * current showing state of the hierarchy, call the
+ * Component.isShowing method. Showing state changes occur
* when either the displayability or visibility of the
* hierarchy occurs. Visibility changes occur in response to explicit
- * or implicit calls to Component.show and
- * Component.hide.
+ * or implicit calls of the Component.show and
+ * Component.hide methods.
*
* @see java.awt.Component#isShowing()
* @see java.awt.Component#addNotify()
@@ -155,20 +169,26 @@ public class HierarchyEvent extends AWTEvent {
/**
* Constructs an HierarchyEvent object to identify a
* change in the Component hierarchy.
- * Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the Component object that
+ * @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
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link HierarchyEvent}
+ * @param changed The Component at the top of
* the hierarchy which was changed
- * @param changedParent the parent of changed; this
+ * @param changedParent The parent of the changed component.
+ * This
* may be the parent before or after the
* change, depending on the type of change
- * @throws IllegalArgumentException if source is null
+ * @throws IllegalArgumentException if source is {@code null}
+ * @see #getSource()
+ * @see #getID()
+ * @see #getChanged()
+ * @see #getChangedParent()
*/
public HierarchyEvent(Component source, int id, Component changed,
Container changedParent) {
@@ -180,23 +200,32 @@ public class HierarchyEvent extends AWTEvent {
/**
* Constructs an HierarchyEvent object to identify
* a change in the Component hierarchy.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the Component object that
+ * @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
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link HierarchyEvent}
+ * @param changed The Component at the top
* of the hierarchy which was changed
- * @param changedParent the parent of changed; this
+ * @param changedParent The parent of the changed component.
+ * 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
+ * @param changeFlags A bitmask which indicates the type(s) of
+ * the HIERARCHY_CHANGED events
+ * represented in this event object.
+ * For information on allowable values, see
+ * the class description for {@link HierarchyEvent}
* @throws IllegalArgumentException if source is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getChanged()
+ * @see #getChangedParent()
+ * @see #getChangeFlags()
*/
public HierarchyEvent(Component source, int id, Component changed,
Container changedParent, long changeFlags) {
diff --git a/src/share/classes/java/awt/event/InputEvent.java b/src/share/classes/java/awt/event/InputEvent.java
index 45b1f87e40e389bec54153a2d8178b14ac910a30..0c35c2be46401e3a9413e6fa7efc4d5c74c18ead 100644
--- a/src/share/classes/java/awt/event/InputEvent.java
+++ b/src/share/classes/java/awt/event/InputEvent.java
@@ -208,17 +208,32 @@ public abstract class InputEvent extends ComponentEvent {
/**
* Constructs an InputEvent object with the specified source component,
* modifiers, and type.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
* @param source the object where the event originated
- * @param id the event type
- * @param when the time the event occurred
- * @param modifiers represents the modifier keys and mouse buttons down
- * while the event occurred
+ * @param id the integer that identifies the event type.
+ * It is allowed to pass as parameter any value that
+ * allowed for some subclass of {@code InputEvent} class.
+ * Passing in the value different from those values result
+ * in unspecified behavior
+ * @param when a long int that gives the time the event occurred.
+ * Passing negative or zero value
+ * is not recommended
+ * @param modifiers the modifier keys down during event (e.g. shift, ctrl,
+ * alt, meta)
+ * Passing negative parameter is not recommended.
+ * Zero value means no modifiers.
+ * Either extended _DOWN_MASK or old _MASK modifiers
+ * should be used, but both models should not be mixed
+ * in one event. Use of the extended modifiers is
+ * preferred
* @throws IllegalArgumentException if source is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getWhen()
+ * @see #getModifiers()
*/
InputEvent(Component source, int id, long when, int modifiers) {
super(source, id);
@@ -285,7 +300,8 @@ public abstract class InputEvent extends ComponentEvent {
}
/**
- * Returns the timestamp of when this event occurred.
+ * Returns the difference in milliseconds between the timestamp of when this event occurred and
+ * midnight, January 1, 1970 UTC.
*/
public long getWhen() {
return when;
@@ -358,7 +374,12 @@ public abstract class InputEvent extends ComponentEvent {
* Returns a String describing the extended modifier keys and
* mouse buttons, such as "Shift", "Button1", or "Ctrl+Shift".
* These strings can be localized by changing the
- * awt.properties file.
+ * awt.properties file.
+ *
+ * Note that passing negative parameter is incorrect,
+ * and will cause the returning an unspecified string.
+ * Zero parameter means that no modifiers were passed and will
+ * cause the returning an empty string.
*
* @param modifiers a modifier mask describing the extended
* modifier keys and mouse buttons for the event
diff --git a/src/share/classes/java/awt/event/InvocationEvent.java b/src/share/classes/java/awt/event/InvocationEvent.java
index 705f87a12e437cdc206db500276359d919994be6..0959a86cb3539e0999bb94ab0d8d200fc06169af 100644
--- a/src/share/classes/java/awt/event/InvocationEvent.java
+++ b/src/share/classes/java/awt/event/InvocationEvent.java
@@ -1,5 +1,5 @@
/*
- * Copyright 1998-2006 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright 1998-2008 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -39,6 +39,10 @@ import java.awt.AWTEvent;
* can use this fact to write replacement functions for invokeLater
* and invokeAndWait without writing special-case code
* in any AWTEventListener objects.
+ *
+ * An unspecified behavior will be caused if the {@code id} parameter + * of any particular {@code InvocationEvent} instance is not + * in the range from {@code INVOCATION_FIRST} to {@code INVOCATION_LAST}. * * @author Fred Ecks * @author David Mendenhall @@ -123,12 +127,13 @@ public class InvocationEvent extends AWTEvent implements ActiveEvent { *
This method throws an IllegalArgumentException
* if source is null.
*
- * @param source the Object that originated the event
- * @param runnable the Runnable whose run
+ * @param source The Object that originated the event
+ * @param runnable The Runnable whose run
* method will be executed
* @throws IllegalArgumentException if source is null
*
- * @see #InvocationEvent(Object, Runnable, Object, boolean)
+ * @see #getSource()
+ * @see #InvocationEvent(Object, Runnable, Object, boolean)
*/
public InvocationEvent(Object source, Runnable runnable) {
this(source, runnable, null, false);
@@ -147,15 +152,15 @@ public class InvocationEvent extends AWTEvent implements ActiveEvent {
*
This method throws an IllegalArgumentException
* if source is null.
*
- * @param source the Object that originated
+ * @param source The Object that originated
* the event
- * @param runnable the Runnable whose
+ * @param runnable The Runnable whose
* run method will be
* executed
- * @param notifier the Object whose notifyAll
+ * @param notifier The {@code Object} whose notifyAll
* method will be called after
* Runnable.run has returned
- * @param catchThrowables specifies whether dispatch
+ * @param catchThrowables Specifies whether dispatch
* should catch Throwable when executing
* the Runnable's run
* method, or should instead propagate those
@@ -163,6 +168,7 @@ public class InvocationEvent extends AWTEvent implements ActiveEvent {
* dispatch loop
* @throws IllegalArgumentException if source is null
*
+ * @see #getSource()
* @see #InvocationEvent(Object, int, Runnable, Object, boolean)
*/
public InvocationEvent(Object source, Runnable runnable, Object notifier,
@@ -176,26 +182,29 @@ public class InvocationEvent extends AWTEvent implements ActiveEvent {
* 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. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the Object that originated
+ * @param source The Object that originated
* the event
- * @param id the ID for the event
- * @param runnable the Runnable whose
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link InvocationEvent}
+ * @param runnable The Runnable whose
* run method will be executed
- * @param notifier the Object whose notifyAll
+ * @param notifier The Object whose notifyAll
* method will be called after
* Runnable.run has returned
- * @param catchThrowables specifies whether dispatch
+ * @param catchThrowables Specifies whether dispatch
* should catch Throwable when executing the
* Runnable's run
* method, or should instead propagate those
* Throwables to the EventDispatchThread's
* dispatch loop
* @throws IllegalArgumentException if source is null
+ * @see #getSource()
+ * @see #getID()
*/
protected InvocationEvent(Object source, int id, Runnable runnable,
Object notifier, boolean catchThrowables) {
diff --git a/src/share/classes/java/awt/event/ItemEvent.java b/src/share/classes/java/awt/event/ItemEvent.java
index 7b37f3ed0c4645a58e11556e3df0a368db59febf..156b0614618a9b8916a743e2b899f087a4251c10 100644
--- a/src/share/classes/java/awt/event/ItemEvent.java
+++ b/src/share/classes/java/awt/event/ItemEvent.java
@@ -41,6 +41,18 @@ import java.awt.ItemSelectable;
* spared the details of processing individual mouse movements and mouse
* clicks, and can instead process a "meaningful" (semantic) event like
* "item selected" or "item deselected".
+ *
+ * An unspecified behavior will be caused if the {@code id} parameter + * of any particular {@code ItemEvent} instance is not + * in the range from {@code ITEM_FIRST} to {@code ITEM_LAST}. + *
+ * The {@code stateChange} of any {@code ItemEvent} instance takes one of the following + * values: + *
ItemEvent object.
- * Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the ItemSelectable object
+ * @param source The ItemSelectable object
* that originated the event
- * @param id an integer that identifies the event type
- * @param item an object -- the item affected by the event
- * @param stateChange
- * an integer that indicates whether the item was
- * selected or deselected
+ * @param id The integer that identifies the event type.
+ * For information on allowable values, see
+ * the class description for {@link ItemEvent}
+ * @param item An object -- the item affected by the event
+ * @param stateChange An integer that indicates whether the item was
+ * selected or deselected.
+ * For information on allowable values, see
+ * the class description for {@link ItemEvent}
* @throws IllegalArgumentException if source is null
+ * @see #getItemSelectable()
+ * @see #getID()
+ * @see #getStateChange()
*/
public ItemEvent(ItemSelectable source, int id, Object item, int stateChange) {
super(source, id);
diff --git a/src/share/classes/java/awt/event/KeyEvent.java b/src/share/classes/java/awt/event/KeyEvent.java
index 556ceb28b2b12a5c3e993d06ae96a41f3d2444b0..039675702972f64d4446bb0697d8cda02016a25a 100644
--- a/src/share/classes/java/awt/event/KeyEvent.java
+++ b/src/share/classes/java/awt/event/KeyEvent.java
@@ -1,5 +1,5 @@
/*
- * Copyright 1996-2007 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -128,6 +128,10 @@ import java.io.ObjectInputStream;
* (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.
+ *
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code KeyEvent} instance is not
+ * in the range from {@code KEY_FIRST} to {@code KEY_LAST}.
*
* @author Carl Quinn
* @author Amy Fowler
@@ -914,27 +918,32 @@ public class KeyEvent extends InputEvent {
/**
* Constructs a KeyEvent object.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the Component that originated the event
- * @param id an integer identifying the type of event
- * @param when a long integer that specifies the time the event
- * occurred
- * @param modifiers the modifier keys down during event (shift, ctrl,
- * alt, meta)
- * Either extended _DOWN_MASK or old _MASK modifiers
- * should be used, but both models should not be mixed
- * in one event. Use of the extended modifiers is
- * preferred.
- * @param keyCode the integer code for an actual key, or VK_UNDEFINED
+ * @param source The Component that originated the event
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link KeyEvent}
+ * @param when A long integer that specifies the time the event
+ * occurred.
+ * Passing negative or zero value
+ * is not recommended
+ * @param modifiers The modifier keys down during event (shift, ctrl,
+ * alt, meta).
+ * Passing negative value
+ * is not recommended.
+ * Zero value means that no modifiers were passed.
+ * Use either an extended _DOWN_MASK or old _MASK modifiers,
+ * however do not mix models in the one event.
+ * The extended modifiers are preferred for using
+ * @param keyCode The integer code for an actual key, or VK_UNDEFINED
* (for a key-typed event)
- * @param keyChar the Unicode character generated by this event, or
+ * @param keyChar The Unicode character generated by this event, or
* CHAR_UNDEFINED (for key-pressed and key-released
* events which do not map to a valid Unicode character)
- * @param keyLocation identifies the key location. The only legal
+ * @param keyLocation Identifies the key location. The only legal
* values are KEY_LOCATION_UNKNOWN,
* KEY_LOCATION_STANDARD, KEY_LOCATION_LEFT,
* KEY_LOCATION_RIGHT, and KEY_LOCATION_NUMPAD.
@@ -948,6 +957,13 @@ public class KeyEvent extends InputEvent {
* or if keyLocation is not one of the legal
* values enumerated above.
* @throws IllegalArgumentException if source is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getWhen()
+ * @see #getModifiers()
+ * @see #getKeyCode()
+ * @see #getKeyChar()
+ * @see #getKeyLocation()
* @since 1.4
*/
public KeyEvent(Component source, int id, long when, int modifiers,
@@ -982,24 +998,29 @@ public class KeyEvent extends InputEvent {
/**
* Constructs a KeyEvent object.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the Component that originated the event
- * @param id an integer identifying the type of event
- * @param when a long integer that specifies the time the event
- * occurred
- * @param modifiers the modifier keys down during event (shift, ctrl,
- * alt, meta)
- * Either extended _DOWN_MASK or old _MASK modifiers
- * should be used, but both models should not be mixed
- * in one event. Use of the extended modifiers is
- * preferred.
- * @param keyCode the integer code for an actual key, or VK_UNDEFINED
+ * @param source The Component that originated the event
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link KeyEvent}
+ * @param when A long integer that specifies the time the event
+ * occurred.
+ * Passing negative or zero value
+ * is not recommended
+ * @param modifiers The modifier keys down during event (shift, ctrl,
+ * alt, meta).
+ * Passing negative value
+ * is not recommended.
+ * Zero value means that no modifiers were passed.
+ * Use either an extended _DOWN_MASK or old _MASK modifiers,
+ * however do not mix models in the one event.
+ * The extended modifiers are preferred for using
+ * @param keyCode The integer code for an actual key, or VK_UNDEFINED
* (for a key-typed event)
- * @param keyChar the Unicode character generated by this event, or
+ * @param keyChar The Unicode character generated by this event, or
* CHAR_UNDEFINED (for key-pressed and key-released
* events which do not map to a valid Unicode character)
* @throws IllegalArgumentException if id is
@@ -1008,6 +1029,12 @@ public class KeyEvent extends InputEvent {
* KEY_TYPED and keyCode is not
* VK_UNDEFINED
* @throws IllegalArgumentException if source is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getWhen()
+ * @see #getModifiers()
+ * @see #getKeyCode()
+ * @see #getKeyChar()
*/
public KeyEvent(Component source, int id, long when, int modifiers,
int keyCode, char keyChar) {
diff --git a/src/share/classes/java/awt/event/MouseEvent.java b/src/share/classes/java/awt/event/MouseEvent.java
index d546be5ec8e65372953cedef06c2658f0e05fa63..a9aed6add197930212c00e4e31358148dc4f33f6 100644
--- a/src/share/classes/java/awt/event/MouseEvent.java
+++ b/src/share/classes/java/awt/event/MouseEvent.java
@@ -159,6 +159,11 @@ import java.awt.IllegalComponentStateException;
* The reported coordinates for mouse drag events are clipped to fit within the
* bounds of the virtual device associated with the Component.
*
+ * An unspecified behavior will be caused if the {@code id} parameter + * of any particular {@code MouseEvent} instance is not + * in the range from {@code MOUSE_FIRST} to {@code MOUSE_LAST}-1 + * ({@code MOUSE_WHEEL} is not acceptable). * * @author Carl Quinn * @@ -418,8 +423,7 @@ public class MouseEvent extends InputEvent { * specified source component, * type, modifiers, coordinates, and click count. *
- * Note that passing in an invalid id results in
- * unspecified behavior. Creating an invalid event (such
+ * Creating an invalid event (such
* as by using more than one of the old _MASKs, or modifier/button
* values which don't match) results in unspecified behavior.
* An invocation of the form
@@ -435,28 +439,44 @@ public class MouseEvent extends InputEvent {
* IllegalArgumentException if source
* is null.
*
- * @param source the Component that originated the event
- * @param id the integer that identifies the event
- * @param when a long int that gives the time the event occurred
- * @param modifiers the modifier keys down during event (e.g. shift, ctrl,
+ * @param source The Component that originated the event
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link MouseEvent}
+ * @param when A long integer that gives the time the event occurred.
+ * Passing negative or zero value
+ * is not recommended
+ * @param modifiers The modifier keys down during event (e.g. shift, ctrl,
* alt, meta)
- * Either extended _DOWN_MASK or old _MASK modifiers
- * should be used, but both models should not be mixed
- * in one event. Use of the extended modifiers is
- * preferred.
- * @param x the horizontal x coordinate for the mouse location
- * @param y the vertical y coordinate for the mouse location
- * @param clickCount the number of mouse clicks associated with event
- * @param popupTrigger a boolean, true if this event is a trigger for a
- * popup menu
- * @param button which of the mouse buttons has changed state.
- * NOBUTTON,
- * BUTTON1,
- * BUTTON2 or
- * BUTTON3.
+ * Passing negative parameter
+ * is not recommended.
+ * Zero value means that no modifiers were passed.
+ * Use either an extended _DOWN_MASK or old _MASK modifiers,
+ * however do not mix models in the one event.
+ * The extended modifiers are preferred for using
+ * @param x The horizontal x coordinate for the mouse location.
+ * It is allowed to pass negative values
+ * @param y The vertical y coordinate for the mouse location.
+ * It is allowed to pass negative values
+ * @param clickCount The number of mouse clicks associated with event.
+ * Passing negative value
+ * is not recommended
+ * @param popupTrigger A boolean that equals {@code true} if this event
+ * is a trigger for a popup menu
+ * @param button An integer that indicates, which of the mouse buttons has
+ * changed its state
* @throws IllegalArgumentException if an invalid button
* value is passed in
* @throws IllegalArgumentException if source is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getWhen()
+ * @see #getModifiers()
+ * @see #getX()
+ * @see #getY()
+ * @see #getClickCount()
+ * @see #isPopupTrigger()
+ * @see #getButton()
* @since 1.4
*/
public MouseEvent(Component source, int id, long when, int modifiers,
@@ -479,8 +499,6 @@ public class MouseEvent extends InputEvent {
* Constructs a MouseEvent object with the
* specified source component,
* type, modifiers, coordinates, and click count.
- *
Note that passing in an invalid id results in
- * unspecified behavior.
* An invocation of the form
* MouseEvent(source, id, when, modifiers, x, y, clickCount, popupTrigger)
* behaves in exactly the same way as the invocation
@@ -493,21 +511,39 @@ public class MouseEvent extends InputEvent {
* This method throws an IllegalArgumentException
* if source is null.
*
- * @param source the Component that originated the event
- * @param id the integer that identifies the event
- * @param when a long int that gives the time the event occurred
- * @param modifiers the modifier keys down during event (e.g. shift, ctrl,
+ * @param source The Component that originated the event
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link MouseEvent}
+ * @param when A long integer that gives the time the event occurred.
+ * Passing negative or zero value
+ * is not recommended
+ * @param modifiers The modifier keys down during event (e.g. shift, ctrl,
* alt, meta)
- * Either extended _DOWN_MASK or old _MASK modifiers
- * should be used, but both models should not be mixed
- * in one event. Use of the extended modifiers is
- * preferred.
- * @param x the horizontal x coordinate for the mouse location
- * @param y the vertical y coordinate for the mouse location
- * @param clickCount the number of mouse clicks associated with event
- * @param popupTrigger a boolean, true if this event is a trigger for a
- * popup menu
+ * Passing negative parameter
+ * is not recommended.
+ * Zero value means that no modifiers were passed.
+ * Use either an extended _DOWN_MASK or old _MASK modifiers,
+ * however do not mix models in the one event.
+ * The extended modifiers are preferred for using
+ * @param x The horizontal x coordinate for the mouse location.
+ * It is allowed to pass negative values
+ * @param y The vertical y coordinate for the mouse location.
+ * It is allowed to pass negative values
+ * @param clickCount The number of mouse clicks associated with event.
+ * Passing negative value
+ * is not recommended
+ * @param popupTrigger A boolean that equals {@code true} if this event
+ * is a trigger for a popup menu
* @throws IllegalArgumentException if source is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getWhen()
+ * @see #getModifiers()
+ * @see #getX()
+ * @see #getY()
+ * @see #getClickCount()
+ * @see #isPopupTrigger()
*/
public MouseEvent(Component source, int id, long when, int modifiers,
int x, int y, int clickCount, boolean popupTrigger) {
@@ -520,8 +556,7 @@ public class MouseEvent extends InputEvent {
* specified source component,
* type, modifiers, coordinates, absolute coordinates, and click count.
*
- * Note that passing in an invalid id results in
- * unspecified behavior. Creating an invalid event (such
+ * Creating an invalid event (such
* as by using more than one of the old _MASKs, or modifier/button
* values which don't match) results in unspecified behavior.
* Even if inconsistent values for relative and absolute coordinates are
@@ -531,30 +566,50 @@ public class MouseEvent extends InputEvent {
* IllegalArgumentException if source
* is null.
*
- * @param source the Component that originated the event
- * @param id the integer that identifies the event
- * @param when a long int that gives the time the event occurred
- * @param modifiers the modifier keys down during event (e.g. shift, ctrl,
+ * @param source The Component that originated the event
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link MouseEvent}
+ * @param when A long integer that gives the time the event occurred.
+ * Passing negative or zero value
+ * is not recommended
+ * @param modifiers The modifier keys down during event (e.g. shift, ctrl,
* alt, meta)
- * Either extended _DOWN_MASK or old _MASK modifiers
- * should be used, but both models should not be mixed
- * in one event. Use of the extended modifiers is
- * preferred.
- * @param x the horizontal x coordinate for the mouse location
- * @param y the vertical y coordinate for the mouse location
- * @param xAbs the absolute horizontal x coordinate for the mouse location
- * @param yAbs the absolute vertical y coordinate for the mouse location
- * @param clickCount the number of mouse clicks associated with event
- * @param popupTrigger a boolean, true if this event is a trigger for a
- * popup menu
- * @param button which of the mouse buttons has changed state.
- * NOBUTTON,
- * BUTTON1,
- * BUTTON2 or
- * BUTTON3.
+ * Passing negative parameter
+ * is not recommended.
+ * Zero value means that no modifiers were passed.
+ * Use either an extended _DOWN_MASK or old _MASK modifiers,
+ * however do not mix models in the one event.
+ * The extended modifiers are preferred for using
+ * @param x The horizontal x coordinate for the mouse location.
+ * It is allowed to pass negative values
+ * @param y The vertical y coordinate for the mouse location.
+ * It is allowed to pass negative values
+ * @param xAbs The absolute horizontal x coordinate for the mouse location
+ * It is allowed to pass negative values
+ * @param yAbs The absolute vertical y coordinate for the mouse location
+ * It is allowed to pass negative values
+ * @param clickCount The number of mouse clicks associated with event.
+ * Passing negative value
+ * is not recommended
+ * @param popupTrigger A boolean that equals {@code true} if this event
+ * is a trigger for a popup menu
+ * @param button An integer that indicates, which of the mouse buttons has
+ * changed its state
* @throws IllegalArgumentException if an invalid button
* value is passed in
* @throws IllegalArgumentException if source is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getWhen()
+ * @see #getModifiers()
+ * @see #getX()
+ * @see #getY()
+ * @see #getXOnScreen()
+ * @see #getYOnScreen()
+ * @see #getClickCount()
+ * @see #isPopupTrigger()
+ * @see #getButton()
* @since 1.6
*/
public MouseEvent(Component source, int id, long when, int modifiers,
@@ -675,21 +730,26 @@ public class MouseEvent extends InputEvent {
}
/**
- * Returns a String describing the modifier keys and
+ * Returns a String instance describing the modifier keys and
* mouse buttons that were down during the event, such as "Shift",
* or "Ctrl+Shift". These strings can be localized by changing
* the awt.properties file.
*
- * Note that InputEvent.ALT_MASK and
- * InputEvent.BUTTON2_MASK have the same value,
- * so the string "Alt" is returned for both modifiers. Likewise,
- * InputEvent.META_MASK and
- * InputEvent.BUTTON3_MASK have the same value,
- * so the string "Meta" is returned for both modifiers.
+ * Note that the InputEvent.ALT_MASK and
+ * InputEvent.BUTTON2_MASK have equal values,
+ * so the "Alt" string is returned for both modifiers. Likewise,
+ * the InputEvent.META_MASK and
+ * InputEvent.BUTTON3_MASK have equal values,
+ * so the "Meta" string is returned for both modifiers.
+ *
+ * Note that passing negative parameter is incorrect, + * and will cause the returning an unspecified string. + * Zero parameter means that no modifiers were passed and will + * cause the returning an empty string. * - * @param modifiers a modifier mask describing the modifier keys and + * @param modifiers A modifier mask describing the modifier keys and * mouse buttons that were down during the event - * @return string a text description of the combination of modifier + * @return string string text description of the combination of modifier * keys and mouse buttons that were down during the event * @see InputEvent#getModifiersExText(int) * @since 1.4 diff --git a/src/share/classes/java/awt/event/MouseWheelEvent.java b/src/share/classes/java/awt/event/MouseWheelEvent.java index a1c5b2ebb9111eb755c8914f9a42672b12ceef87..19c46fe7f41996cfea366a7cfe7a77675118a9ca 100644 --- a/src/share/classes/java/awt/event/MouseWheelEvent.java +++ b/src/share/classes/java/awt/event/MouseWheelEvent.java @@ -1,5 +1,5 @@ /* - * Copyright 2000-2007 Sun Microsystems, Inc. All Rights Reserved. + * Copyright 2000-2008 Sun Microsystems, Inc. All Rights Reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it diff --git a/src/share/classes/java/awt/event/PaintEvent.java b/src/share/classes/java/awt/event/PaintEvent.java index beafed7f8eb8e8a661b50e6f370475f0dd5e46bf..1826cce357894aefdbf54992b74469fd1a46011a 100644 --- a/src/share/classes/java/awt/event/PaintEvent.java +++ b/src/share/classes/java/awt/event/PaintEvent.java @@ -36,6 +36,10 @@ import java.awt.Rectangle; * designed to be used with the Event Listener model; programs * should continue to override paint/update methods in order * render themselves properly. + *
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code PaintEvent} instance is not
+ * in the range from {@code PAINT_FIRST} to {@code PAINT_LAST}.
*
* @author Amy Fowler
* @since 1.1
@@ -82,15 +86,19 @@ public class PaintEvent extends ComponentEvent {
/**
* Constructs a PaintEvent object with the specified
* source component and type.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the object where the event originated
- * @param id the event type
- * @param updateRect the rectangle area which needs to be repainted
+ * @param source The object where the event originated
+ * @param id The integer that identifies the event type.
+ * For information on allowable values, see
+ * the class description for {@link PaintEvent}
+ * @param updateRect The rectangle area which needs to be repainted
* @throws IllegalArgumentException if source is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getUpdateRect()
*/
public PaintEvent(Component source, int id, Rectangle updateRect) {
super(source, id);
diff --git a/src/share/classes/java/awt/event/TextEvent.java b/src/share/classes/java/awt/event/TextEvent.java
index 0c7aadca17709a5aa209a46815ffb08b10db65f4..36b62d40d0106ae4ea2afb9cfcbb15f2419c9916 100644
--- a/src/share/classes/java/awt/event/TextEvent.java
+++ b/src/share/classes/java/awt/event/TextEvent.java
@@ -38,6 +38,10 @@ import java.awt.AWTEvent;
* this TextEvent when the event occurs. The listener is
* spared the details of processing individual mouse movements and key strokes
* Instead, it can process a "meaningful" (semantic) event like "text changed".
+ *
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code TextEvent} instance is not
+ * in the range from {@code TEXT_FIRST} to {@code TEXT_LAST}.
*
* @author Georges Saab
*
@@ -71,15 +75,18 @@ public class TextEvent extends AWTEvent {
/**
* Constructs a TextEvent object.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the (TextComponent) object that
+ * @param source The (TextComponent) object that
* originated the event
- * @param id an integer that identifies the event type
+ * @param id An integer that identifies the event type.
+ * For information on allowable values, see
+ * the class description for {@link TextEvent}
* @throws IllegalArgumentException if source is null
+ * @see #getSource()
+ * @see #getID()
*/
public TextEvent(Object source, int id) {
super(source, id);
diff --git a/src/share/classes/java/awt/event/WindowEvent.java b/src/share/classes/java/awt/event/WindowEvent.java
index 090ba017f559c919f9514ec56c255c9c589d9a6f..a662aab92e4242f1928c6fc8cc284569ddf32386 100644
--- a/src/share/classes/java/awt/event/WindowEvent.java
+++ b/src/share/classes/java/awt/event/WindowEvent.java
@@ -41,6 +41,10 @@ import sun.awt.SunToolkit;
* (WindowAdapter objects implement the
* WindowListener interface.) Each such listener object
* gets this WindowEvent when the event occurs.
+ *
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code WindowEvent} instance is not
+ * in the range from {@code WINDOW_FIRST} to {@code WINDOW_LAST}.
*
* @author Carl Quinn
* @author Amy Fowler
@@ -170,20 +174,27 @@ public class WindowEvent extends ComponentEvent {
/**
* Constructs a WindowEvent object.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the Window object
+ * @param source The Window object
* that originated the event
- * @param id an integer indicating the type of event.
- * @param opposite the other window involved in the focus or activation
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link WindowEvent}
+ * @param opposite The other window involved in the focus or activation
* change, or null
- * @param oldState previous state of the window for window state
- * change event
- * @param newState new state of the window for window state change event
+ * @param oldState Previous state of the window for window state change event.
+ * See {@code #getOldState()} for allowable values
+ * @param newState New state of the window for window state change event.
+ * See {@code #getNewState()} for allowable values
* @throws IllegalArgumentException if source is null
+ * @see #getWindow()
+ * @see #getID()
+ * @see #getOppositeWindow()
+ * @see #getOldState()
+ * @see #getNewState()
* @since 1.4
*/
public WindowEvent(Window source, int id, Window opposite,
@@ -209,24 +220,28 @@ public class WindowEvent extends ComponentEvent {
* If this focus change occurs with a native application, with a
* Java application in a different VM, or with no other
* Window, then the opposite Window is null.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the Window object that
+ * @param source The Window object that
* originated the event
- * @param id WINDOW_ACTIVATED,
- * WINDOW_DEACTIVATED,
- * WINDOW_GAINED_FOCUS,
- * or WINDOW_LOST_FOCUS. It is
- * expected that this constructor will not be used for
- * other WindowEvent types because the
- * opposite Window of such events
- * will always be null
- * @param opposite the other Window involved in the
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link WindowEvent}.
+ * It is expected that this constructor will not
+ * be used for other then
+ * {@code WINDOW_ACTIVATED},{@code WINDOW_DEACTIVATED},
+ * {@code WINDOW_GAINED_FOCUS}, or {@code WINDOW_LOST_FOCUS}.
+ * {@code WindowEvent} types,
+ * because the opposite Window of other event types
+ * will always be {@code null}.
+ * @param opposite The other Window involved in the
* focus or activation change, or null
* @throws IllegalArgumentException if source is null
+ * @see #getWindow()
+ * @see #getID()
+ * @see #getOppositeWindow()
* @since 1.4
*/
public WindowEvent(Window source, int id, Window opposite) {
@@ -236,21 +251,30 @@ public class WindowEvent extends ComponentEvent {
/**
* Constructs a WindowEvent object with the specified
* previous and new window states.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the Window object
+ * @param source The Window object
* that originated the event
- * @param id WINDOW_STATE_CHANGED event type.
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link WindowEvent}.
* It is expected that this constructor will not
- * be used for other WindowEvent
+ * be used for other then
+ * {@code WINDOW_STATE_CHANGED}
+ * {@code WindowEvent}
* types, because the previous and new window
* states are meaningless for other event types.
- * @param oldState an integer representing the previous window state
- * @param newState an integer representing the new window state
+ * @param oldState An integer representing the previous window state.
+ * See {@code #getOldState()} for allowable values
+ * @param newState An integer representing the new window state.
+ * See {@code #getNewState()} for allowable values
* @throws IllegalArgumentException if source is null
+ * @see #getWindow()
+ * @see #getID()
+ * @see #getOldState()
+ * @see #getNewState()
* @since 1.4
*/
public WindowEvent(Window source, int id, int oldState, int newState) {
@@ -259,14 +283,17 @@ public class WindowEvent extends ComponentEvent {
/**
* Constructs a WindowEvent object.
- *
Note that passing in an invalid id results in
- * unspecified behavior. This method throws an
+ *
This method throws an
* IllegalArgumentException if source
* is null.
*
- * @param source the Window object that originated the event
- * @param id an integer indicating the type of event
+ * @param source The Window object that originated the event
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link WindowEvent}.
* @throws IllegalArgumentException if source is null
+ * @see #getWindow()
+ * @see #getID()
*/
public WindowEvent(Window source, int id) {
this(source, id, null, 0, 0);