net.rim.device.api.ui
Class ScrollView

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

All Implemented Interfaces:

AdjustmentListener

Direct Known Subclasses:

Manager

public abstract class ScrollView
extends Field
implements AdjustmentListener

This class provides fundamental scrolling functionality to all Managers.

This class is not intended to be directly subclassed by third party developers.

ScrollView is aware of horizontal and vertical scroll position and scroll boundaries, but not the content contained within. It provides a layer of abstraction between scrolling mechanics and rendering content. ScrollView can be used to get or modify the scroll position, with or without animation. Many helper methods are contained within, to execute common tasks associated with making a region visible or getting the state of scrolling.

ScrollView utilizes a horizontal and vertical Adjustment to encapsulate the state of each scrollable axis. The value of the Adjustment represents the current scroll position, in pixels, along that axis. Upper and lower values of the Adjustment are the scroll limits. Please note that bounce and elasticity animations allow the scroll position along each axis to temporarily move beyond the limits defined in the Adjustment. ScrollView will use pageSize on each Adjustment to divide it’s virtual area into a series of scrollable pages. PageStepSize will define the scroll threshold that mused be passed in order to move to the next page. StepSize from each Adjustment defines the amount of pixels scrolled, performed on a standard navigation movement.

Scroll paging, with ‘speed bump’ like animations can be enabled by setting values > 0 for pageSize and pageStepSize on the Adjustment representing the appropriate axis (horizontal or vertical).

Since:

BlackBerry API 6.0.0

Field Summary
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	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 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

Method Summary
void	configurationChanged(Adjustment a) Called by Adjustment when the config changes.
Adjustment	getHorizontalAdjustment() Get the Adjustment being used for horizontal scrolling.
int	getHorizontalScroll() Returns current horizontal offset of scrolling region.
Adjustment	getVerticalAdjustment() Get the Adjustment being used for vertical scrolling.
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.
int	getVisibleHeight() Retrieves height of this ScrollView's visible region.
int	getVisibleWidth() Retrieves width of this ScrollView's visible region.
protected void	onExposed() Invoked when the screen this field is attached to is revealed by a screen getting popped off the display stack.
void	setCurrentLocation(int x, int y) Sets this ScrollView's current location.
protected void	setExtent(int width, int height) Sets this field's extent.
void	setHorizontalAdjustment(Adjustment a) Set the Adjustment to be used for horizontal scrolling.
void	setHorizontalScroll(int position) Sets this ScrollView's horizontal scroll value.
void	setHorizontalScroll(int position, boolean animate) Sets this ScrollView's horizontal scroll value.
void	setScrollListener(ScrollChangeListener listener) Registers a listener for scroll changes.
protected void	setScrollingInertial(boolean isScrollingInertial) Sets whether the scrolling on this ScrollView is inertial, overriding the system's default.
void	setVerticalAdjustment(Adjustment a) Set the Adjustment to be used for vertical scrolling.
void	setVerticalScroll(int position) Sets this ScrollView's vertical scroll value.
void	setVerticalScroll(int position, boolean animate) Sets this ScrollView's vertical scroll value.
protected void	setVirtualExtent(int virtualWidth, int virtualHeight) Sets the virtual extent for this ScrollView.
void	valueChanged(Adjustment a) Called by Adjustment when the value changes.
void	waitForScrolling() Waits until the view's engine has stopped scrolling, then returns.

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

cursorClick, cursorUnclick, drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getAccessibleContext, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFocusRect, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTextFillColor, getTextStrokeColor, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isLeftToRight, isMuddy, isPasteable, isScrollCopyable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, layout, makeContextMenu, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, onDisplay, onFocus, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onUnfocus, onVisibilityChange, paint, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEditable, setEnabled, setFocus, setFocusListener, setFont, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, touchEvent, trackwheelClick, trackwheelUnclick, updateLayout

Methods inherited from class java.lang.Object

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

Field Detail

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

Since:

BlackBerry API 6.0.0

HORIZONTAL_SCROLL_MASK

protected static final long HORIZONTAL_SCROLL_MASK

Bitfield mask of the horizontal scroll style specifiers.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

HORIZONTAL_SCROLLBAR

public static final long HORIZONTAL_SCROLLBAR

ScrollView style to turn on horizontal scrollbars.

Note: this functionality has been implemented only for scroll arrows.

If VERTICAL_SCROLL_BAR is enabled then HORIZONTAL_SCROLL_BAR is ignored.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

HORIZONTAL_SCROLLBAR_MASK

protected static final long HORIZONTAL_SCROLLBAR_MASK

Bitfield mask of the horizontal scrollbar style specifiers.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

NO_HORIZONTAL_SCROLL

public static final long NO_HORIZONTAL_SCROLL

ScrollView will not support horizontal scrolling.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

NO_HORIZONTAL_SCROLLBAR

public static final long NO_HORIZONTAL_SCROLLBAR

ScrollView will not show horizontal scrollbars.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

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 6.0.0

NO_VERTICAL_SCROLL

public static final long NO_VERTICAL_SCROLL

ScrollView will not support vertical scrolling.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

NO_VERTICAL_SCROLLBAR

public static final long NO_VERTICAL_SCROLLBAR

ScrollView will not show vertical scrollbars.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

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

Since:

BlackBerry API 6.0.0

VERTICAL_SCROLL_MASK

protected static final long VERTICAL_SCROLL_MASK

Bitfield mask of the vertical scroll style specifiers.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

VERTICAL_SCROLLBAR

public static final long VERTICAL_SCROLLBAR

ScrollView style to turn on vertical scrollbars.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

VERTICAL_SCROLLBAR_MASK

protected static final long VERTICAL_SCROLLBAR_MASK

Bitfield mask of the vertical scrollbar style specifiers.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

Method Detail

getHorizontalScroll

public int getHorizontalScroll()

Returns current horizontal offset of scrolling region.

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

Returns:

Horizontal scroll value, in pixels.

Since:

BlackBerry API 6.0.0

getVerticalScroll

public int getVerticalScroll()

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.

Returns:

Vertical scroll offset, in pixels.

Since:

BlackBerry API 6.0.0

getVirtualHeight

public int getVirtualHeight()

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.

Returns:

Virtual height of this ScrollView, in pixels.

Since:

BlackBerry API 6.0.0

getVirtualWidth

public int getVirtualWidth()

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.

Returns:

Virtual width of this ScrollView, in pixels.

Since:

BlackBerry API 6.0.0

getVisibleHeight

public int getVisibleHeight()

Retrieves height of this ScrollView's visible region.

Returns:

Height in pixels of the portion of this ScrollView's region visible on the display.

Since:

BlackBerry API 6.0.0

getVisibleWidth

public int getVisibleWidth()

Retrieves width of this ScrollView's visible region. The visible width is the number of pixels that can be seen in this ScrollView's region at one time.

Returns:

Width in pixels of the portion of this ScrollView's region visible on the display.

Since:

BlackBerry API 6.0.0

onExposed

protected void onExposed()

Invoked when the screen this field is attached to is revealed by a screen getting popped off the display stack.

The complementing callback is Field.onObscured().

Overrides:

onExposed in class Field

Since:

BlackBerry API 7.0.0

setExtent

protected void setExtent(int width,
                         int height)

Sets this field's extent.

The field calls this method during layout to set its extent (height and width). Anything overriding this method should call super.setExtent(width,height).

Overrides:

setExtent in class Field

Parameters:

width - Width of the field.

height - Height of the field.

Since:

BlackBerry API 6.0.0

setHorizontalScroll

public void setHorizontalScroll(int position)

Sets this ScrollView's horizontal scroll value.

Invoke this method to adjust the horizontal scroll value for this ScrollView. This method is not normally invoked as focus movement deals with scrolling automatically.

If you use this function to set the scroll value for a screen that is not on the display stack you must push the screen onto the stack first, before invoking this method.

Parameters:

position - New horizontal scroll position.

Since:

BlackBerry API 6.0.0

setHorizontalScroll

public void setHorizontalScroll(int position,
                                boolean animate)

Sets this ScrollView's horizontal scroll value.

Invoke this method to adjust the horizontal scroll value for this ScrollView. This method is not normally invoked as focus movement deals with scrolling automatically.

If you use this function to set the scroll value for a screen that is not on the display stack you must push the screen onto the stack first, before invoking this method.

Parameters:

position - New horizontal scroll position. Ignored if scrolling is not possible.

animate - Animate the scrolling if true, jump to the new scroll position if false

Since:

BlackBerry API 6.0.0

setScrollingInertial

protected void setScrollingInertial(boolean isScrollingInertial)

Sets whether the scrolling on this ScrollView is inertial, overriding the system's default. For this ScrollView, this overrides the system-wide setting of inertial scrolling for ScrollViews.

Parameters:

isScrollingInertial - whether the scrolling for this ScrollView is "inertial", assuming that it is supported on this device.

Since:

BlackBerry API 6.0.0

setScrollListener

public void setScrollListener(ScrollChangeListener listener)

Registers a listener for scroll changes.

To unregister a scroll listener, pass null into this method.

Parameters:

listener - Object that listens for scroll changes.

Throws:

IllegalStateException - when there is already a listener set and your listener parameter is non-null.

Since:

BlackBerry API 6.0.0

setCurrentLocation

public void setCurrentLocation(int x,
                               int y)

Sets this ScrollView's current location.

Invoke this method to adjust the current location for this ScrollView. This method is not normally invoked as focus movement deals with scrolling automatically.

If you use this function to set the scroll value for a screen that is not on the display stack you must push the screen onto the stack first, before invoking this method.

Parameters:

x - New horizontal scroll position.

x - New vertical scroll position.

Since:

BlackBerry API 6.0.0

setVerticalScroll

public void setVerticalScroll(int position)

Sets this ScrollView's vertical scroll value.

Invoke this method to adjust the vertical scroll value for this ScrollView. This method is not normally invoked as focus movement deals with scrolling automatically.

If you use this function to set the scroll value for a screen that is not on the display stack you must push the screen onto the stack first, before invoking this method.

Parameters:

position - New vertical scroll position.

Since:

BlackBerry API 6.0.0

setVerticalScroll

public void setVerticalScroll(int position,
                              boolean animate)

Sets this ScrollView's vertical scroll value.

Invoke this method to adjust the vertical scroll value for this ScrollView. This method is not normally invoked as focus movement deals with scrolling automatically.

If you use this function to set the scroll value for a screen that is not on the display stack you must push the screen onto the stack first, before invoking this method.

Parameters:

position - New vertical scroll position. Ignored if scrolling is not possible.

animate - Animate the scrolling if true, jump to the new scroll position if false

Since:

BlackBerry API 6.0.0

setVirtualExtent

protected void setVirtualExtent(int virtualWidth,
                                int virtualHeight)

Sets the virtual extent for this ScrollView.

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

Subclasses should invoke this method when layout is called.

Parameters:

virtualWidth - Width of the ScrollView's virtual extent.

virtualHeight - Height of the ScrollView's virtual extent.

Since:

BlackBerry API 6.0.0

configurationChanged

public void configurationChanged(Adjustment a)

Called by Adjustment when the config changes.

Specified by:

configurationChanged in interface AdjustmentListener

Parameters:

a - source Adjustment

Since:

BlackBerry API 6.0.0

valueChanged

public void valueChanged(Adjustment a)

Called by Adjustment when the value changes.

Specified by:

valueChanged in interface AdjustmentListener

Parameters:

a - source Adjustment

Since:

BlackBerry API 6.0.0

setHorizontalAdjustment

public void setHorizontalAdjustment(Adjustment a)

Set the Adjustment to be used for horizontal scrolling. This object encapsulates values and characteristics the ScrollView adheres to for this axis. ScrollView is an AdjustmentListener registered on each axis, therefore any changes to the Adjustment representing this axis will result in changes to the ScrollView.

Parameters:

a - Adjustment representing the horizontal axis. Use this object to modify scroll position, boundaries, page sizes, page step size required to move to the next page, and step size used for nav movement.

Since:

BlackBerry API 6.0.0

setVerticalAdjustment

public void setVerticalAdjustment(Adjustment a)

Set the Adjustment to be used for vertical scrolling. This object encapsulates values and characteristics the ScrollView adheres to for this axis. ScrollView is an AdjustmentListener registered on each axis, therefore any changes to the Adjustment representing this axis will result in changes to the ScrollView.

Parameters:

a - Adjustment representing the vertical axis. Use this object to modify scroll position, boundaries, page sizes, page step size required to move to the next page, and step size used for nav movement.

Since:

BlackBerry API 6.0.0

getHorizontalAdjustment

public Adjustment getHorizontalAdjustment()

Get the Adjustment being used for horizontal scrolling. This object encapsulates values and characteristics the ScrollView adheres to for this axis. ScrollView is an AdjustmentListener registered on each axis, therefore any changes to the Adjustment representing this axis will result in changes to the ScrollView.

Returns:

Adjustment representing the horizontal axis. Use this object to modify scroll position, boundaries, page sizes, page step size required to move to the next page, and step size used for nav movement.

Since:

BlackBerry API 6.0.0

getVerticalAdjustment

public Adjustment getVerticalAdjustment()

Get the Adjustment being used for vertical scrolling. This object encapsulates values and characteristics the ScrollView adheres to for this axis. ScrollView is an AdjustmentListener registered on each axis, therefore any changes to the Adjustment representing this axis will result in changes to the ScrollView.

Returns:

Adjustment representing the vertical axis. Use this object to modify scroll position, boundaries, page sizes, page step size required to move to the next page, and step size used for nav movement.

Since:

BlackBerry API 6.0.0

waitForScrolling

public void waitForScrolling()

Waits until the view's engine has stopped scrolling, then returns.

Since:

BlackBerry API 6.0.0