Name: rmT116609 Date: 05/28/2003


A DESCRIPTION OF THE PROBLEM :
The javax.swing.JTable documentation doesn't seem to describe JTable's
behavior regarding row or cell focus (the highlighting that moves when
you press e.g., the up and down arrow keys, unless possibly that's a lead
selection index (without being selected)).

Also, the JTable and other documentation (at least ListSelectionModel)
doesn't seem to say anything about the relationship between drags,
clicks, and keystrokes on one hand and selection anchors and leads
on the other.

(In my case, I'm looking for documention on several interacting areas of
behavior to diagnose this symptom:
I:
- select N rows (mouse or keyboard)
- invoke an action
- programmatically de-select the rows
- programmatically select the next row
- remove the rows
The focus ends up about N (or N-1) rows down from where I expected it
(the "next row" above).

Various documentation appears to be insufficient for finding my programming
error(s). For example:

In general, there seems to be no documentation describing:
- row and/or cell focus behavior
- selection gestures
- anchor and lead indices
or, more specifically:
- any specific requirements for keeping focus synchronized with selection
  changes or row deletions automatically
- how to get or set the focused row manually
- (even whether the blue cell/row outline I see (in whichever look-and-feel
  I'm getting) is really the focus is or is possibly something else)
- the relationships between mouse- and key-driven selection and anchor
  and lead indices

Note: I'm rating this "Difficult to make even minimal progress without
resolving this bug" instead of "Can not make any progress until this bug
is resolved" because the source code is available. Othersise, I think
it would be a lot closer to "cannot make progress."

P.S. You might suggest in documentation guidelines or reminders considering
listing and documenting the concepts and attributes of a class in the class
description (instead of in the getter/setter/etc. methods).


EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
In general terms:
- a bit more orientation to concepts and high-level features
  (not just listing the methods and documenting what they do individually,
  but (in the class description) listing the concepts and features and
  documenting them to some degree)
- the details that developers need


URL OF FAULTY DOCUMENTATION :
http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JTable.html
http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JTable.html#getScrollableTracksViewportWidth()
(Review ID: 186632)
======================================================================