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

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.ScrollView
          extended by net.rim.device.api.ui.Manager
              extended by net.rim.device.api.ui.container.FlowFieldManager
All Implemented Interfaces:
AdjustmentListener

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  int nextFocus(int direction, int axis)
          Retrieves the index of the next field that should be given 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, cursorClick, cursorMovement, cursorUnclick, 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, keyDown, keyRepeat, keyStatus, keyUp, layout, layoutChild, makeMenu, moveFocus, moveFocus, navigationClick, navigationUnclick, onFocus, onUnfocus, paint, paintChild, replace, setDirty, setFocus, setHorizontalQuantization, setPositionChild, setScrollingInertial, setVerticalQuantization, setVirtualExtent, shouldCursorScroll, touchEvent, trackwheelClick, trackwheelUnclick
 
Methods inherited from class net.rim.device.api.ui.ScrollView
configurationChanged, getHorizontalAdjustment, getVerticalAdjustment, getVisibleHeight, getVisibleWidth, onExposed, 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, getTextFillColor, getTextStrokeColor, getTop, getVisualState, getWidth, invalidateAll, isEditable, isEnabled, isFocus, isLeftToRight, isPasteable, isScrollCopyable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onDisplay, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setEditable, setEnabled, setFocus, setFocusListener, setFont, 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
 



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 - The magnitude of navigational motion: negative for a move left and postive for a move right.
dy - The magnitude of navigational motion: negative for an upwards move, and positive for a downwards move.
status - A bitfield of values defined by KeypadListener.
time - The number of milliseconds since the device was turned on.
Returns:
true if the event was consumed, false otherwise.
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:

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.

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

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





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal