net.rim.device.api.ui
Class ScrollView

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by 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 onDisplay()
          Invoked when the screen this field is attached to is pushed onto the display stack.
protected  void onUndisplay()
          Invoked when the screen this field is attached to is 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
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, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isMuddy, isPasteable, isScrollCopyable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, layout, makeContextMenu, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, onExposed, onFocus, onMenuDismissed, onMenuDismissed, onObscured, onUnfocus, onVisibilityChange, paint, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEditable, setEnabled, setFocus, setFocusListener, 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

onDisplay

protected void onDisplay()
Invoked when the screen this field is attached to is pushed onto the display stack.

This method is invoked by the system after the screen is pushed onto the stack and layout has been done, but before any painting occurs.

The complementing callback is #onUiEngineAttached.

Overrides:
onDisplay in class Field
Since:
BlackBerry API 6.0.0

onUndisplay

protected void onUndisplay()
Invoked when the screen this field is attached to is popped off the display stack.

The complementing callback is Field.onDisplay().

Overrides:
onUndisplay in class Field
Since:
BlackBerry API 6.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.
Throws:
IllegalStateException - If this ScrollView is non scrollable.
IllegalArgumentException - If position is negative.
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 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 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.
Throws:
IllegalStateException - If this ScrollView is non scrollable.
IllegalArgumentException - If position is negative.
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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.