net.rim.device.api.ui.container
Class HorizontalFieldManager

java.lang.Object
  net.rim.device.api.ui.Field
      net.rim.device.api.ui.ScrollView
          net.rim.device.api.ui.Manager
              net.rim.device.api.ui.container.HorizontalFieldManager

All Implemented Interfaces:

AdjustmentListener

Direct Known Subclasses:

PhoneScreenHorizontalManager, SpinBoxFieldManager

public class HorizontalFieldManager
extends Manager

A manager that lays out fields along a single, horizontal row.

Behaviour
A horizontal field manager lays out fields from left to right on a single row. The layout direction can be changed to locale-aware leading to trailing by specifying the HorizontalFieldManager.LOCALE_AWARE_LAYOUT style bit in the constructor. The layout direction can also be controlled by setting the style of the HorizontalFieldManager to include Field.RIGHT_TO_LEFT or Field.LEFT_TO_RIGHT in the constructor. This will override any locale aware settings. You can build this manager with Manager.HORIZONTAL_SCROLL to accommodate collections of fields wider than the manager's visible frame; you can build this manager with Manager.VERTICAL_SCROLL to accommodate fields taller than the manager's visible frame.

Field Summary
static int	LOCALE_AWARE_LAYOUT Used to specify locale aware layout.

Fields inherited from class net.rim.device.api.ui.Manager

BOTTOMMOST, DOWNWARD, HORIZONTAL_SCROLL, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_MASK, HORIZONTAL_SCROLL_MASK, LEAVE_BLANK_SPACE, LEFTMOST, LEFTWARD, NO_HORIZONTAL_SCROLL, NO_HORIZONTAL_SCROLLBAR, NO_SCROLL_RESET, NO_VERTICAL_SCROLL, NO_VERTICAL_SCROLLBAR, QUANTA_FONT, RIGHTMOST, RIGHTWARD, TOPMOST, UPWARD, VERTICAL_SCROLL, VERTICAL_SCROLLBAR, VERTICAL_SCROLLBAR_MASK, VERTICAL_SCROLL_MASK

Fields inherited from class net.rim.device.api.ui.Field

ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL

Constructor Summary

HorizontalFieldManager()
Constructs a new horizontal field manager.

HorizontalFieldManager(long style)
Constructs a new horizontal field manager with provided style(s).

Method Summary
int	getFieldAtLocation(int x, int y) Retrieves field under a particular point.
int	getPreferredHeight() Retrieves the manager's preferred height (in pixels).
int	getPreferredWidth() Retrieves the manager's preferred width (in pixels).
protected int	nextFocus(int direction, int axis) Retrieves the index of the next field that should be given focus.
protected void	sublayout(int maxWidth, int maxHeight) Lays out this manager's controlled fields.
protected void	subpaint(Graphics graphics) Redraws this manager's controlled fields.

Methods inherited from class net.rim.device.api.ui.Manager

add, addAll, delete, deleteAll, deleteRange, getAccessibleContext, getField, getFieldCount, getFieldWithFocus, getFieldWithFocusIndex, getFocusRect, getHorizontalScroll, getLeafFieldWithFocus, getPreferredHeightOfChild, getPreferredWidthOfChild, getVerticalScroll, getVirtualHeight, getVirtualWidth, insert, insertAll, invalidate, invalidate, invalidateFieldRange, invokeAction, isDataValid, isDirty, isDownArrowShown, isFocusable, isMuddy, isSelecting, isUpArrowShown, isValidLayout, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, layout, layoutChild, makeMenu, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, nextFocus, onFocus, onUnfocus, paint, paintChild, replace, setDirty, setFocus, setHorizontalQuantization, setPositionChild, setScrollingInertial, setVerticalQuantization, setVirtualExtent, touchEvent, trackwheelClick, trackwheelUnclick

Methods inherited from class net.rim.device.api.ui.ScrollView

configurationChanged, getHorizontalAdjustment, getVerticalAdjustment, getVisibleHeight, getVisibleWidth, onDisplay, onUndisplay, setCurrentLocation, setExtent, setHorizontalAdjustment, setHorizontalScroll, setHorizontalScroll, setScrollListener, setVerticalAdjustment, setVerticalScroll, setVerticalScroll, valueChanged, waitForScrolling

Methods inherited from class net.rim.device.api.ui.Field

drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getScreen, getStyle, getTop, getVisualState, getWidth, invalidateAll, isEditable, isEnabled, isFocus, isPasteable, isScrollCopyable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setEditable, setEnabled, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, updateLayout

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOCALE_AWARE_LAYOUT

public static final int LOCALE_AWARE_LAYOUT

Used to specify locale aware layout.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

Constructor Detail

HorizontalFieldManager

public HorizontalFieldManager()

Constructs a new horizontal field manager.

This method builds a new horizontal field manager with no style.

HorizontalFieldManager

public HorizontalFieldManager(long style)

Constructs a new horizontal field manager with provided style(s).

Parameters:

style - Styles recognized by this manager include Manager.HORIZONTAL_SCROLL, Manager.VERTICAL_SCROLL Field.LEFT_TO_RIGHT and Field.RIGHT_TO_LEFT.

Method Detail

getPreferredWidth

public int getPreferredWidth()

Retrieves the manager's preferred width (in pixels).

This method returns the width (in pixels) required to lay out the manager’s contents. It includes the preferred widths for the controlled fields, as well as spacing between these fields. Spacing between neighboring fields is defined by the largest of each field’s margins.

Overrides:

getPreferredWidth in class Field

Returns:

Horizontal space preferred by this manager.

getPreferredHeight

public int getPreferredHeight()

Retrieves the manager's preferred height (in pixels).

This method returns the height (in pixels) required to lay out the manager’s contents. The contents height is defined by the highest of controlled fields and its margins.

Overrides:

getPreferredHeight in class Field

Returns:

Vertical space preferred by this manager.

nextFocus

protected int nextFocus(int direction,
                        int axis)

Retrieves the index of the next field that should be given focus.

This method is called by the framework during a track-ball focus move operation.

The direction parameter indicates the direction in which the focus is moving: a value of 1 indicates that the focus is moving forward (generally down and to the right), while a value of -1 indicates that the focus is moving backwards (generally up and to the left).

The axis parameter indicates which axis of movement the direction is in. This can be one of Field.AXIS_SEQUENTIAL, Field.AXIS_HORIZONTAL or Field.AXIS_VERTICAL.

HorizontalFieldManager will move focus out of the manager in the event of AXIS_VERTICAL movement.

Overrides:

nextFocus in class Manager

Parameters:

direction - Direction the focus is moving within the field.

axis - The axis of movement.

Returns:

Index of the next field that should receive focus, -1 if the focus should leave the manager.

Throws:

IllegalArgumentException - If direction parameter is a value other than 1 or -1.

Since:

BlackBerry API 6.0.0

sublayout

protected void sublayout(int maxWidth,
                         int maxHeight)

Lays out this manager's controlled fields.

The framework invokes this method to direct this manager to lay out its controlled fields.

Specified by:

sublayout in class Manager

Parameters:

maxWidth - Horizontal space available for this manager.

maxHeight - Vertical space available for this manager.

subpaint

protected void subpaint(Graphics graphics)

Redraws this manager's controlled fields.

The framework invokes this method to direct this manager to repaint its controlled fields. This method examines the clipping rectangle contained in the graphics context parameter to determine which controlled fields are in the invalid region (require repainting), in order to prevent unnecessary redraws.

Overrides:

subpaint in class Manager

Parameters:

graphics - Graphics context used for the redraw operation.

getFieldAtLocation

public int getFieldAtLocation(int x,
                              int y)

Retrieves field under a particular point.

Given a point in coordinates local to this manager's extent, this method returns the index of the controlled field under that point.

If no field exists under the point you specify, this method returns -1.

If you provide a coordinate outside this manager's extent, this method uses values along the edges of the extent as required.

HorizontalFieldManager performs a binary search for the x coordinate passed in. No checks are made for the vertical value.

Overrides:

getFieldAtLocation in class Manager

Parameters:

x - Distance from left edge of this manager's extent.

y - Distance from top edge of this manager's extent.

Returns:

Index of the field under your point, or -1 if no field under your point.