6520716: event classes lack info about parameters
Summary: clarify allowed values for event constructors
Reviewed-by: son, denis
--- a/jdk/src/share/classes/java/awt/dnd/DragGestureEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/dnd/DragGestureEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -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
@@ -55,9 +55,19 @@
* platform dependent drag initiating gesture has occurred
* on the <code>Component</code> that it is tracking.
*
+ * The {@code action} field of any {@code DragGestureEvent} instance should take one of the following
+ * values:
+ * <ul>
+ * <li> {@code DnDConstants.ACTION_COPY}
+ * <li> {@code DnDConstants.ACTION_MOVE}
+ * <li> {@code DnDConstants.ACTION_LINK}
+ * </ul>
+ * Assigning the value different from listed above will cause an unspecified behavior.
+ *
* @see java.awt.dnd.DragGestureRecognizer
* @see java.awt.dnd.DragGestureListener
* @see java.awt.dnd.DragSource
+ * @see java.awt.dnd.DnDConstants
*/
public class DragGestureEvent extends EventObject {
@@ -65,19 +75,25 @@
private static final long serialVersionUID = 9080172649166731306L;
/**
- * Constructs a <code>DragGestureEvent</code> given the
- * <code>DragGestureRecognizer</code> firing this event,
- * an <code>int</code> representing
- * the user's preferred action, a <code>Point</code>
- * indicating the origin of the drag, and a <code>List</code>
- * of events that comprise the gesture.
+ * Constructs a <code>DragGestureEvent</code> object given by the
+ * <code>DragGestureRecognizer</code> 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).
* <P>
* @param dgr The <code>DragGestureRecognizer</code> 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 <code>List</code> of events that comprise the gesture
* <P>
- * @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,
--- a/jdk/src/share/classes/java/awt/dnd/DropTargetEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/dnd/DropTargetEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -45,10 +45,13 @@
private static final long serialVersionUID = 2821229066521922993L;
/**
- * Construct a <code>DropTargetEvent</code> with
- * a specified <code>DropTargetContext</code>.
+ * Construct a <code>DropTargetEvent</code> object with
+ * the specified <code>DropTargetContext</code>.
* <P>
- * @param dtc the <code>DropTargetContext</code>
+ * @param dtc The <code>DropTargetContext</code>
+ * @throws NullPointerException if {@code dtc} equals {@code null}.
+ * @see #getSource()
+ * @see #getDropTargetContext()
*/
public DropTargetEvent(DropTargetContext dtc) {
--- a/jdk/src/share/classes/java/awt/event/ActionEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/ActionEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -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 @@
* is therefore spared the details of processing individual mouse movements
* and mouse clicks, and can instead process a "meaningful" (semantic)
* event like "button pressed".
+ * <p>
+ * 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 <a href="http://java.sun.com/docs/books/tutorial/post1.0/ui/eventmodel.html">Tutorial: Java 1.1 Event Model</a>
@@ -134,18 +138,22 @@
/**
* Constructs an <code>ActionEvent</code> object.
* <p>
- * Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
* A <code>null</code> <code>command</code> 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 <code>source</code> 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 @@
/**
* Constructs an <code>ActionEvent</code> object with modifier keys.
* <p>
- * Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
* A <code>null</code> <code>command</code> 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 <code>source</code> 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 @@
* Constructs an <code>ActionEvent</code> object with the specified
* modifier keys and timestamp.
* <p>
- * Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
* A <code>null</code> <code>command</code> 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 <code>source</code> is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getActionCommand()
+ * @see #getModifiers()
+ * @see #getWhen()
*
* @since 1.4
*/
--- a/jdk/src/share/classes/java/awt/event/AdjustmentEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/AdjustmentEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -29,7 +29,25 @@
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}.
+ * <p>
+ * 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}.
+ * <p>
+ * The {@code type} of any {@code AdjustmentEvent} instance takes one of the following
+ * values:
+ * <ul>
+ * <li> {@code UNIT_INCREMENT}
+ * <li> {@code UNIT_DECREMENT}
+ * <li> {@code BLOCK_INCREMENT}
+ * <li> {@code BLOCK_DECREMENT}
+ * <li> {@code TRACK}
+ * </ul>
+ * Assigning the value different from listed above will cause an unspecified behavior.
* @see java.awt.Adjustable
* @see AdjustmentListener
*
@@ -130,17 +148,24 @@
* Constructs an <code>AdjustmentEvent</code> object with the
* specified <code>Adjustable</code> source, event type,
* adjustment type, and value.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p> This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Adjustable</code> object where the
+ * @param source The <code>Adjustable</code> 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 <code>source</code> 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 @@
/**
* Constructs an <code>AdjustmentEvent</code> object with the
* specified Adjustable source, event type, adjustment type, and value.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p> This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
-
*
- * @param source the <code>Adjustable</code> object where the
+ * @param source The <code>Adjustable</code> 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 <code>true</code> 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 <code>true</code> if the event is one
* of a series of multiple adjusting events,
* otherwise <code>false</code>
* @throws IllegalArgumentException if <code>source</code> 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);
--- a/jdk/src/share/classes/java/awt/event/ComponentEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/ComponentEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -52,6 +52,10 @@
* (<code>ComponentAdapter</code> objects implement the
* <code>ComponentListener</code> interface.) Each such listener object
* gets this <code>ComponentEvent</code> when the event occurs.
+ * <p>
+ * 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 @@
/**
* Constructs a <code>ComponentEvent</code> object.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p> This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Component</code> that originated the event
- * @param id an integer indicating the type of event
+ * @param source The <code>Component</code> 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 <code>source</code> is null
+ * @see #getComponent()
+ * @see #getID()
*/
public ComponentEvent(Component source, int id) {
super(source, id);
--- a/jdk/src/share/classes/java/awt/event/ContainerEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/ContainerEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -45,6 +45,10 @@
* (<code>ContainerAdapter</code> objects implement the
* <code>ContainerListener</code> interface.) Each such listener object
* gets this <code>ContainerEvent</code> when the event occurs.
+ * <p>
+ * 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 @@
/**
* Constructs a <code>ContainerEvent</code> object.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p> This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Component</code> object (container)
+ * @param source The <code>Component</code> 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 <code>source</code> is null
+ * @see #getContainer()
+ * @see #getID()
+ * @see #getChild()
*/
public ContainerEvent(Component source, int id, Component child) {
super(source, id);
--- a/jdk/src/share/classes/java/awt/event/FocusEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/FocusEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -50,6 +50,10 @@
* 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.
+ * <p>
+ * 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 @@
* application, with a Java application in a different VM,
* or with no other <code>Component</code>, then the opposite
* <code>Component</code> is <code>null</code>.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p> This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Component</code> that originated the event
- * @param id <code>FOCUS_GAINED</code> or <code>FOCUS_LOST</code>
- * @param temporary <code>true</code> if the focus change is temporary;
+ * @param source The <code>Component</code> 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 <code>true</code> if the focus change is temporary;
* <code>false</code> otherwise
- * @param opposite the other Component involved in the focus change,
+ * @param opposite The other Component involved in the focus change,
* or <code>null</code>
- * @throws IllegalArgumentException if <code>source</code> is null
+ * @throws IllegalArgumentException if <code>source</code> 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 @@
/**
* Constructs a <code>FocusEvent</code> object and identifies
* whether or not the change is temporary.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p> This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Component</code> that originated the event
- * @param id an integer indicating the type of event
- * @param temporary <code>true</code> if the focus change is temporary;
+ * @param source The <code>Component</code> 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 <code>true</code> if the focus change is temporary;
* <code>false</code> otherwise
- * @throws IllegalArgumentException if <code>source</code> is null
+ * @throws IllegalArgumentException if <code>source</code> 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 @@
/**
* Constructs a <code>FocusEvent</code> object and identifies it
* as a permanent change in focus.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p> This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Component</code> that originated the event
- * @param id an integer indicating the type of event
- * @throws IllegalArgumentException if <code>source</code> is null
+ * @param source The <code>Component</code> 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 <code>source</code> equals {@code null}
+ * @see #getSource()
+ * @see #getID()
*/
public FocusEvent(Component source, int id) {
this(source, id, false);
--- a/jdk/src/share/classes/java/awt/event/HierarchyEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/HierarchyEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -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 @@
/**
* An event which indicates a change to the <code>Component</code>
- * hierarchy to which a <code>Component</code> belongs.
+ * hierarchy to which <code>Component</code> belongs.
* <ul>
* <li>Hierarchy Change Events (HierarchyListener)
* <ul>
@@ -58,16 +58,30 @@
* Container is added, removed, moved, or resized, and passed down the
* hierarchy. It is also generated by a Component object when that object's
* <code>addNotify</code>, <code>removeNotify</code>, <code>show</code>, or
- * <code>hide</code> method is called. ANCESTOR_MOVED and ANCESTOR_RESIZED
+ * <code>hide</code> method is called. The {@code ANCESTOR_MOVED} and
+ * {@code ANCESTOR_RESIZED}
* events are dispatched to every <code>HierarchyBoundsListener</code> or
* <code>HierarchyBoundsAdapter</code> object which registered to receive
* such events using the Component's <code>addHierarchyBoundsListener</code>
* method. (<code>HierarchyBoundsAdapter</code> objects implement the <code>
- * HierarchyBoundsListener</code> interface.) HIERARCHY_CHANGED events are
+ * HierarchyBoundsListener</code> interface.) The {@code HIERARCHY_CHANGED} events are
* dispatched to every <code>HierarchyListener</code> object which registered
* to receive such events using the Component's <code>addHierarchyListener
* </code> method. Each such listener object gets this <code>HierarchyEvent
* </code> when the event occurs.
+ * <p>
+ * 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}.
+ * <br>
+ * The {@code changeFlags} parameter of any {@code HierarchyEvent} instance takes one of the following
+ * values:
+ * <ul>
+ * <li> {@code HierarchyEvent.PARENT_CHANGED}
+ * <li> {@code HierarchyEvent.DISPLAYABILITY_CHANGED}
+ * <li> {@code HierarchyEvent.SHOWING_CHANGED}
+ * </ul>
+ * Assigning the value different from listed above will cause unspecified behavior.
*
* @author David Mendenhall
* @see HierarchyListener
@@ -108,20 +122,20 @@
public static final int HIERARCHY_LAST = ANCESTOR_RESIZED;
/**
- * Indicates that the <code>HIERARCHY_CHANGED</code> event
+ * A change flag indicates that the <code>HIERARCHY_CHANGED</code> event
* was generated by a reparenting operation.
*/
public static final int PARENT_CHANGED = 0x1;
/**
- * Indicates that the <code>HIERARCHY_CHANGED</code> event
- * was generated due to a change in the displayability
- * of the hierarchy. To discern the
- * current displayability of the hierarchy, call
- * <code>Component.isDisplayable</code>. Displayability changes occur
- * in response to explicit or implicit calls to
+ * A change flag indicates that the <code>HIERARCHY_CHANGED</code> event
+ * was generated due to the changing of the hierarchy displayability.
+ * To discern the
+ * current displayability of the hierarchy, call the
+ * <code>Component.isDisplayable</code> method. Displayability changes occur
+ * in response to explicit or implicit calls of the
* <code>Component.addNotify</code> and
- * <code>Component.removeNotify</code>.
+ * <code>Component.removeNotify</code> methods.
*
* @see java.awt.Component#isDisplayable()
* @see java.awt.Component#addNotify()
@@ -130,15 +144,15 @@
public static final int DISPLAYABILITY_CHANGED = 0x2;
/**
- * Indicates that the <code>HIERARCHY_CHANGED</code> event
- * was generated due to a change in the showing state
- * of the hierarchy. To discern the
- * current showing state of the hierarchy, call
- * <code>Component.isShowing</code>. Showing state changes occur
+ * A change flag indicates that the <code>HIERARCHY_CHANGED</code> event
+ * was generated due to the changing of the hierarchy showing state.
+ * To discern the
+ * current showing state of the hierarchy, call the
+ * <code>Component.isShowing</code> 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 <code>Component.show</code> and
- * <code>Component.hide</code>.
+ * or implicit calls of the <code>Component.show</code> and
+ * <code>Component.hide</code> methods.
*
* @see java.awt.Component#isShowing()
* @see java.awt.Component#addNotify()
@@ -155,20 +169,26 @@
/**
* Constructs an <code>HierarchyEvent</code> object to identify a
* change in the <code>Component</code> hierarchy.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p>This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Component</code> object that
+ * @param source The <code>Component</code> object that
* originated the event
- * @param id an integer indicating the type of event
- * @param changed the <code>Component</code> 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 <code>Component</code> at the top of
* the hierarchy which was changed
- * @param changedParent the parent of <code>changed</code>; this
+ * @param changedParent The parent of the <code>changed</code> component.
+ * This
* may be the parent before or after the
* change, depending on the type of change
- * @throws IllegalArgumentException if <code>source</code> is null
+ * @throws IllegalArgumentException if <code>source</code> 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 @@
/**
* Constructs an <code>HierarchyEvent</code> object to identify
* a change in the <code>Component</code> hierarchy.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p> This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Component</code> object that
+ * @param source The <code>Component</code> object that
* originated the event
- * @param id an integer indicating the type of event
- * @param changed the <code>Component</code> 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 <code>Component</code> at the top
* of the hierarchy which was changed
- * @param changedParent the parent of <code>changed</code>; this
+ * @param changedParent The parent of the <code>changed</code> 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
- * <code>HIERARCHY_CHANGED</code> events
- * represented in this event object
+ * @param changeFlags A bitmask which indicates the type(s) of
+ * the <code>HIERARCHY_CHANGED</code> events
+ * represented in this event object.
+ * For information on allowable values, see
+ * the class description for {@link HierarchyEvent}
* @throws IllegalArgumentException if <code>source</code> is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getChanged()
+ * @see #getChangedParent()
+ * @see #getChangeFlags()
*/
public HierarchyEvent(Component source, int id, Component changed,
Container changedParent, long changeFlags) {
--- a/jdk/src/share/classes/java/awt/event/InputEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/InputEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -208,17 +208,32 @@
/**
* Constructs an InputEvent object with the specified source component,
* modifiers, and type.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p> This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
* @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 <code>source</code> 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 @@
}
/**
- * 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 @@
* 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.
+ * <code>awt.properties</code> file.
+ * <p>
+ * 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
--- a/jdk/src/share/classes/java/awt/event/InvocationEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/InvocationEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -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 @@
* can use this fact to write replacement functions for <code>invokeLater
* </code> and <code>invokeAndWait</code> without writing special-case code
* in any <code>AWTEventListener</code> objects.
+ * <p>
+ * 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 @@
* <p> This method throws an <code>IllegalArgumentException</code>
* if <code>source</code> is <code>null</code>.
*
- * @param source the <code>Object</code> that originated the event
- * @param runnable the <code>Runnable</code> whose <code>run</code>
+ * @param source The <code>Object</code> that originated the event
+ * @param runnable The <code>Runnable</code> whose <code>run</code>
* method will be executed
* @throws IllegalArgumentException if <code>source</code> 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 @@
* <p>This method throws an <code>IllegalArgumentException</code>
* if <code>source</code> is <code>null</code>.
*
- * @param source the <code>Object</code> that originated
+ * @param source The <code>Object</code> that originated
* the event
- * @param runnable the <code>Runnable</code> whose
+ * @param runnable The <code>Runnable</code> whose
* <code>run</code> method will be
* executed
- * @param notifier the Object whose <code>notifyAll</code>
+ * @param notifier The {@code Object} whose <code>notifyAll</code>
* method will be called after
* <code>Runnable.run</code> has returned
- * @param catchThrowables specifies whether <code>dispatch</code>
+ * @param catchThrowables Specifies whether <code>dispatch</code>
* should catch Throwable when executing
* the <code>Runnable</code>'s <code>run</code>
* method, or should instead propagate those
@@ -163,6 +168,7 @@
* dispatch loop
* @throws IllegalArgumentException if <code>source</code> is null
*
+ * @see #getSource()
* @see #InvocationEvent(Object, int, Runnable, Object, boolean)
*/
public InvocationEvent(Object source, Runnable runnable, Object notifier,
@@ -176,26 +182,29 @@
* method when dispatched. If notifier is non-<code>null</code>,
* <code>notifyAll</code> will be called on it
* immediately after <code>run</code> returns.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p>This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Object</code> that originated
+ * @param source The <code>Object</code> that originated
* the event
- * @param id the ID for the event
- * @param runnable the <code>Runnable</code> 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 <code>Runnable</code> whose
* <code>run</code> method will be executed
- * @param notifier the <code>Object</code> whose <code>notifyAll</code>
+ * @param notifier The <code>Object</code> whose <code>notifyAll</code>
* method will be called after
* <code>Runnable.run</code> has returned
- * @param catchThrowables specifies whether <code>dispatch</code>
+ * @param catchThrowables Specifies whether <code>dispatch</code>
* should catch Throwable when executing the
* <code>Runnable</code>'s <code>run</code>
* method, or should instead propagate those
* Throwables to the EventDispatchThread's
* dispatch loop
* @throws IllegalArgumentException if <code>source</code> is null
+ * @see #getSource()
+ * @see #getID()
*/
protected InvocationEvent(Object source, int id, Runnable runnable,
Object notifier, boolean catchThrowables) {
--- a/jdk/src/share/classes/java/awt/event/ItemEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/ItemEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -41,6 +41,18 @@
* 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".
+ * <p>
+ * 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}.
+ * <p>
+ * The {@code stateChange} of any {@code ItemEvent} instance takes one of the following
+ * values:
+ * <ul>
+ * <li> {@code ItemEvent.SELECTED}
+ * <li> {@code ItemEvent.DESELECTED}
+ * </ul>
+ * Assigning the value different from listed above will cause an unspecified behavior.
*
* @author Carl Quinn
*
@@ -101,19 +113,24 @@
/**
* Constructs an <code>ItemEvent</code> object.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p> This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>ItemSelectable</code> object
+ * @param source The <code>ItemSelectable</code> 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 <code>source</code> is null
+ * @see #getItemSelectable()
+ * @see #getID()
+ * @see #getStateChange()
*/
public ItemEvent(ItemSelectable source, int id, Object item, int stateChange) {
super(source, id);
--- a/jdk/src/share/classes/java/awt/event/KeyEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/KeyEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -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 @@
* (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.
+ * <p>
+ * 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 @@
/**
* Constructs a <code>KeyEvent</code> object.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p>This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Component</code> 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 <code>Component</code> 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 <code>KEY_LOCATION_UNKNOWN</code>,
* <code>KEY_LOCATION_STANDARD</code>, <code>KEY_LOCATION_LEFT</code>,
* <code>KEY_LOCATION_RIGHT</code>, and <code>KEY_LOCATION_NUMPAD</code>.
@@ -948,6 +957,13 @@
* or if <code>keyLocation</code> is not one of the legal
* values enumerated above.
* @throws IllegalArgumentException if <code>source</code> 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 @@
/**
* Constructs a <code>KeyEvent</code> object.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p> This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Component</code> 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 <code>Component</code> 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 <code>id</code> is
@@ -1008,6 +1029,12 @@
* <code>KEY_TYPED</code> and <code>keyCode</code> is not
* <code>VK_UNDEFINED</code>
* @throws IllegalArgumentException if <code>source</code> 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) {
--- a/jdk/src/share/classes/java/awt/event/MouseEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/MouseEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -159,6 +159,11 @@
* The reported coordinates for mouse drag events are clipped to fit within the
* bounds of the virtual device associated with the <code>Component</code>.
* </ul>
+ * <p>
+ * 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 @@
* specified source component,
* type, modifiers, coordinates, and click count.
* <p>
- * Note that passing in an invalid <code>id</code> 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 @@
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Component</code> 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 <code>Component</code> 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.
- * <code>NOBUTTON</code>,
- * <code>BUTTON1</code>,
- * <code>BUTTON2</code> or
- * <code>BUTTON3</code>.
+ * 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 <code>button</code>
* value is passed in
* @throws IllegalArgumentException if <code>source</code> 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 @@
* Constructs a <code>MouseEvent</code> object with the
* specified source component,
* type, modifiers, coordinates, and click count.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior.
* An invocation of the form
* <tt>MouseEvent(source, id, when, modifiers, x, y, clickCount, popupTrigger)</tt>
* behaves in exactly the same way as the invocation
@@ -493,21 +511,39 @@
* This method throws an <code>IllegalArgumentException</code>
* if <code>source</code> is <code>null</code>.
*
- * @param source the <code>Component</code> 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 <code>Component</code> 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 <code>source</code> 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 @@
* specified source component,
* type, modifiers, coordinates, absolute coordinates, and click count.
* <p>
- * Note that passing in an invalid <code>id</code> 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 @@
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Component</code> 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 <code>Component</code> 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.
- * <code>NOBUTTON</code>,
- * <code>BUTTON1</code>,
- * <code>BUTTON2</code> or
- * <code>BUTTON3</code>.
+ * 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 <code>button</code>
* value is passed in
* @throws IllegalArgumentException if <code>source</code> 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 @@
}
/**
- * Returns a <code>String</code> describing the modifier keys and
+ * Returns a <code>String</code> 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 <code>awt.properties</code> file.
* <p>
- * Note that <code>InputEvent.ALT_MASK</code> and
- * <code>InputEvent.BUTTON2_MASK</code> have the same value,
- * so the string "Alt" is returned for both modifiers. Likewise,
- * <code>InputEvent.META_MASK</code> and
- * <code>InputEvent.BUTTON3_MASK</code> have the same value,
- * so the string "Meta" is returned for both modifiers.
+ * Note that the <code>InputEvent.ALT_MASK</code> and
+ * <code>InputEvent.BUTTON2_MASK</code> have equal values,
+ * so the "Alt" string is returned for both modifiers. Likewise,
+ * the <code>InputEvent.META_MASK</code> and
+ * <code>InputEvent.BUTTON3_MASK</code> have equal values,
+ * so the "Meta" string is returned for both modifiers.
+ * <p>
+ * 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
--- a/jdk/src/share/classes/java/awt/event/MouseWheelEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/MouseWheelEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -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
--- a/jdk/src/share/classes/java/awt/event/PaintEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/PaintEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -36,6 +36,10 @@
* designed to be used with the Event Listener model; programs
* should continue to override paint/update methods in order
* render themselves properly.
+ * <p>
+ * 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 @@
/**
* Constructs a <code>PaintEvent</code> object with the specified
* source component and type.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p> This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @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 <code>source</code> is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getUpdateRect()
*/
public PaintEvent(Component source, int id, Rectangle updateRect) {
super(source, id);
--- a/jdk/src/share/classes/java/awt/event/TextEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/TextEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -38,6 +38,10 @@
* this <code>TextEvent</code> 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".
+ * <p>
+ * 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 @@
/**
* Constructs a <code>TextEvent</code> object.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p> This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the (<code>TextComponent</code>) object that
+ * @param source The (<code>TextComponent</code>) 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 <code>source</code> is null
+ * @see #getSource()
+ * @see #getID()
*/
public TextEvent(Object source, int id) {
super(source, id);
--- a/jdk/src/share/classes/java/awt/event/WindowEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/WindowEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -41,6 +41,10 @@
* (<code>WindowAdapter</code> objects implement the
* <code>WindowListener</code> interface.) Each such listener object
* gets this <code>WindowEvent</code> when the event occurs.
+ * <p>
+ * 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 @@
/**
* Constructs a <code>WindowEvent</code> object.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p>This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Window</code> object
+ * @param source The <code>Window</code> 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 <code>null</code>
- * @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 <code>source</code> 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 @@
* If this focus change occurs with a native application, with a
* Java application in a different VM, or with no other
* <code>Window</code>, then the opposite Window is <code>null</code>.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p>This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Window</code> object that
+ * @param source The <code>Window</code> object that
* originated the event
- * @param id <code>WINDOW_ACTIVATED</code>,
- * <code>WINDOW_DEACTIVATED</code>,
- * <code>WINDOW_GAINED_FOCUS</code>,
- * or <code>WINDOW_LOST_FOCUS</code>. It is
- * expected that this constructor will not be used for
- * other <code>WindowEvent</code> types because the
- * opposite <code>Window</code> of such events
- * will always be <code>null</code>
- * @param opposite the other <code>Window</code> 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 <code>Window</code> of other event types
+ * will always be {@code null}.
+ * @param opposite The other <code>Window</code> involved in the
* focus or activation change, or <code>null</code>
* @throws IllegalArgumentException if <code>source</code> is null
+ * @see #getWindow()
+ * @see #getID()
+ * @see #getOppositeWindow()
* @since 1.4
*/
public WindowEvent(Window source, int id, Window opposite) {
@@ -236,21 +251,30 @@
/**
* Constructs a <code>WindowEvent</code> object with the specified
* previous and new window states.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p>This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Window</code> object
+ * @param source The <code>Window</code> object
* that originated the event
- * @param id <code>WINDOW_STATE_CHANGED</code> 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 <code>WindowEvent</code>
+ * 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 <code>source</code> 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 @@
/**
* Constructs a <code>WindowEvent</code> object.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p>This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Window</code> object that originated the event
- * @param id an integer indicating the type of event
+ * @param source The <code>Window</code> 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 <code>source</code> is null
+ * @see #getWindow()
+ * @see #getID()
*/
public WindowEvent(Window source, int id) {
this(source, id, null, 0, 0);