Name: pa48320 Date: 11/29/2001


When an application that uses partial or completely overlapping stacked canvases is implemented using Java, it usually
requires creating a lightweight panel for each stacked canvas and
adding all those panels as children of some top level lightweight
window. Each panel can in turn contain a number of components.

During application execution, those canvases need to be raised
and lowered programmatically. A common case is that the user
uses the keyboard to navigate to a text component on a canvas
which is currently obscured by another canvas, and therefore
needs that canvas to come to the top of the Z-order.

The current implementation of Z-ordering in a container is static
in the sense that Z-order of each child relative to the others is
decided once at the time the child is added to the container, and
never altered. This means the only way we can alter the Z-order
of existing components in a container is by removing some set of
components and adding them again to the same container at with
different indices. This is not ideal, because the removal process
causes handlers to be called, resources to be destroyed, and focus
to shift, which in turn requires a workarounds to get everything
back to the state where it was before the Z-order modification.

We propose that an API be added to the Container class to allow
Z-order to be changed dynamically. _Raising_ a child component in
the Z-order of its parent container using this API should not
generate focus events or cause any other unnecessary handlers
to be called, though lowering a child could potentially have
more ramifications, and perhaps it might make sense to add new
listeners and events to track movement in the Z direction.

This API could mirror "add(component, index)" on Container and
perhaps be called "setZOrder(component, index)".
(Review ID: 136396)
======================================================================