net.rim.device.api.ui
Class Manager

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

All Implemented Interfaces:

AdjustmentListener

Direct Known Subclasses:

BrowserField, GlassField, Screen, PaneManagerView, PaneView, TitleView, AbstractProgressIndicatorView, DataView, AbsoluteFieldManager, DialogFieldManager, FlowFieldManager, GridFieldManager, HorizontalFieldManager, VerticalFieldManager, HomeScreenLocationPicker, ToolbarManager, ToolbarSetManager

public abstract class Manager
extends ScrollView

Provides fundamental functionality for all field managers.

Manager objects are used to contain fields. The various manager subclasses handle specific kinds of field layout. The ScrollView class itself deals with scrolling.

Implementing your own layout manager
If you have particular needs, you can implement your own manager. Extend the Manager class, and implement sublayout, getPreferredWidth, and getPreferredHeight. For efficiency, you may optionally override subpaint.

The framework invokes sublayout, prompting your manager to lay out the controlled fields appropriately. For each field within this Manager, invoke layoutChild, which will call layout for the field, and setPositionChild, which will call setPosition for the field. This will let each controlled field determine the size it requires.

subpaint iterates through controlled fields, instructing each to paint itself. You can optimize subpaint by using details of the layout to determine which fields are in the current visible region and skipping non-visible ones. To paint a controlled field, invoke paintchild.

Styles
The Manager class does not accept Field.FOCUSABLE_MASK or Field.EDITABLE_MASK.

Field Summary
static int	BOTTOMMOST Indicates scrolling all the way to the bottom of the manager.
static int	DOWNWARD Indicates downward scroll direction.
static long	HORIZONTAL_SCROLL ScrollView style to turn on horizontal scrolling.
static long	HORIZONTAL_SCROLLBAR ScrollView style to turn on horizontal scrollbars.
protected static long	HORIZONTAL_SCROLLBAR_MASK Bitfield mask of the horizontal scrollbar style specifiers.
protected static long	HORIZONTAL_SCROLL_MASK Bitfield mask of the horizontal scroll style specifiers.
static long	LEAVE_BLANK_SPACE Manager style that leave blank space intact.
static int	LEFTMOST Indicates scrolling all the way to the left of the manager.
static int	LEFTWARD Indicates scroll direction is to the left.
static long	NO_HORIZONTAL_SCROLL ScrollView will not support horizontal scrolling.
static long	NO_HORIZONTAL_SCROLLBAR ScrollView will not show horizontal scrollbars.
static long	NO_SCROLL_RESET Deprecated.
static long	NO_VERTICAL_SCROLL ScrollView will not support vertical scrolling.
static long	NO_VERTICAL_SCROLLBAR ScrollView will not show vertical scrollbars.
static int	QUANTA_FONT Indicates that the size of a quanta should be adjusted to the size of the current font on layout.
static int	RIGHTMOST Indicates scrolling all the way to the right of the manager.
static int	RIGHTWARD Indicates scroll direction is to the right.
static int	TOPMOST Indicates scrolling all the way to the top of the manager.
static int	UPWARD Indicates upward scroll direction.
static long	VERTICAL_SCROLL ScrollView style to turn on vertical scrolling.
static long	VERTICAL_SCROLLBAR ScrollView style to turn on vertical scrollbars.
protected static long	VERTICAL_SCROLLBAR_MASK Bitfield mask of the vertical scrollbar style specifiers.
protected static long	VERTICAL_SCROLL_MASK Bitfield mask of the vertical scroll style specifiers.

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
protected	Manager(long style) Constructs a new Manager instance.

Method Summary
void	add(Field field) Adds a field to this manager.
void	addAll(Field[] fields) Adds an array of fields into this manager.
protected boolean	cursorClick(int x, int y, int status, int time) Indicates a cursor click event.
protected boolean	cursorMovement(int x, int y, int status, int time) Indicates a cursor movement event.
protected boolean	cursorUnclick(int x, int y, int status, int time) Indicates a cursor unclick event.
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.
AccessibleContext	getAccessibleContext() Returns accessible representation of the field for a screen reader.
Field	getField(int index) Retrieves the controlled field with a specified index.
int	getFieldAtLocation(int x, int y) Retrieves the index of the field under a specified point.
int	getFieldCount() Retrieves the number of fields controlled by this manager.
Field	getFieldWithFocus() Retrieves the controlled field that currently has the focus.
int	getFieldWithFocusIndex() Retrieves the index of the controlled field with the focus.
void	getFocusRect(XYRect rect) Retrieves the current extent of the focus.
int	getHorizontalScroll() Returns the current horizontal offset of the scrolling region.
Field	getLeafFieldWithFocus() Retrieves the leaf field with focus.
protected int	getPreferredHeightOfChild(Field field) Retrieves the preferred height of a managed field.
protected int	getPreferredWidthOfChild(Field field) Retrieves the preferred width of a managed field.
int	getVerticalScroll() Retrieves current vertical offset of scrolling region.
int	getVirtualHeight() Retrieves this ScrollView's virtual height.
int	getVirtualWidth() Retrieves this ScrollView's virtual width.
void	insert(Field field, int index) Inserts a field into this manager.
void	insertAll(Field[] fields, int index) Inserts an array of fields into this manager.
void	invalidate() Marks this entire manager as requiring repainting.
protected void	invalidate(int x, int y, int width, int height) Marks a region as requiring repainting.
protected void	invalidateFieldRange(int lower, int upper) Invalidates this manager's controlled fields from lower to upper, inclusive.
protected boolean	invokeAction(int action) Invokes an action on the field in this manager that currently has the focus.
boolean	isDataValid() Indicates whether the data on the screen is valid.
boolean	isDirty() Determines if any controlled field is dirty.
protected boolean	isDownArrowShown() Deprecated. Please use ScrollView.canScrollDownward() instead.
boolean	isFocusable() Determines if this manager accepts the focus.
boolean	isMuddy() Determines if any controlled field is muddy.
boolean	isSelecting() Determines if the field with the focus is in selection mode.
protected boolean	isUpArrowShown() Deprecated. Please use ScrollView.canScrollUpward() instead.
boolean	isValidLayout() Determines if this manager has a completed layout for its fields.
protected boolean	keyChar(char ch, int status, int time) Handles key generation events.
protected boolean	keyControl(char ch, int status, int time) Sends key generation event to the controlled field with focus.
protected boolean	keyDown(int keycode, int time) Sends key down event to the controlled field with focus.
protected boolean	keyRepeat(int keycode, int time) Sends key repeat event to the controlled field with focus.
protected boolean	keyStatus(int keycode, int time) Sends key status event to the controlled field with focus.
protected boolean	keyUp(int keycode, int time) Sends key up event to the controlled field with focus.
protected void	layout(int width, int height) Lays out this manager's controlled fields in a standardized manner.
protected void	layoutChild(Field field, int width, int height) Prompts managed field to lay itself out.
protected void	makeMenu(Menu menu, int instance) Called from Screen.makeMenuWithContext(net.rim.device.api.ui.component.Menu, int) to populate the menu.
protected int	moveFocus(int amount, int status, int time) Called by the framework to move focus within this manager.
protected void	moveFocus(int x, int y, int status, int time) Moves focus to an exact position within this manager.
protected boolean	navigationClick(int status, int time) Invoked when the navigational action is selected.
protected boolean	navigationMovement(int dx, int dy, int status, int time) Invoked when a navigational motion occurs.
protected boolean	navigationUnclick(int status, int time) Invoked when the navigational action is released.
protected int	nextFocus(int direction, boolean alt) Deprecated. Please use Manager.nextFocus(int, int) instead
protected int	nextFocus(int direction, int axis) Retrieves the index of the next field that should be given focus.
protected void	onFocus(int direction) Invoked by the framework when focus is gained.
protected void	onUnfocus() Invoked by the framework when focus is lost.
protected void	paint(Graphics graphics) Paints this manager's visible region.
protected void	paintChild(Graphics graphics, Field field) Paints a controlled field.
void	replace(Field oldField, Field newField) Removes a field from this Manager and replaces it with another field.
void	setDirty(boolean dirty) Cleans or dirties all controlled fields.
boolean	setFocus(int x, int y, int status) Sets focus to an exact position on the current screen.
void	setHorizontalQuantization(int horizontalQuanta) Sets this manager's horizontal quantization.
protected void	setPositionChild(Field field, int x, int y) Sets the position of a manager's field.
protected void	setScrollingInertial(boolean isScrollingInertial) Sets whether the scrolling on this manager is inertial, overriding the system's default.
void	setVerticalQuantization(int verticalQuanta) Sets this manager's vertical quantization.
protected void	setVirtualExtent(int virtualWidth, int virtualHeight) Sets the virtual extent for this manager.
boolean	shouldCursorScroll(int newX, int newY, int dx, int dy) Returns true if the new position of the cursor would trigger a scroll, false otherwise.
protected abstract void	sublayout(int width, int height) Implements custom layout features for this manager.
protected void	subpaint(Graphics graphics) Paints the children of this manager.
protected boolean	touchEvent(TouchEvent message) Handles touch input events (see TouchEvent).
protected boolean	trackwheelClick(int status, int time) Dispatches trackwheel event to the controlled field with focus.
protected boolean	trackwheelUnclick(int status, int time) Dispatches trackwheel released event to the controlled field with focus.

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

LEAVE_BLANK_SPACE

public static final long LEAVE_BLANK_SPACE

Manager style that leave blank space intact.

This style specifies that the layout update logic should not attempt to adjust the scroll offset to eliminate blank space.

See Also:

Constant Field Values

UPWARD

public static final int UPWARD

Indicates upward scroll direction.

See Also:

Constant Field Values

DOWNWARD

public static final int DOWNWARD

Indicates downward scroll direction.

See Also:

Constant Field Values

LEFTWARD

public static final int LEFTWARD

Indicates scroll direction is to the left.

See Also:

Constant Field Values

RIGHTWARD

public static final int RIGHTWARD

Indicates scroll direction is to the right.

See Also:

Constant Field Values

TOPMOST

public static final int TOPMOST

Indicates scrolling all the way to the top of the manager.

See Also:

Constant Field Values

BOTTOMMOST

public static final int BOTTOMMOST

Indicates scrolling all the way to the bottom of the manager.

See Also:

Constant Field Values

LEFTMOST

public static final int LEFTMOST

Indicates scrolling all the way to the left of the manager.

See Also:

Constant Field Values

RIGHTMOST

public static final int RIGHTMOST

Indicates scrolling all the way to the right of the manager.

See Also:

Constant Field Values

QUANTA_FONT

public static final int QUANTA_FONT

Indicates that the size of a quanta should be adjusted to the size of the current font on layout.

For vertical quantization, this is the font height. The value is reserved for future use with horizontal quantization.

See Also:

Manager.setHorizontalQuantization(int), Manager.setVerticalQuantization(int), Constant Field Values

HORIZONTAL_SCROLL

public static final long HORIZONTAL_SCROLL

ScrollView style to turn on horizontal scrolling.

If this scroll provider's virtual width is larger than its visible width the region scrolls horizontally as required.

See Also:

Constant Field Values

HORIZONTAL_SCROLLBAR

public static final long HORIZONTAL_SCROLLBAR

ScrollView style to turn on horizontal scrollbars.

If VERTICAL_SCROLL_BAR is enabled then HORIZONTAL_SCROLL_BAR is ignored.

See Also:

Constant Field Values

HORIZONTAL_SCROLLBAR_MASK

protected static final long HORIZONTAL_SCROLLBAR_MASK

Bitfield mask of the horizontal scrollbar style specifiers.

See Also:

Constant Field Values

HORIZONTAL_SCROLL_MASK

protected static final long HORIZONTAL_SCROLL_MASK

Bitfield mask of the horizontal scroll style specifiers.

See Also:

Constant Field Values

NO_HORIZONTAL_SCROLL

public static final long NO_HORIZONTAL_SCROLL

ScrollView will not support horizontal scrolling.

See Also:

Constant Field Values

NO_HORIZONTAL_SCROLLBAR

public static final long NO_HORIZONTAL_SCROLLBAR

ScrollView will not show horizontal scrollbars.

See Also:

Constant Field Values

NO_SCROLL_RESET

public static final long NO_SCROLL_RESET

Deprecated.

ScrollView style to turn off resetting of scroll value when we leave the ScrollView.

See Also:

Constant Field Values

Since:

BlackBerry API 3.7.0

NO_VERTICAL_SCROLL

public static final long NO_VERTICAL_SCROLL

ScrollView will not support vertical scrolling.

See Also:

Constant Field Values

NO_VERTICAL_SCROLLBAR

public static final long NO_VERTICAL_SCROLLBAR

ScrollView will not show vertical scrollbars.

See Also:

Constant Field Values

VERTICAL_SCROLL

public static final long VERTICAL_SCROLL

ScrollView style to turn on vertical scrolling.

If the ScrollView's virtual height is larger than its visible height, the region scrolls vertically as required.

See Also:

Constant Field Values

VERTICAL_SCROLLBAR

public static final long VERTICAL_SCROLLBAR

ScrollView style to turn on vertical scrollbars.

See Also:

Constant Field Values

VERTICAL_SCROLLBAR_MASK

protected static final long VERTICAL_SCROLLBAR_MASK

Bitfield mask of the vertical scrollbar style specifiers.

See Also:

Constant Field Values

VERTICAL_SCROLL_MASK

protected static final long VERTICAL_SCROLL_MASK

Bitfield mask of the vertical scroll style specifiers.

See Also:

Constant Field Values

Constructor Detail

Manager

protected Manager(long style)

Constructs a new Manager instance.

Subclasses invoke this constructor in order to set the appropriate style bits for a new manager.

Parameters:

style - The style bits for this manager. The styles Field.FOCUSABLE, Field.NON_FOCUSABLE, Field.EDITABLE, Field.READONLY are ignored; these properties are controlled by the Manager's contents.

Throws:

IllegalArgumentException - if the style parameter specifies an invalid or undefined style.

Method Detail

add

public void add(Field field)

Adds a field to this manager.

Invoke this method to add a new field at the end of this manager's list of controlled fields.

Notice that only one manager is allowed to control any single field, and a field can never manage itself.

Parameters:

field - The field to add.

Throws:

IllegalStateException - if the field has already been added to a manager.

IllegalArgumentException - if the field is being added to itself.

NullPointerException - if the field is null.

addAll

public void addAll(Field[] fields)

Adds an array of fields into this manager.

Invoke this method to add new fields into this manager's list of controlled fields, triggering a single layout. Fields are added in the order provided.

Parameters:

fields - The fields to add.

Throws:

IllegalStateException - if any fields have already been added to a manager.

IllegalArgumentException - if any field is being added to itself.

NullPointerException - if fields is null.

Since:

BlackBerry API 5.0.0

delete

public void delete(Field field)

Removes a field from this manager.

Invoke this method to remove a field from this manager.

Parameters:

field - The field to remove.

Throws:

IllegalArgumentException - if the field to be deleted does not belong to this manager.

deleteAll

public void deleteAll()

Removes all fields from this manager.

Invoking this method has the same effect as

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

deleteRange

public void deleteRange(int start,
                        int count)

Removes a range of fields from this manager.

Provide the index of the first field you want to delete, and the number of fields to delete.

Parameters:

start - The index at which to begin deletion.

count - The number of fields to delete.

Throws:

IndexOutOfBoundsException - if start or count are invalid.

getAccessibleContext

public AccessibleContext getAccessibleContext()

Returns accessible representation of the field for a screen reader.

Overrides:

getAccessibleContext in class Field

Returns:

An AccessibleContext instance that represents the field for a screen reader.

Since:

BlackBerry API 4.6.1

getField

public Field getField(int index)

Retrieves the controlled field with a specified index.

Parameters:

index - The index of the field to retrieve.

Returns:

The controlled field at the specified index.

Throws:

IndexOutOfBoundsException - if index is not valid.

getFieldAtLocation

public int getFieldAtLocation(int x,
                              int y)

Retrieves the index of the field under a specified point.

Given a point in coordinates local to this manager's extent, this method returns the index of the controlled field under that point (or -1 if no field found under the specified point).

This method constrains its search to the extent of this manager: 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 hit, testing each controlled field in turn. If you implement a manager, you can override this method to optimize its functionality.

Parameters:

x - The distance from the left edge of the manager's extent.

y - The distance from the top edge of the manager's extent.

Returns:

The index of the field, or -1 if no field was found.

getFieldCount

public int getFieldCount()

Retrieves the number of fields controlled by this manager.

Returns:

The number of fields controlled by this manager.

getFieldWithFocus

public Field getFieldWithFocus()

Retrieves the controlled field that currently has the focus.

Invoke this method to retrieve the field controlled by this manager that has the focus. Notice that the field returned may in fact be another manager.

Returns:

The controlled field with the focus, or null if no field has the focus.

See Also:

Manager.getLeafFieldWithFocus()

getFieldWithFocusIndex

public int getFieldWithFocusIndex()

Retrieves the index of the controlled field with the focus.

Returns:

The index of the controlled field with the focus, or -1 if no field has the focus.

getFocusRect

public void getFocusRect(XYRect rect)

Retrieves the current extent of the focus.

Invoke this method to retrieve the extent of the current focus region. Notice that the coordinates expressed are local to this manager, and take scrolling into account (that is, the coordinates are local to the manager's visible region, not the virtual region).

Overrides:

getFocusRect in class Field

Parameters:

rect - The XYRect object to contain the extent of the focus.

getHorizontalScroll

public final int getHorizontalScroll()

Returns the current horizontal offset of the scrolling region.

Invoke this method to retrieve the current offset (from the left edge of this Manager's virtual region) of the currently displayed part of the Manager.

Overrides:

getHorizontalScroll in class ScrollView

Returns:

The horizontal scroll value (in pixels).

getLeafFieldWithFocus

public Field getLeafFieldWithFocus()

Retrieves the leaf field with focus. A leaf field is a field that does not manage any other fields. Use this method to retrieve the leaf field that has focus.

Since managers can themselves control other managers, you can invoke this method to retrieve the leaf (bottom-most, non-manager) field that has the focus.

Overrides:

getLeafFieldWithFocus in class Field

Returns:

The leaf field with focus, or null if no controlled field (directly or indirectly) has the focus.

See Also:

Manager.getFieldWithFocus()

getPreferredHeightOfChild

protected final int getPreferredHeightOfChild(Field field)

Retrieves the preferred height of a managed field.

Note: The returned value does not include field's margins, but includes border and padding.

Parameters:

field - The field to examine.

Returns:

The preferred height of the provided field.

Throws:

NullPointerException - if field is null.

Since:

BlackBerry API 4.2.0

getPreferredWidthOfChild

protected final int getPreferredWidthOfChild(Field field)

Retrieves the preferred width of a managed field.

Note: The returned value does not include field's margins, but includes border and padding.

Parameters:

field - The field to examine.

Returns:

The preferred width of the provided field.

Throws:

NullPointerException - if field is null.

Since:

BlackBerry API 4.2.0

getVerticalScroll

public final int getVerticalScroll()

Description copied from class: ScrollView

Retrieves current vertical offset of scrolling region.

Invoke this method to retrieve the current offset (from the top edge of this ScrollView's virtual region) of the currently displayed part of the ScrollView.

Overrides:

getVerticalScroll in class ScrollView

Returns:

Vertical scroll offset, in pixels.

getVirtualHeight

public final int getVirtualHeight()

Description copied from class: ScrollView

Retrieves this ScrollView's virtual height.

The ScrollView's virtual height is the entire height of the field that can be displayed, either at once or by scrolling.

Overrides:

getVirtualHeight in class ScrollView

Returns:

Virtual height of this ScrollView, in pixels.

getVirtualWidth

public final int getVirtualWidth()

Description copied from class: ScrollView

Retrieves this ScrollView's virtual width.

The ScrollView's virtual width may be wider than the ScrollView's visible width, and can be displayed either all at once or by scrolling.

Overrides:

getVirtualWidth in class ScrollView

Returns:

Virtual width of this ScrollView, in pixels.

insert

public void insert(Field field,
                   int index)

Inserts a field into this manager.

Invoke this method to insert a new field into this manager's list of controlled fields. You provide the field to add, and the index position you wish the new field to occupy.

Parameters:

field - The field to insert.

index - The index at which to insert.

Throws:

IndexOutOfBoundsException - if index is less than zero or greater than Manager.getFieldCount().

IllegalStateException - if the field has already been added to a manager.

IllegalArgumentException - if the field is being added to itself.

insertAll

public void insertAll(Field[] fields,
                      int index)

Inserts an array of fields into this manager.

Invoke this method to insert new fields into this manager's list of controlled fields, triggering a single layout. Fields are inserted in the order provided.

Parameters:

fields - The fields to insert.

index - The index at which to begin inserting.

Throws:

IndexOutOfBoundsException - if index is less than zero or greater than Manager.getFieldCount().

IllegalStateException - if any fields have already been added to a manager.

IllegalArgumentException - if any field is being added to itself.

NullPointerException - if fields is null.

Since:

BlackBerry API 6.0.0

invalidate

public void invalidate()

Marks this entire manager as requiring repainting.

Invoke this method to signal that this manager's entire region requires repainting.

It is safe to call this function without synchronizing on the event lock.

Overrides:

invalidate in class Field

invalidate

protected void invalidate(int x,
                          int y,
                          int width,
                          int height)

Marks a region as requiring repainting.

Invoke this method to identify a region of this manager that requires repainting.

Overrides:

invalidate in class Field

Parameters:

x - The left edge of the invalid rectangle.

y - The top edge of the invalid rectangle.

width - The width of the invalid rectangle.

height - The height of the invalid rectangle.

invalidateFieldRange

protected void invalidateFieldRange(int lower,
                                    int upper)

Invalidates this manager's controlled fields from lower to upper, inclusive.

Parameters:

lower - The index of the first field to invalidate.

upper - The index beyond the last field to invalidate.

Since:

BlackBerry API 4.0.0

invokeAction

protected boolean invokeAction(int action)

Invokes an action on the field in this manager that currently has the focus.

If no field has the focus then this method does nothing and returns that the action was not consumed.

Overrides:

invokeAction in class Field

Parameters:

action - The action to be performed on the field in this manager that currently has the focus.

Returns:

true if the action was consumed by the field on which the action was performed, false if the action was not consumed or no field has the focus in this manager.

Since:

BlackBerry API 4.2.0

isDownArrowShown

protected boolean isDownArrowShown()

Deprecated. Please use ScrollView.canScrollDownward() instead.

Determines whether the downward scroll arrow is to be drawn.

A custom ScrollView can override this method to provide precise control over the downward scroll arrow. The framework can invoke this method at any time after performing a layout.

By default, this method returns true if the view can scroll downward.

Returns:

true if the arrow should be drawn, false otherwise.

isUpArrowShown

protected boolean isUpArrowShown()

Deprecated. Please use ScrollView.canScrollUpward() instead.

Determines whether the upward scroll arrow is to be drawn.

A custom ScrollView can override this method to provide precise control over the upward scroll arrow. The framework can invoke this method at any time after performing a layout.

By default, this method returns true if the view can scroll upward.

Returns:

true if the arrow should be drawn, false otherwise.

isDataValid

public boolean isDataValid()

Indicates whether the data on the screen is valid.

Loops through all children, recursively invoking isDataValid() on each controlled field, and will return true if all children return true.

Overrides:

isDataValid in class Field

Returns:

true if all children return true, false otherwise.

Since:

BlackBerry API 4.2.0

isDirty

public boolean isDirty()

Determines if any controlled field is dirty.

Invoke this method to determine if any of this manager's controlled fields are dirty. A field is dirty if it has changed since the last time it was clean. A field is clean when it is first created, and also when explicitly cleaned by invoking setDirty(false).

Overrides:

isDirty in class Field

Returns:

true if any of this manager's controlled fields return true from an invocation of isDirty(), false otherwise.

See Also:

Field.isMuddy(), Field.setDirty(boolean)

isFocusable

public boolean isFocusable()

Determines if this manager accepts the focus.

Overrides:

isFocusable in class Field

Returns:

true if and only if any one of this manager's controlled fields (directly or indirectly) accepts the focus, false otherwise.

isMuddy

public boolean isMuddy()

Determines if any controlled field is muddy.

Invoke this method to determine if any of this manager's controlled fields are muddy. A field is muddy if it has changed and focus has not been moved or left the field since the change.

Overrides:

isMuddy in class Field

Returns:

true if at least one field is muddy, false otherwise.

See Also:

Field.isDirty(), Field.setMuddy(boolean)

isSelecting

public boolean isSelecting()

Determines if the field with the focus is in selection mode.

Overrides:

isSelecting in class Field

Returns:

true if the leaf field with the focus is currently in selection mode, false otherwise.

See Also:

Field.select(boolean)

isValidLayout

public final boolean isValidLayout()

Determines if this manager has a completed layout for its fields.

A manager's layout is valid after its screen has first been pushed onto the display stack.

Overrides:

isValidLayout in class ScrollView

Returns:

true if this manager has a completed layout for its controlled fields, false otherwise.

keyChar

protected boolean keyChar(char ch,
                          int status,
                          int time)

Handles key generation events.

This method sends the event to the field with focus. If no controlled field has the focus, this method does nothing and returns false.

Overrides:

keyChar in class Field

Parameters:

ch - The character that was generated.

status - The modifier key status.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.

keyControl

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

Sends key generation event to the controlled field with focus.

If no controlled field has the focus, this method does nothing and returns false.

Overrides:

keyControl in class Field

Parameters:

ch - The character that was generated.

status - The modifier key status.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.

keyDown

protected boolean keyDown(int keycode,
                          int time)

Sends key down event to the controlled field with focus.

If no controlled field has the focus, this method does nothing and returns false.

Overrides:

keyDown in class Field

Parameters:

keycode - The code of the key that was pressed.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.

keyRepeat

protected boolean keyRepeat(int keycode,
                            int time)

Sends key repeat event to the controlled field with focus.

If no controlled field has the focus, this method does nothing and returns false.

Overrides:

keyRepeat in class Field

Parameters:

keycode - The code of the key that was repeated.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.

keyStatus

protected boolean keyStatus(int keycode,
                            int time)

Sends key status event to the controlled field with focus.

If no controlled field has the focus, this method does nothing and returns false.

Overrides:

keyStatus in class Field

Parameters:

keycode - The code of the status key.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.

keyUp

protected boolean keyUp(int keycode,
                        int time)

Sends key up event to the controlled field with focus.

If no controlled field has the focus, this method does nothing and returns false.

Overrides:

keyUp in class Field

Parameters:

keycode - The code of the key that was released.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.

layout

protected final void layout(int width,
                            int height)

Lays out this manager's controlled fields in a standardized manner.

By default, this method sets any required scroll bars and sets the horizontal and vertical quantizations for layout components in a grid-like fashion.

If you are creating a customized layout by extending the Manager class, implement the Manager.sublayout(int, int) method in your subclass.

Invoking the Manager.sublayout(int, int) method prompts your manager subclass to lay out the controlled fields appropriately.

Specified by:

layout in class Field

Parameters:

width - The width available to this manager (in pixels).

height - The height available to this manager (in pixels).

layoutChild

protected final void layoutChild(Field field,
                                 int width,
                                 int height)

Prompts managed field to lay itself out.

Invoke this method to prompt this manager to tell one of its managed fields to lay itself out.

Parameters:

field - The field managed by this manager.

width - The width available to the field (in pixels).

height - The height available to the field (in pixels).

moveFocus

protected int moveFocus(int amount,
                        int status,
                        int time)

Called by the framework to move focus within this manager.

This method searches fields in their index order, attempting to pass the focus on to the next available field.

The amount parameter specifies the number of index positions to hop over when moving the focus. Use a negative amount to move backwards in this manager's list of fields, a positive value to forwards. Note that some controlled fields may support more than one focus position (date fields, for example).

This method ignores the status and time parameters, but passes them on to the controlled fields. The status parameter should contain modifiers to the trackwheel roll event, such as modifier keys held while rolling, direction of roll, and so forth.

When the focus is moved from a controlled field, the Manager.onUnfocus() handler method is invoked. Then, Manager.isFocusable() is invoked on the next controlled field to determine if it accepts the focus.

As the focus passes over each field that accepts the focus, the amount parameter's absolute value is reduced by one, and that field is provided with the chance to respond to a new focus event. If the amount parameter's absolute value is still greater than zero, the focus passes on to the next field which accepts it.

If either end of this manager's field list is reached (the top for negative amount values, the bottom for positive amount values), either because of a large amount value, or because there are no fields left that accept the focus, this method returns the remaining amount that wasn't used up. Notice that the sign for the amount is preserved, to retain the direction indicator.

Overrides:

moveFocus in class Field

Parameters:

amount - If positive, move focus forward this many index positions; if negative, move focus backwards this many index positions.

status - Trackwheel event modifiers.

time - The number of milliseconds since the device was turned on.

Returns:

The remaining scroll amount not used up, with the same sign as was originally provided with the amount parameter.

paint

protected void paint(Graphics graphics)

Paints this manager's visible region.

Invoke this method to prompt this manager to paint itself. If you extend Manager to create a custom layout manager, you may want to implement the Manager.subpaint(net.rim.device.api.ui.Graphics) method, as this method invokes it.

This method also draws the focus indicator as required.

Specified by:

paint in class Field

Parameters:

graphics - The graphics object used for painting.

paintChild

protected final void paintChild(Graphics graphics,
                                Field field)

Paints a controlled field.

Invoke this method to paint a controlled field. This method ensures the graphics stack and drawing attributes are ready before invoking the Manager.paint(net.rim.device.api.ui.Graphics) method on the field you provide.

If the controlled field is not within the clipping rect of the Graphics object, then the field will not be painted.

Parameters:

graphics - The graphics object used for painting.

field - The controlled field you wish to paint.

replace

public void replace(Field oldField,
                    Field newField)

Removes a field from this Manager and replaces it with another field.

The specified oldField must be a direct child of this manager and the specified newField must not be being managed by any Manager, including this one.

If oldField had the focus and newField is focusable, then Field.setFocus() will be invoked on newField after it is added to this manager.

This method is implemented as follows: After the runtime checks are passed then delete(oldField) is invoked, then insert(newField, index) is invoked, where index is the index of oldField when it was managed by this Manager, then newField.setFocus() is invoked if oldField had the focus when it was managed by this Manager.

Parameters:

oldField - The field to replace.

newField - The field to replace it with.

Throws:

IllegalArgumentException - if any argument is null, if oldField is not being managed by this Manager (ie. oldField.getManager() != this), or if newField is being managed by another Manager including this one (ie. newField.getManager() != null).

IllegalStateException - if oldField.getIndex() returns -1.

See Also:

Manager.delete(Field), Manager.insert(Field, int), Field.getIndex(), Field.getManager(), Field.setFocus()

Since:

BlackBerry API 4.2.0

sublayout

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

Parameters:

width - The width available for this manager.

height - The height available for this manager.

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

Parameters:

graphics - The graphics object used for painting.

onFocus

protected void onFocus(int direction)

Invoked by the framework when focus is gained.

When the framework invokes this method, it starts either at the start of the manager's controlled field list, or the end (depending on the passed direction parameter), looking for a field to give the focus.

This method passes the focus to the first field it finds to accept it.

Overrides:

onFocus in class Field

Parameters:

direction - Specify 1 to search forward from the first controlled field in this manager's list. Specify -1 to search backward from the last controlled field in this manager's list.

onUnfocus

protected void onUnfocus()

Invoked by the framework when focus is lost.

Overrides:

onUnfocus in class Field

nextFocus

protected int nextFocus(int direction,
                        boolean alt)

Deprecated. Please use Manager.nextFocus(int, int) instead

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

This method is called by the framework during a trackwheel focus move operation.

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

alt - If true the user is ALT-rolling the trackwheel, if false the user is not ALT-rolling the trackwheel.

Returns:

The index of the next field that should have focus, or -1 if focus should leave the manager.

Throws:

IllegalArgumentException - if direction has a value other than 1 or -1.

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.

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.

Throws:

IllegalArgumentException - if direction has a value other than 1 or -1.

Since:

BlackBerry API 5.0.0

moveFocus

protected void moveFocus(int x,
                         int y,
                         int status,
                         int time)

Moves focus to an exact position within this manager.

Invoke this method to place the focus on a precise point within this manager's region.

This method ignores the status and time parameters, but passes them on to the controlled fields. The status parameter should contain modifiers to the trackwheel roll event, such as modifier keys held while rolling, direction of roll, and so forth.

Overrides:

moveFocus in class Field

Parameters:

x - The distance from the left edge of the virtual region.

y - The distance from the top edge of the virtual region.

status - Trackwheel event modifiers.

time - The number of milliseconds since the device was turned on.

setFocus

public boolean setFocus(int x,
                        int y,
                        int status)

Sets focus to an exact position on the current screen.

This method retrieves a handle to the current screen, and then invokes setFocus on it (for the time parameter, it passes in a value of zero).

Parameters:

x - The distance from the left edge of the screen.

y - The distance from the top edge of the screen.

status - Modifiers when the trackwheel roll occured, from KeyPad.

Returns:

true if the field under desired point accepts the focus, false otherwise.

navigationClick

protected boolean navigationClick(int status,
                                  int time)

Invoked when the navigational action is selected.

The system invokes this method when passing on a navigational click event.

The ALT-click combination will enter selection mode, or if in selection mode will copy.

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:

navigationClick in class Field

Parameters:

status - A bitfield of values defined by KeypadListener.

time - The number of milliseconds since the device was turned on.

Returns:

true if this method consumed the event, false otherwise.

Since:

BlackBerry API 4.2.0

navigationMovement

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

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 ScrollView

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

navigationUnclick

protected boolean navigationUnclick(int status,
                                    int time)

Invoked when the navigational action is released.

The system invokes this method when passing on a navigational release event.

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:

navigationUnclick in class Field

Parameters:

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

setDirty

public void setDirty(boolean dirty)

Cleans or dirties all controlled fields.

Pass true to this method to dirty all this manager's controlled fields. Pass false to this method to clean all the controlled fields.

Overrides:

setDirty in class Field

Parameters:

dirty - If true the fields are dirtied, if false the fields are cleaned.

See Also:

Field.isDirty(), Field.setMuddy(boolean)

setHorizontalQuantization

public void setHorizontalQuantization(int horizontalQuanta)

Sets this manager's horizontal quantization.

Parameters:

horizontalQuanta - The horizontal quantization (in pixels); the real horizontal size must be a multiple of this value.

Throws:

IllegalArgumentException - if horizontalQuanta is negative and not equal to -1.

setPositionChild

protected final void setPositionChild(Field field,
                                      int x,
                                      int y)

Sets the position of a manager's field.

Parameters:

field - The field managed by this manager.

x - The offset of the left of the field in its manager.

y - The offset of the top of the field in its manager.

Throws:

IllegalArgumentException - if field is not a child of this manager.

setVerticalQuantization

public void setVerticalQuantization(int verticalQuanta)

Sets this manager's vertical quantization.

Parameters:

verticalQuanta - The vertical quantization (in pixels); the real vertical size must be a multiple of this value.

Throws:

IllegalArgumentException - if verticalQuanta is negative and not equal to -1.

trackwheelClick

protected boolean trackwheelClick(int status,
                                  int time)

Dispatches trackwheel event to the controlled field with focus.

If no controlled field has the focus, this method does nothing and returns false.

Overrides:

trackwheelClick in class Field

Parameters:

status - Trackwheel event modifiers.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.

makeMenu

protected void makeMenu(Menu menu,
                        int instance)

Called from Screen.makeMenuWithContext(net.rim.device.api.ui.component.Menu, int) to populate the menu.

If you override this function, you must call super.makeMenu(menu, instance) so that the sub managers's items are added to the menu.

Overrides:

makeMenu in class Field

Parameters:

menu - The menu to which items should be added.

instance - The instance of the desired menu. If your screen supports only one menu, this may be ignored. By default, it is 0.

Since:

BlackBerry API 4.0.0

setScrollingInertial

protected final void setScrollingInertial(boolean isScrollingInertial)

Sets whether the scrolling on this manager is inertial, overriding the system's default.

For this manager, this overrides the system-wide setting of inertial scrolling for managers.

Overrides:

setScrollingInertial in class ScrollView

Parameters:

isScrollingInertial - If true the scrolling for this manager is inertial (assuming it is supported on this device), if false scrolling is not inertial.

Since:

BlackBerry API 5.0.0

setVirtualExtent

protected final void setVirtualExtent(int virtualWidth,
                                      int virtualHeight)

Sets the virtual extent for this manager.

Use this method to specify the size of the area that child controls inhabit. If this extent is larger than the manager's visible area, scrolling is used to bring the extra area into view.

Subclasses should invoke this method when Manager.layout(int, int) is called.

Overrides:

setVirtualExtent in class ScrollView

Parameters:

virtualWidth - The width of the manager's virtual extent.

virtualHeight - The height of the manager's virtual extent.

touchEvent

protected boolean touchEvent(TouchEvent message)

Handles touch input events (see TouchEvent).

The coordinates reflect the location of the touch event with respect to the top-left of this manager. The x-y coordinates are then further mapped to the top-left corner of the field with input.

Overrides:

touchEvent in class Field

Parameters:

message - A TouchEvent object containing various input parameters, including the event type and touch coordinates.

Returns:

true if the event was consumed, false otherwise.

Throws:

IllegalArgumentException - if message is null.

Since:

BlackBerry API 4.7.0

cursorClick

protected boolean cursorClick(int x,
                              int y,
                              int status,
                              int time)

Indicates a cursor click event.

The system invokes this method when passing on a cursor click event.

Overrides:

cursorClick in class Field

Parameters:

x - X coordinate of the cursor event.

y - Y coordinate of the cursor event.

status - Bitfield of values defined by KeypadListener.

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

Returns:

True if this method consumed the event; otherwise, false.

Since:

BlackBerry API 7.0.0

cursorUnclick

protected boolean cursorUnclick(int x,
                                int y,
                                int status,
                                int time)

Indicates a cursor unclick event.

The system invokes this method when passing on a cursor unclick event.

Overrides:

cursorUnclick in class Field

Parameters:

x - X coordinate of the cursor event.

y - Y coordinate of the cursor event.

status - Bitfield of values defined by KeypadListener.

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

Returns:

True if this method consumed the event; otherwise, false.

Since:

BlackBerry API 7.0.0

cursorMovement

protected boolean cursorMovement(int x,
                                 int y,
                                 int status,
                                 int time)

Indicates a cursor movement event.

The system invokes this method when passing on a hover event.

Overrides:

cursorMovement in class Field

Parameters:

x - New x coordinate of the cursor.

y - New y coordinate of the cursor.

status - Bitfield of values defined by KeypadListener.

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

Returns:

True if this method consumed the event; otherwise, false.

Since:

BlackBerry API 7.1.0

shouldCursorScroll

public boolean shouldCursorScroll(int newX,
                                  int newY,
                                  int dx,
                                  int dy)

Returns true if the new position of the cursor would trigger a scroll, false otherwise.

Parameters:

newX - X coordinate of the cursor.

newY - Y coordinate of the cursor.

dx - Difference between newX and current X coordinate of cursor

dy - Difference between newY and current Y coordinate of cursor

Returns:

true if the new position of the cursor would trigger a scroll, false otherwise

Since:

BlackBerry API 7.1.0

trackwheelUnclick

protected boolean trackwheelUnclick(int status,
                                    int time)

Dispatches trackwheel released event to the controlled field with focus.

If no controlled field has the focus, this method does nothing and returns false.

Overrides:

trackwheelUnclick in class Field

Parameters:

status - Trackwheel event modifiers.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.