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

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

public class FlowFieldManager
extends Manager

Manager that lays out fields in a horizontal-then-vertical flow.

Behaviour
When laying out, this manager first tries to lay out a field along the current horizontal row. If there's not enough horizontal space, it places the field on the next row of fields. If you build this manager with the style Manager.VERTICAL_SCROLL, then it will have an infinite number of rows into which it can layout fields.

Field Summary

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

FlowFieldManager()
Constructs a flow field manager.

FlowFieldManager(long style)
Constructs a flow field manager of provided style.

Method Summary
int	getFieldAtLocation(int x, int y) Retrieves field under a particular point.
int	getPreferredHeight() Retrieves this manager's preferred height.
int	getPreferredWidth() Retrieves this manager's preferred width.
protected boolean	keyControl(char c, int status, int time) Sends key-generation event to the controlled field with focus.
protected boolean	navigationMovement(int dx, int dy, int status, int time) Invoked when a navigational motion occurs.
int	nextFocus(int direction, boolean alt) Returns the index of the next controlled field that should be given the focus.
protected void	sublayout(int width, int height) 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, getVisibleHeight, getVisibleWidth, insert, invalidate, invalidate, invalidateFieldRange, invokeAction, isDataValid, isDirty, isDownArrowShown, isFocusable, isMuddy, isSelecting, isUpArrowShown, isValidLayout, keyChar, keyDown, keyRepeat, keyStatus, keyUp, layout, layoutChild, makeMenu, moveFocus, moveFocus, navigationClick, navigationUnclick, nextFocus, onFocus, onUndisplay, onUnfocus, paint, paintChild, replace, setDirty, setFocus, setHorizontalQuantization, setHorizontalScroll, setHorizontalScroll, setPositionChild, setScrollListener, setScrollingInertial, setVerticalQuantization, setVerticalScroll, setVirtualExtent, touchEvent, trackwheelClick, trackwheelUnclick

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

drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getOriginal, getScreen, getStyle, getTop, getVisualState, getWidth, invalidateAll, isEditable, isFocus, isPasteable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCookie, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setNonSpellCheckable, setPosition, setVisualState, updateLayout

Methods inherited from class java.lang.Object

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

Constructor Detail

FlowFieldManager

public FlowFieldManager()

Constructs a flow field manager.

This method builds a default flow field manager, with the styles Field.USE_ALL_WIDTH and Manager.VERTICAL_SCROLL.

FlowFieldManager

public FlowFieldManager(long style)

Constructs a flow field manager of provided style.

Use this method to build a flow field manager with your provided style(s). Note that, unlike the default constructor, this method uses only the style(s) you specify. Specifying a style of zero will ensure that not all the available width will be used for layout.

Parameters:

style - Style(s) for this manager (can be Field.USE_ALL_WIDTH, Manager.VERTICAL_SCROLL, and/or Manager.HORIZONTAL_SCROLL.

Method Detail

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.

By default, this method performs a linear search, testing each controlled field in turn. If you extend this manager, you can override this method to optimize its functionality.

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.

getPreferredHeight

public int getPreferredHeight()

Retrieves this manager's preferred height.

This method queries each controlled field for its preferred height, returning the sum of all these heights.

This method is likely to return a value that's much larger than actually required, since it's accurate only for the degenerate case where each controlled field is laid out on its own row.

Overrides:

getPreferredHeight in class Field

Returns:

Preferred height for this manager.

getPreferredWidth

public int getPreferredWidth()

Retrieves this manager's preferred width.

This method queries each controlled field for its preferred width, returning the greatest of these widths.

This method is likely to return a value that's smaller than actually required, since it's accurate only for the degenerate case where each controlled field is laid out on its own row.

Overrides:

getPreferredWidth in class Field

Returns:

Preferred width for this manager.

keyControl

protected boolean keyControl(char c,
                             int status,
                             int time)

Sends key-generation event to the controlled field with focus.

This method maps Characters.CONTROL_UP, Characters.CONTROL_DOWN, Characters.CONTROL_LEFT and Characters.CONTROL_RIGHT keys to horizontal trackwheel rolls, and otherwise passes on key-generation events to the parent class.

Overrides:

keyControl in class Manager

Parameters:

c - Character generated.

status - Modifier key status.

time - Number of milliseconds since the device was turned on.

Returns:

True if event was consumed; otherwise, false.

navigationMovement

protected boolean navigationMovement(int dx,
                                     int dy,
                                     int status,
                                     int time)

Description copied from class: Manager

Invoked when a navigational motion occurs.

The source of the navigation event can be determined by checking the KeypadListener.STATUS_TRACKWHEEL and KeypadListener.STATUS_FOUR_WAY bits in the status parameter; exactly one of them will be set.

Overrides:

navigationMovement in class Manager

Parameters:

dx - Magnitude of navigational motion: negative for a move left and postive for a move right.

dy - Magnitude of navigational motion: negative for an upwards move, and positive for a downwards move.

status - Bitfield of values defined by KeypadListener.

time - Number of milliseconds since the device was turned on.

Returns:

True if event was consumed; otherwise, false.

Since:

BlackBerry API 4.2.0

nextFocus

public int nextFocus(int direction,
                     boolean alt)

Returns the index of the next controlled field that should be given the focus.

The framework invokes this method during a trackwheel focus move operation.

The direction parameter indicates the direction in which the focus is moving:

• 1 indicates that the focus is moving forward (first to the right, and then down if necessary)
• -1 indicates that the focus is moving backwards (first to the left, and then up if necessary)

However, if the alt paramater is true (the trackwheel is being ALT-rolled), then the focus is moved vertically, not horizontally.

Overrides:

nextFocus in class Manager

Parameters:

direction - Direction in which the focus is moving within this manager.

alt - True if the trackwheel is being ALT-rolled.

Returns:

Index position of the next field that should have the focus; -1 if the focus should leave the manager entirely.

sublayout

protected void sublayout(int width,
                         int height)

Lays out this manager's controlled fields.

The framework invokes this method to direct this manager to lay out its controlled fields. If the FlowFieldManager was created with a style of zero, it will be checked for here to ensure that not all the available width is used for layout

Specified by:

sublayout in class Manager

Parameters:

width - Horizontal space available for this manager.

height - 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.