###@###.### 2001-09-07

comments from a CAP member regarding Container.validate doc:

------------------------------------------------------------
Understanding this aspect of the Java repaint system is basically impossible
based on the documentation. I have read the api docs many times, and usually
give up and randomly try a sequence of invalidates and validates until it works.
This is the same for everyone else I know. Here is the current detailed
documentation for the complex issues involved in repainting (from the 1.4
Container.validate doc):

   Validates this container and all of its subcomponents.
   AWT uses validate to cause a container to lay out its subcomponents
   again after the components it contains have been added to or modified.

From invalidate:

    Invalidates the container. The container and all parents above it are
    marked as needing to be laid out. This method can be called often, so it
    needs to execute quickly.

This talks about layout, not about repainting. When do these need to be called?
What are the efficiency issues? When does the repaint actually happen? Why are
these necessary?

The api docs are really pretty minimal for many of these crucial functions. I
understood this for 1.1 when Java was new, but this is now *years* later, and
this crucial documentation is still as unhelpful as it was originally. If you
really want people to be able to program this without wasted time and
frustration, the semantics of the repaint and layout system need to be made
clear - with examples *in* the api docs (where most people look). And ideally,
the entire need for validate would be removed.