Package com.amazon.kindle.kindlet.ui

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

See:
          Description

Interface Summary
Focus2DTraversable Components that want to participate in two-dimensional focus movement should implement this interface.
KMenuListener Interface for receiving events about the state of the menu.
KOptionPane.ConfirmDialogListener A listener that is notified when a confirmation dialog is closed.
KOptionPane.InputDialogListener A listener that is notified when an input dialog is closed.
KOptionPane.MessageDialogListener A listener that is notified when a message dialog is closed.
KProgress Interface for components to display progress to the user about running activities.
KTextOptionMenu Interface to option menus that can be displayed on the KTextOption panel.
OrientationController Allows a Kindle Application to control the device's orientation.
 

Class Summary
AbstractFocus2DTraversalPolicy Common implementation usable by most implementations of Focus2DTraversalPolicy.
Focus2DTraversalPolicy A FocusTraversalPolicy capable of supporting two-dimensional focus movement.
FocusTraversalEdgePolicy Typesafe enumeration of possible types of actions a FocusTraversalPolicy may take when it reaches the "beginning" or "end" of a traversal chain.
FocusTraversalOrthogonalMode Typesafe enumeration specifying focus traversal modes that describe how orthogonal alignments between components affect a focus traversal policy's behavior.
KBox A simple container that uses KBoxLayout to layout its children.
KBox.Filler A helper component which implements a simple component with fixed size requests.
KBoxLayout An layout manager which arranges items into a sequence of boxes along either the x or y axis.
KButton This class creates a labeled button, in the Kindle style.
KComponent The base class for all UI components included in the KDK.
KImage A component which displays an image.
KImage.Alignment A type-safe class representing different image alignments.
KindleOrientation Constants representing the possible orientations of the Kindle device.
KindletUIResources Object that provides style properties for the current runtime/device.
KindletUIResources.KColorName Typesafe enumeration of color names supported by the Kindle Development Kit.
KindletUIResources.KFontFamilyName Typesafe enumeration of font family names supported by the kindle KDK.
KindletUIResources.KFontStyle Typesafe enumeration of font styles supported by this interface's getFont() methods.
KLabel Displays a single line text.
KLabelMultiline Extension to KLabel permitting display of multiple lines of text.
KMenu A single level pull down menu deployed from the system title bar.
KMenuEvent Event sent to KMenuListener when a menu is opened (selected) or closed (deselected).
KMenuItem A menu item to be displayed in a menu.
KOptionPane This class provides helper functions to display common modal dialog boxes.
KPagedContainer A container for laying out components across a series of pages.
KPages A simplified KPagedContainer that stores content internally rather than relying on a supplied PageModel, allowing easy addition/removal of items in the internal page model.
KPanel A simple opaque area in which an application can attach other components using a supplied layout manager.
KPasswordField KPasswordField is a lightweight component that allows the editing of a single line of text where the view indicates something was typed, but does not show the original characters.
KRepaintManager KRepaintManager provides applications with more precise control over the repaint logic.
KTextArea A KTextArea object is a multi-line region that displays text.
KTextComponent Common base class for Components that render text in some manner.
KTextField KTextField permits the editing of a single line of text.
KTextOptionEvent Event interface for text option events.
KTextOptionFontMenu Standard font size option menu.
KTextOptionListMenu A text option menu implementation that contains a title and a list of selectable items.
KTextOptionMenuItem Option menu item that can be displayed on an KTextOptionListMenu.
KTextOptionMenuSelectable Base class for text option menus that implement ItemSelectable.
KTextOptionOrientationMenu Standard orientation option menu.
KTextOptionPane Option dialog invoked by the text button.
LayoutFocus2DTraversalPolicy A Focus2DTraversalPolicy which determines focus motion based on the pixel location of the components within the focus cycle root.
LogicalFocus2DTraversalPolicy An implementation of Focus2DTraversalPolicy that allows an application to specify a logical grid (ie two dimensional array) which is used like a two dimensional "tab stop index" for focus traversal operations.
 

Package com.amazon.kindle.kindlet.ui Description

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 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 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 LayoutFocus2DTraversalPolicy. This heuristic works well for many layouts, but sometimes developers need more control over traversal. To assist, a 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 Component.requestFocus() or new two-dimensional policies can be created by extending Focus2DTraversalPolicy. All KComponents implement 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 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 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 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 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 KRepaintManager.paintImmediately(Component, boolean).

Additionally developers may wish to track dirty regions manually and paint them. 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 Color and Font are used. To ensure that the colors and fonts specified are available on the device, application's should use 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


(C) 1996-2010 Amazon.com, Inc. and its affiliates.