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

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

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

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

addAll, getAccessibleContext, getField, getFieldAtLocation, getFieldWithFocus, getFieldWithFocusIndex, getFocusRect, getHorizontalScroll, getLeafFieldWithFocus, getPreferredHeightOfChild, getPreferredWidthOfChild, getVerticalScroll, getVirtualHeight, getVirtualWidth, getVisibleHeight, getVisibleWidth, 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, onUndisplay, onUnfocus, paint, paintChild, replace, setDirty, setFocus, setHorizontalQuantization, setHorizontalScroll, setHorizontalScroll, setPositionChild, setScrollListener, setScrollingInertial, setVerticalQuantization, setVerticalScroll, setVirtualExtent, sublayout, subpaint, 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, getPreferredHeight, getPreferredWidth, 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

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

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()

Description copied from class: Manager

Retrieves number of fields controlled by this manager.

Overrides:

getFieldCount in class Manager

Returns:

Number of fields controlled by this manager.

See Also:

Manager.getFieldCount()

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)

Description copied from class: Manager

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.

See Also:

Manager#nextFocus()

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