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

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.GridFieldManager
All Implemented Interfaces:
AdjustmentListener

public class GridFieldManager
extends Manager

A grid-based manager.

A GridFieldManager is created with a fixed number of rows and columns. Fields may be added to the grid either in the next empty cell with the add() method or inserted at a specific row and column location using the insert() method.

Row and column heights and widths may be specified as fixed sizes or may be automatically sized with the available space divided evenly among the rows and columns.

The grid will scroll vertically if the heights of the rows exceeds the visible height of the grid, and will scroll horizontally if the widths of the columns exceedst he visible width of the grid.

The cells in the grid are indexed from zero to (number of cells - 1).

Since:
BlackBerry API 5.0.0

Field Summary
static int AUTO_SIZE
          Indicates that rows or columns should be automatically sized, with the available space divided evently among the rows or columns.
static int FIXED_SIZE
          Indicates that rows and columns should have fixed sizes which can be specified with either setColumnProperty or setRowProperty.
static int PREFERRED_SIZE
          Indicates that rows and columns should be sized according to the preferred size of the contained fields.
static int PREFERRED_SIZE_WITH_MAXIMUM
          Indicates that rows and columns should be sized according to the preferred size of the contained fields, with a specified maximum.
 
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
GridFieldManager(int rows, int columns, long style)
          Constructs a GridFieldManager.
 
Method Summary
 void add(Field field)
          Adds the given field to the first unoccupied cell in the grid.
 void add(Field field, long style)
          Adds a field to the first unoccupied cell in the grid.
 void delete(int row, int column)
          Removes a field from this manager.
 void delete(Field field)
          Removes a field from this manager.
 void deleteAll()
          Removes all fields from this manager.
 void deleteRange(int start, int count)
          Removes a range of fields from this manager.
 void deleteRange(int startRow, int startColumn, int count)
          Removes a range of fields.
protected  int firstFocus(int direction)
          Retrieves the child field that should be given focus when this Manager receives focus.
 int getColumnCount()
          Returns the number of columns in the grid.
 int getColumnPadding()
          Returns the padding between columns.
 int getColumnWidth(int column)
          Returns the width of the specified column.
 Field getFieldAtCell(int row, int column)
          Returns the Field contained in the cell specified by the given row and column.
 Field getFieldAtIndex(int index)
          Returns the field at the given index.
 int getFieldCount()
          Retrieves the number of fields controlled by this manager.
 int getRowCount()
          Returns the number of rows in the grid.
 int getRowHeight(int row)
          Returns the height of the specified row.
 int getRowPadding()
          Returns the padding between rows.
 void insert(Field field, int index)
          Inserts a field at a given index.
 void insert(Field field, int row, int column)
          Inserts a field at the cell specified by a row and column.
 void insert(Field field, int row, int column, long style)
          Inserts a field at the cell specified by a row and column.
 void insert(Field field, int index, long style)
          Inserts a field at a given index.
 int nextFocus(int direction, int axis)
          Retrieves the index of the next field that should be given focus.
 void set(Field field, int row, int column)
          Sets the field at the specified row and column.
 void set(Field field, int row, int column, long style)
          Sets the field at the specified row and column.
 void setCellPadding(int padding)
          Sets the inner cell padding.
 void setColumnPadding(int padding)
          Sets the padding between columns, in pixels.
 void setColumnProperty(int column, int property, int value)
          Sets a column property.
 void setRowPadding(int padding)
          Sets the padding between rows, in pixels.
 void setRowProperty(int row, int property, int value)
          Sets a row property.
protected  void sublayout(int width, int height)
          Implements custom layout features for this manager.
protected  void subpaint(Graphics graphics)
          Paints the children of this manager.
 
Methods inherited from class net.rim.device.api.ui.Manager
addAll, cursorClick, cursorMovement, cursorUnclick, getAccessibleContext, getField, getFieldAtLocation, getFieldWithFocus, getFieldWithFocusIndex, getFocusRect, getHorizontalScroll, getLeafFieldWithFocus, getPreferredHeightOfChild, getPreferredWidthOfChild, getVerticalScroll, getVirtualHeight, getVirtualWidth, 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, 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, getPreferredHeight, getPreferredWidth, 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
 



Field Detail

PREFERRED_SIZE

public static final int PREFERRED_SIZE
Indicates that rows and columns should be sized according to the preferred size of the contained fields.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

PREFERRED_SIZE_WITH_MAXIMUM

public static final int PREFERRED_SIZE_WITH_MAXIMUM
Indicates that rows and columns should be sized according to the preferred size of the contained fields, with a specified maximum.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

AUTO_SIZE

public static final int AUTO_SIZE
Indicates that rows or columns should be automatically sized, with the available space divided evently among the rows or columns.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

FIXED_SIZE

public static final int FIXED_SIZE
Indicates that rows and columns should have fixed sizes which can be specified with either setColumnProperty or setRowProperty.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0


Constructor Detail

GridFieldManager

public GridFieldManager(int rows,
                        int columns,
                        long style)
Constructs a GridFieldManager.

Parameters:
rows - the number of rows in the grid
columns - the number of columns in the grid
style - the style bits to be used by the manager
Since:
BlackBerry API 5.0.0


Method Detail

add

public void add(Field field)
Adds the given field to the first unoccupied cell in the grid.

Overrides:
add in class Manager
Parameters:
field - the field to add to the grid
Throws:
IllegalStateException - if the grid is already full
Since:
BlackBerry API 5.0.0

add

public void add(Field field,
                long style)
Adds a field to the first unoccupied cell in the grid.

Parameters:
field - the field to add to the grid
style - allows specification of field alignment
Throws:
IllegalStateException - if the grid is already full
Since:
BlackBerry API 5.0.0

set

public void set(Field field,
                int row,
                int column)
Sets the field at the specified row and column. If the cell is already occupied, the existing field is replaced.

Parameters:
field - the field to add
row - the row at which to add the field
column - the column at which to add the field
Throws:
IllegalStateException - if the grid is already full
IllegalStateException - if the grid is already full
Since:
BlackBerry API 5.0.0

set

public void set(Field field,
                int row,
                int column,
                long style)
Sets the field at the specified row and column. If the cell is already occupied, the existing field is replaced.

Parameters:
field - the field to add
row - the row at which to add the field
column - the column at which to add the field
style - for specifying the alignment of the field within the cell
Throws:
IllegalStateException - if the grid is already full
Since:
BlackBerry API 5.0.0

delete

public void delete(Field field)
Removes a field from this manager. The cell becomes unoccupied.

Overrides:
delete in class Manager
Parameters:
field - the field to remove
Since:
BlackBerry API 5.0.0

delete

public void delete(int row,
                   int column)
Removes a field from this manager.

Parameters:
row - the row from which to remove the field
column - the column from which to remove the field
Throws:
IllegalArgumentException - if 'row' or 'column' is invalid
Since:
BlackBerry API 5.0.0

deleteAll

public void deleteAll()
Description copied from class: Manager
Removes all fields from this manager.

Invoking this method has the same effect as

     manager.deleteRange( 0, manager.getFieldCount() )
 

Overrides:
deleteAll in class Manager
See Also:
Manager.deleteAll()
Since:
BlackBerry API 5.0.0

deleteRange

public void deleteRange(int start,
                        int count)
Removes a range of fields from this manager.

Overrides:
deleteRange in class Manager
Parameters:
start - the index of the first field to remove
count - the number of fields to remove. Empty cells encountered will contribute to the count of deleted fields.
Throws:
IndexOutOfBoundsException - if start or count are invalid
Since:
BlackBerry API 5.0.0

deleteRange

public void deleteRange(int startRow,
                        int startColumn,
                        int count)
Removes a range of fields.

Parameters:
startRow - the row at which to start deleting
startColumn - the column at which to start deleting
count - the number of fields to delete. Empty cells encountered will contribute to the count of deleted fields.
Throws:
IllegalArgumentException - if startRow or startColumn are invalid
Since:
BlackBerry API 5.0.0

firstFocus

protected int firstFocus(int direction)
Retrieves the child field that should be given focus when this Manager receives focus.

Overrides:
firstFocus in class Manager
Parameters:
direction - -1 if focus is coming in to the bottom of the manager, 1 if focus is coming in to the top of the manager, and 0 if focus is being explicitly set to this manager.
Returns:
Index of the field that should receive focus.
Since:
BlackBerry API 6.0.0

getColumnCount

public int getColumnCount()
Returns the number of columns in the grid.

Returns:
the number of columns
Since:
BlackBerry API 5.0.0

getFieldCount

public int getFieldCount()
Retrieves the number of fields controlled by this manager.

Overrides:
getFieldCount in class Manager
Returns:
The number of fields controlled by this manager.
Since:
BlackBerry API 5.0.0

getRowCount

public int getRowCount()
Returns the number of rows in the grid.

Returns:
the number of rows
Since:
BlackBerry API 5.0.0

getColumnPadding

public int getColumnPadding()
Returns the padding between columns.

Returns:
the column padding, in pixels
Since:
BlackBerry API 5.0.0

getFieldAtIndex

public Field getFieldAtIndex(int index)
Returns the field at the given index.

Parameters:
index - the cell index of the field
Returns:
the Field at the given index if the cell contains a field; null if the cell is unoccupied
Since:
BlackBerry API 5.0.0

getFieldAtCell

public Field getFieldAtCell(int row,
                            int column)
Returns the Field contained in the cell specified by the given row and column.

Parameters:
row - the row of the cell
column - the column of the cell
Returns:
the Field contained by the cell specified by 'row' and 'column', null if the cell is unoccupied
Since:
BlackBerry API 5.0.0

getRowPadding

public int getRowPadding()
Returns the padding between rows.

Returns:
the padding between rows, in pixels
Since:
BlackBerry API 5.0.0

insert

public void insert(Field field,
                   int index)
Inserts a field at a given index.

Overrides:
insert in class Manager
Parameters:
field - the field to insert
index - the index at which to insert the field. The field with occupy the cell at the given index and will push any fields at a greater or equal index to the next cell.
Throws:
IllegalStateException - if grid is already full. Empty cells at an equal or greater value than 'index' will be filled first.
Since:
BlackBerry API 5.0.0

insert

public void insert(Field field,
                   int index,
                   long style)
Inserts a field at a given index.

Parameters:
field - the field to insert
index - the index at which to insert the field. The field with occupy the cell at the given index and will push any fields at a greater or equal index to the next cell.
style - for specification of alignment within the cell
Throws:
IllegalStateException - if grid is already full. Empty cells at an equal or greater value than 'index' will be filled first.
Since:
BlackBerry API 5.0.0

insert

public void insert(Field field,
                   int row,
                   int column)
Inserts a field at the cell specified by a row and column.

Parameters:
field - the field to insert
row - the row at which to insert the field
column - the column at which to insert the field
Throws:
IllegalArgumentException - if row or column is invalid
IllegalStateException - if the grid is already full. Empty cells at an equal or greater than the index indicated by the row and column will be filled first.
Since:
BlackBerry API 5.0.0

insert

public void insert(Field field,
                   int row,
                   int column,
                   long style)
Inserts a field at the cell specified by a row and column.

Parameters:
field - the field to insert
row - the row at which to insert the field
column - the column at which to insert the field
style - allows specification of the field alignment within the cell
Throws:
IllegalArgumentException - if row or column is invalid
IllegalStateException - if the grid is already full. Empty cells at an equal or greater than the index indicated by the row and column will be filled first.
Since:
BlackBerry API 5.0.0

getColumnWidth

public int getColumnWidth(int column)
Returns the width of the specified column.

Parameters:
column - the column for which to return the width
Returns:
the width of the given column
Since:
BlackBerry API 5.0.0

getRowHeight

public int getRowHeight(int row)
Returns the height of the specified row.

Parameters:
row - the row for which to return the height
Returns:
the height of the specified row
Since:
BlackBerry API 5.0.0

nextFocus

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

Overrides:
nextFocus in class Manager
Parameters:
direction - The direction the focus is moving within the field; a value of 1 indicates that the focus is moving forward (generally down and to the right), a value of -1 indicates that the focus is moving backwards (generally up and to the left).
axis - The axis of movement; can be one of Field.AXIS_SEQUENTIAL, Field.AXIS_HORIZONTAL, or Field.AXIS_VERTICAL.
Returns:
The index of the next field that should receive focus, or -1 if the focus should leave the manager.
Since:
BlackBerry API 5.0.0

setColumnPadding

public void setColumnPadding(int padding)
Sets the padding between columns, in pixels.

Parameters:
padding - the padding between columns, in pixels.
Since:
BlackBerry API 5.0.0

setColumnProperty

public void setColumnProperty(int column,
                              int property,
                              int value)
Sets a column property.

Parameters:
column - the index of the column whose property to set
property - one of GridFieldManager.PREFERRED_SIZE GridFieldManager.PREFERRED_SIZE_WITH_MAXIMUM GridFieldManager.AUTO_SIZE GridFieldManager.FIXED_SIZE
value - the maximum value for PREFERRED_SIZE_WITH_MAXIMUM or the number of pixels for GridFieldManager.FIXED_SIZE. This parameter is ignored for other properties.
Since:
BlackBerry API 5.0.0

setRowProperty

public void setRowProperty(int row,
                           int property,
                           int value)
Sets a row property.

Parameters:
row - the index of the row whose property to set
property - one of GridFieldManager.PREFERRED_SIZE GridFieldManager.PREFERRED_SIZE_WITH_MAXIMUM GridFieldManager.AUTO_SIZE GridFieldManager.FIXED_SIZE
value - the maximum value for PREFERRED_SIZE_WITH_MAXIMUM or the number of pixels for GridFieldManager.FIXED_SIZE. This parameter is ignored for other properties
Since:
BlackBerry API 5.0.0

setRowPadding

public void setRowPadding(int padding)
Sets the padding between rows, in pixels.

Parameters:
padding -
Since:
BlackBerry API 5.0.0

setCellPadding

public void setCellPadding(int padding)
Sets the inner cell padding.

Parameters:
padding - the padding, in pixels, surrounding the contained field
Since:
BlackBerry API 5.0.0

sublayout

protected void sublayout(int width,
                         int height)
Implements custom layout features for this manager.

If implementing a manager with custom layout features, extend the Manager class and implement this method. Invoking the sublayout method prompts your manager subclass to lay out controlled fields appropriately. Manager.layout(int, int) invokes this method to perform custom layout handling. A manager must call Manager.setPositionChild(net.rim.device.api.ui.Field, int, int) for each child during sublayout. Note that ScrollView.setExtent(int, int) must also be called, but it is the field's responsibility to do this in layout.

Specified by:
sublayout in class Manager
Parameters:
width - The width available for this manager.
height - The height available for this manager.
Since:
BlackBerry API 6.0.0

subpaint

protected void subpaint(Graphics graphics)
Paints the children of this manager.

The default implementation may call Manager.paintChild(net.rim.device.api.ui.Graphics, net.rim.device.api.ui.Field) on all child fields, with or without regard to the clipping region. paintChild, however, may not result in a call to child.paint if the field would be entirely clipped.

A custom implementation of this method can optimize painting by using details of the layout to determine which fields are in the current visible region. To paint a controlled field, invoke Manager.paintChild(net.rim.device.api.ui.Graphics, net.rim.device.api.ui.Field).

Overrides:
subpaint in class Manager
Parameters:
graphics - The graphics object used for painting.
Since:
BlackBerry API 6.0.0





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