:-) I am a bit of API zealot, so I don't expect you to agree with me,
and I don't know where to start. To sample the obvious, Component has
for instance the following methods;
public Point mapPointFromAncestor(Container ancestor, int x, int y)
public Point mapPointToAncestor(Container ancestor, int x, int y)
These are convenience methods for translating between coordinate
systems. You might use them, for example, if you had registered a
mouse listener on the display but needed the mouse location in a
particular component's coordinate space. Other toolkits have similar
methods.
public Display getDisplay()
A Display represents the root of a component hierarchy. Originally, we
had a single Display singleton, but that doesn't work when multiple
applets from the same origin are hosted in a single page (since all
the applets run in the same JVM instance). So, we support multiple
Display instances in the same JVM so the applets don't stomp on each
other.
public Graphics2D getGraphics()
This returns a graphics context that can be used to draw on a
component directly. AWT has a similar method. However, it is currently
only used by ScrollPane, and may no longer be necessary if we change
the way scroll panes optimize scrolling. Todd can comment better on
this.
There is a method
public Skin getSkin()
Are you talking about Component#getSkin()? If so, that method is
protected. Maybe you assumed it was public because it appears in the
Javadoc?
All containers have a method;
public final int add(Component component)
yet, many containers are not using it as its primary populator, off my
head I recall Accordion.getPanels().add() or something like that. If
only a small number of Containers are actually using the add(), it
should exist at that level, IMHO.
Skins often use this method to add other components to the container.
For example, TerraTabPaneSkin adds tab button components. The "tabs"
collection allows the caller (and the skin) to distinguish between
components that are actually tabs and those that are not.
Then there is stuff I am less sure about;
Component.validate() sounds like an internal method between a
Container and its children.
It is, but it needs to be public, primarily so skins can call it.
Also, there's no reason for it not to be public - it isn't harmful.
Component.paint( Graphics2D graphics ) --> same thing.
Again, there is no reason for this method not to be public - and,
there are valid use cases for making it public (for example, taking a
screen shot of a component). Note that the paint() method is also
public in AWT.
Component.getAttributes() --> is 'protected' but none of the existing
sub-components calls it.
Making it protected allows 3rd party components to also define
attributes.
Also, Attributes sound
like something that should be properly typed and not a 'guess my type'
Object.
The definition of the type is up to the subclass. Attributes are
strongly typed within containers that use them.
So, nah, you won't get an A for API Design... ;-)
Conversely, if you were taking my API design class, you might not
score a particularly high grade yourself. :-)
