Provides the user interface components necessary to build a Kindle Application.

Java User Interface Components

The Kindle user interface components are built on top of AWT. These 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}.

Standard documentation about AWT and Swing can be consulted for general guidelines when working with Java user interface design and implementation. For instance, most of the layout managers can be used in either Swing or AWT. Additionally, the user interface components have the same threading requirements and must only be manipulated from the dispatch thread. Keep in mind that the UI components provided by the KDK are different from those available in Java AWT and Swing and the differences must be taken into account when creating applications for the Kindle platform.

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 coalesces repaint events for the developer. If a repaint is issued 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