Name: gm110360 Date: 03/29/2002


FULL PRODUCT VERSION :
java version "1.4.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-b92)
Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)


FULL OPERATING SYSTEM VERSION : Windows 98 2nd ed. [Version
4.10.2222]


A DESCRIPTION OF THE PROBLEM :
I'm a new Java developer trying to figure out how to catch
changes in displayability for my AWT JComponent. My path
quickly led me to the SDK documentation for
java.awt.event.HierarchyEvent. Here, the constant
DISPLAYABILITY_CHANGED is mentioned in the documentation,
but scant hint as to its use is provided. It took me some
time to learn that this was not an event ID (to be used in
conjunction with getID()), but instead an event mask bit
that should be used in conjunction with
HierarchyEvent.getChangeFlags():

if ((event.getID()==HierarchyEvent.HIERARCHY_CHANGED)
  && ((event.getChangeFlags()
     & HierarchyEvent.DISPLAYABILITY_CHANGED) != 0))
{
  // check displayability and act accordingly
}


The documentation would have been much more helpful to me
if, in this and other similar cases (e.g. ActionEvent,
AdjustmentEvent, ItemEvent), the documentation clearly
  stated, under each event-related constant, with what field
it is intended to be used with (including a cross-link to
the related accessor), and where the context might be
unclear, whether it is an ID (i.e. to be used with a simple
equality test) or a bit mask (i.e. to be used with masking
operations). A quick explanation of additional data
associated with these events in the class overview would be
helpful as well.


STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. See the file:
j2sdk1.4.0/docs/api/java/awt/event/HierarchyEvent.html
2. Look at the documentation under DISPLAYABILITY_CHANGED,
SHOWING_CHANGED, etc.
3. Pretend you're seeing this for the first time, and
ponder how these constants 'indicate' whatever it is
they're supposed to be indicating...


This bug can be reproduced always.
(Review ID: 144753)
======================================================================