stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

6520716: event classes lack info about parameters

Browse Source 
Clarify allowed values for event constructors

Reviewed-by: son, denis
This commit is contained in:
Andrei Dmitriev 2008-04-08 12:46:39 +04:00
parent d21a0af975
commit 5887f56e62
17 changed files with 591 additions and 277 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
jdk/src/share/classes/java/awt/dnd/DragGestureEvent.java
View File

@ -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 @@ import java.io.ObjectOutputStream;
* 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 @@ public class DragGestureEvent extends EventObject {
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,

9
jdk/src/share/classes/java/awt/dnd/DropTargetEvent.java
View File

@ -45,10 +45,13 @@ public class DropTargetEvent extends java.util.EventObject {
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) {

69
jdk/src/share/classes/java/awt/event/ActionEvent.java
View File

@ -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".
* <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 @@ public class ActionEvent extends AWTEvent {
/**
* 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 @@ public class ActionEvent extends AWTEvent {
/**
* 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 @@ public class ActionEvent extends AWTEvent {
* 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
*/

62
jdk/src/share/classes/java/awt/event/AdjustmentEvent.java
View File

@ -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}.
* <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 @@ public class AdjustmentEvent extends AWTEvent {
* 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 @@ public class AdjustmentEvent extends AWTEvent {
/**
* 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);

15
jdk/src/share/classes/java/awt/event/ComponentEvent.java
View File

@ -52,6 +52,10 @@ import java.awt.Rectangle;
* (<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 @@ public class ComponentEvent extends AWTEvent {
/**
* 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);

16
jdk/src/share/classes/java/awt/event/ContainerEvent.java
View File

@ -45,6 +45,10 @@ import java.awt.Component;
* (<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 @@ public class ContainerEvent extends ComponentEvent {
/**
* 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);

52
jdk/src/share/classes/java/awt/event/FocusEvent.java
View File

@ -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.
* <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 @@ public class FocusEvent extends ComponentEvent {
* 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 @@ public class FocusEvent extends ComponentEvent {
/**
* 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 @@ public class FocusEvent extends ComponentEvent {
/**
* 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);

99
jdk/src/share/classes/java/awt/event/HierarchyEvent.java
View File

@ -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 <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 @@ import java.awt.Container;
* 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 class HierarchyEvent extends AWTEvent {
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 class HierarchyEvent extends AWTEvent {
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 @@ public class HierarchyEvent extends AWTEvent {
/**
* 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 @@ public class HierarchyEvent extends AWTEvent {
/**
* 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) {

37
jdk/src/share/classes/java/awt/event/InputEvent.java
View File

@ -208,17 +208,32 @@ public abstract class InputEvent extends ComponentEvent {
/**
* 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 @@ 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.
* <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

39
jdk/src/share/classes/java/awt/event/InvocationEvent.java
View File

@ -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 <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 @@ public class InvocationEvent extends AWTEvent implements ActiveEvent {
* <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 @@ public class InvocationEvent extends AWTEvent implements ActiveEvent {
* <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 @@ public class InvocationEvent extends AWTEvent implements ActiveEvent {
* 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 @@ public class InvocationEvent extends AWTEvent implements ActiveEvent {
* 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) {

33
jdk/src/share/classes/java/awt/event/ItemEvent.java
View File

@ -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".
* <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 @@ public class ItemEvent extends AWTEvent {
/**
* 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);

87
jdk/src/share/classes/java/awt/event/KeyEvent.java
View File

@ -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.
* <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 @@ public class KeyEvent extends InputEvent {
/**
* 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 @@ public class KeyEvent extends InputEvent {
* 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 @@ public class KeyEvent extends InputEvent {
/**
* 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 @@ public class KeyEvent extends InputEvent {
* <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) {

192
jdk/src/share/classes/java/awt/event/MouseEvent.java
View File

@ -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 <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 @@ public class MouseEvent extends InputEvent {
* 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 @@ public class MouseEvent extends InputEvent {
* <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 @@ public class MouseEvent extends InputEvent {
* 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 @@ public class MouseEvent extends InputEvent {
* 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 @@ public class MouseEvent extends InputEvent {
* 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 @@ public class MouseEvent extends InputEvent {
* <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 @@ public class MouseEvent extends InputEvent {
}
/**
* 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

2
jdk/src/share/classes/java/awt/event/MouseWheelEvent.java
View File

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

18
jdk/src/share/classes/java/awt/event/PaintEvent.java
View File

@ -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.
* <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 @@ public class PaintEvent extends ComponentEvent {
/**
* 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);

15
jdk/src/share/classes/java/awt/event/TextEvent.java
View File

@ -38,6 +38,10 @@ import java.awt.AWTEvent;
* 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 @@ public class TextEvent extends AWTEvent {
/**
* 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);

89
jdk/src/share/classes/java/awt/event/WindowEvent.java
View File

@ -41,6 +41,10 @@ import sun.awt.SunToolkit;
* (<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 @@ public class WindowEvent extends ComponentEvent {
/**
* 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 @@ 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
* <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 @@ public class WindowEvent extends ComponentEvent {
/**
* 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 @@ public class WindowEvent extends ComponentEvent {
/**
* 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);