Provides the user interface components necessary to build a Kindle Application.
Relationship to AWT and Swing
These components are built on top of AWT. In most cases, they are extremely similar to
their AWT or Swing counterpart and existing code can be ported.
Like Swing, Kindle components are lightweight and inherit from a common base class which is
both a Container and a Component. It is recommended that developers
creating custom components derive from {@link com.amazon.kindle.kindlet.ui.KComponent}.
A large amount of the standard documentation about AWT and Swing applies in some way to
Kindle development. For instance, most of the same layout managers are used in both.
Additionally, the user interface components have the same threading requirements and must
only be manipulated from the dispatch thread.
Unlike desktop development
there are two specific areas that demand special attention on the Kindle platform: focus
management and repaints. For convenience, the common cases for each have already been handled.
Focus
On desktop applications the user has a mouse to point at components with. Some advanced users
move through an application via the keyboard using Tab and Shift-Tab.
Java provides
a standard concept, the {@link java.awt.FocusTraversalPolicy}, to determine how focus is moved
inside an application. But by default, this is simply one-dimensional movement (forward and back). Focus
moves between components in the order they were added to the container.
On the Kindle
the user moves the focus with a two dimensional navigation method - the five way. Two dimensional
focus movement is a considerably harder problem than one dimensional focus movement. By default,
each application's root container is preconfigured with a two-dimensional focus policy based
on the actual location of each component on the screen. For more details see
{@link com.amazon.kindle.kindlet.ui.LayoutFocus2DTraversalPolicy}. This heuristic works well for many
layouts, but sometimes developers need more control over traversal. To assist, a
{@link com.amazon.kindle.kindlet.ui.LogicalFocus2DTraversalPolicy} is also provided. This allows the
developer to supply a grid of valid focus transitions - similar to 2d focus order.
In extreme circumstance, applications may need to take control of focus movement explicitly. This
can be done manually using {@link java.awt.Component#requestFocus()} or new two-dimensional policies can be
created by extending {@link com.amazon.kindle.kindlet.ui.Focus2DTraversalPolicy}. All
{@link com.amazon.kindle.kindlet.ui.KComponent}s implement {@link com.amazon.kindle.kindlet.ui.Focus2DTraversable}.
Repaints
Despite eInk's many advantages, it is much slower to refresh than traditional display technologies.
The speed at which the screen updates is related to how much of the screen is being refreshed and what
colors are involved. The
Kindle components take care of most of the details of repainting for the developer.
Minimizing Repaints
AWT also coalesces repaint events for the developer. If a repaint is issue that is entirely contained by
or entirely contains an outstanding repaint request, the two will be collapsed for efficiency.
Developers of custom components should attempt to update the smallest region of the screen possible. When
a {@link java.awt.Component#repaint(int, int, int, int)} is requested the component will receive a paint request
that indicates the clip bound that is necessary to repaint.
Grays
Areas of the screen containing only black and white are the fastest for the screen to redraw. The next
fastest refresh are areas that contain only four specific shades: black, white, light gray and dark gray. For
APIs to obtain the specific colors please see {@link com.amazon.kindle.kindlet.ui.KindletUIResources}.
The provided components are designed with these restrictions in mind.
For applications where update performance is important, it is recommended that developers avoid using
all of the available grays on the device.
More Control
For various reasons, the developer may desire more complete control over the display than
{@link java.awt.Component#repaint()} provides. In particular, the Kindle's display also may leave a faint ghost of the
previous screen image. While normally barely perceptible, over many updates an area can appear to
have a "dirty" background. To address this issue, a special type of repaint is used that briefly inverts the
display, or flashes it. To issue a full refresh, or flashing repaint, see
{@link com.amazon.kindle.kindlet.ui.KRepaintManager#paintImmediately(Component, boolean)}.
Additionally developers may wish to track dirty regions manually and paint them.
{@link com.amazon.kindle.kindlet.ui.KRepaintManager} provides support for this.
Developers should start by using the standard repaint mechanisms in AWT and only move to the repaint manager
if necessary.
User Interface Standards
When referencing colors and fonts, the standard {@link java.awt.Color} and {@link java.awt.Font} are used. To
ensure that the colors and fonts specified are available on the device, application's should use
{@link com.amazon.kindle.kindlet.ui.KindletUIResources} to obtain the specific Color and Font
instances. This is particularly important for fonts, where this is the only reliable way to obtain
aliased vs. anti-aliased font rendering.
@since 1.0