net.rim.device.api.ui.component.pane
Class HorizontalScrollableTitleView

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.ScrollView
          extended by net.rim.device.api.ui.Manager
              extended by net.rim.device.api.ui.component.pane.TitleView
                  extended by net.rim.device.api.ui.component.pane.HorizontalScrollableTitleView
All Implemented Interfaces:
AdjustmentListener

public class HorizontalScrollableTitleView
extends TitleView

An extension of TitleView that presents the titles of Pane objects that are contained within the associated PaneManagerModel.

This class presents the titles as a horizontal scrollable bar. Three titles are presented at a time. The one representing the currently selected pane will be centered. The preceeding title, and the following title are partially presented at the sides of the view. These placements are the default positions from which HorizontalScrollableTitleView.drag(int, int, int, int, int) offsets.

This class is designed for use with HorizontalScrollableController.

Since:
BlackBerry API 6.0.0

Field Summary
 
Fields inherited from class net.rim.device.api.ui.Manager
BOTTOMMOST, DOWNWARD, HORIZONTAL_SCROLL, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_MASK, HORIZONTAL_SCROLL_MASK, LEAVE_BLANK_SPACE, LEFTMOST, LEFTWARD, NO_HORIZONTAL_SCROLL, NO_HORIZONTAL_SCROLLBAR, NO_SCROLL_RESET, NO_VERTICAL_SCROLL, NO_VERTICAL_SCROLLBAR, QUANTA_FONT, RIGHTMOST, RIGHTWARD, TOPMOST, UPWARD, VERTICAL_SCROLL, VERTICAL_SCROLLBAR, VERTICAL_SCROLLBAR_MASK, VERTICAL_SCROLL_MASK
 
Fields inherited from class net.rim.device.api.ui.Field
ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL
 
Constructor Summary
HorizontalScrollableTitleView(long style)
          Constructor that accepts a long of style bit flags and sets the Field.FOCUSABLE style bit.
 
Method Summary
 boolean areArrowsEnabled()
          Indicates if rendering of arrows is currently enabled.
 void drag(int dx, int dy, int index, int leftIndex, int rightIndex)
          Offsets the positions of the current titles within its pushed region.
protected  void drawFocus(Graphics graphics, boolean on)
          Draws the focus indicator for this field.
 void enableArrows(boolean enable)
          Enables or disables the use of Bitmap images as arrows to represent that there are more titles that can be scrolled to.
 int getNumberOfDisplayedPanes()
          Returns the number of panes that currently have titles displayed.
 XYRect getRegionExtent(int index)
          Provides the region of the Field that represents the touch region of a title within the currently pushed region.
 boolean isAnimating()
          Indicates if the view is currently animating the transition between panes.
 void jumpBackwards(boolean animate, int duration)
          Similar to HorizontalScrollableTitleView.jumpTo(int, int, int, boolean, int, int) except only causes a transition from the currently selected title to the one that preceeds it in the model.
 void jumpForwards(boolean animate, int duration)
          Similar to HorizontalScrollableTitleView.jumpTo(int, int, int, boolean, int, int) except only causes a transition from the currently selected title to the one that follows it in the model.
 void jumpTo(int index, int leftIndex, int rightIndex, boolean animate, int direction, int duration)
          Causes the view to move from the currently selected pane to the pane at the specified index.
protected  int nextFocus(int direction, int axis)
          Returns 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.
 void setModel(PaneManagerModel model)
          Associates a PaneManagerModel to this view.
 void snapToCurrent(boolean animate, int duration, int direction)
          Causes this view to move the currently selected pane back to its default layout position.
protected  void sublayout(int width, int height)
          Implements custom layout features for this manager.
protected  void subpaint(Graphics graphics)
          Implements custom paint features for this manager.
 
Methods inherited from class net.rim.device.api.ui.component.pane.TitleView
getLeftArrow, getModel, getRightArrow, setLeftArrow, setRightArrow
 
Methods inherited from class net.rim.device.api.ui.Manager
add, addAll, delete, deleteAll, deleteRange, getAccessibleContext, getField, getFieldAtLocation, getFieldCount, getFieldWithFocus, getFieldWithFocusIndex, getFocusRect, getHorizontalScroll, getLeafFieldWithFocus, getPreferredHeightOfChild, getPreferredWidthOfChild, getVerticalScroll, getVirtualHeight, getVirtualWidth, insert, insertAll, invalidate, invalidate, invalidateFieldRange, invokeAction, isDataValid, isDirty, isDownArrowShown, isFocusable, isMuddy, isSelecting, isUpArrowShown, isValidLayout, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, layout, layoutChild, makeMenu, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, nextFocus, paintChild, replace, setDirty, setFocus, setHorizontalQuantization, setPositionChild, setScrollingInertial, setVerticalQuantization, setVirtualExtent, touchEvent, trackwheelClick, trackwheelUnclick
 
Methods inherited from class net.rim.device.api.ui.ScrollView
configurationChanged, getHorizontalAdjustment, getVerticalAdjustment, getVisibleHeight, getVisibleWidth, onDisplay, onUndisplay, setCurrentLocation, setExtent, setHorizontalAdjustment, setHorizontalScroll, setHorizontalScroll, setScrollListener, setVerticalAdjustment, setVerticalScroll, setVerticalScroll, valueChanged, waitForScrolling
 
Methods inherited from class net.rim.device.api.ui.Field
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, getTop, getVisualState, getWidth, invalidateAll, isEditable, isEnabled, isFocus, isPasteable, isScrollCopyable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setEditable, setEnabled, setFocus, setFocusListener, 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
 



Constructor Detail

HorizontalScrollableTitleView

public HorizontalScrollableTitleView(long style)

Constructor that accepts a long of style bit flags and sets the Field.FOCUSABLE style bit.

Parameters:
style - the style bit flags to use for this Manager.
Since:
BlackBerry API 6.0.0


Method Detail

areArrowsEnabled

public boolean areArrowsEnabled()

Indicates if rendering of arrows is currently enabled. When enabled, arrows will render instead of partially displayed titles at the edges of the view.

Returns:
true if the rendering of arrows is enabled, otherwise false.
Since:
BlackBerry API 6.0.0

drag

public void drag(int dx,
                 int dy,
                 int index,
                 int leftIndex,
                 int rightIndex)

Offsets the positions of the current titles within its pushed region.

This view only allows for the horizontal movement of the titles, so the dy parameter is ignored.

Specified by:
drag in class TitleView
Parameters:
dx - the horizontal offset from the default position in pixels.
dy - the vertical offset from the default position in pixels - ingored in this class.
index - the index of the pane that is to be offset.
leftIndex - the index of the pane that is to appear to the left of the pane specified by the parameter index.
rightIndex - the index of the pane that is to appear to the right of the pane specified by the parameter index.
Since:
BlackBerry API 6.0.0

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)
Draws the focus indicator for this field.

A field's manager invokes this method after painting the field. The manager initializes the graphics object specified for drawing with field-local coordinates. It assumes that the region is already drawn correctly for the opposing state to that indicated by the on parameter.

When overriding this method, fields should use Field.drawHighlightRegion(net.rim.device.api.ui.Graphics, int, boolean, int, int, int, int) to render focus and select regions instead of hardcoding the logic.

By default this method invokes Field.drawHighlightRegion(net.rim.device.api.ui.Graphics, int, boolean, int, int, int, int) to render the focus indicator using the rect obtained from Manager.getFocusRect(net.rim.device.api.ui.XYRect).

Overrides:
drawFocus in class Field
Parameters:
graphics - Graphics context for drawing the focus.
on - True if the focus should be set; otherwise, false.
Since:
BlackBerry API 6.0.0

enableArrows

public void enableArrows(boolean enable)

Enables or disables the use of Bitmap images as arrows to represent that there are more titles that can be scrolled to. These can be accessed and provided by: TitleView.getLeftArrow(), TitleView.getRightArrow(), TitleView.setLeftArrow(Bitmap), TitleView.setRightArrow(Bitmap). When enabled arrows will be rendered at the edges instead of the titles of the preceeding and following panes.

Parameters:
enable - true to enable the usage of arrows, false to disable the rendering of arrows
Since:
BlackBerry API 6.0.0

getNumberOfDisplayedPanes

public int getNumberOfDisplayedPanes()

Returns the number of panes that currently have titles displayed. May not reflect the number of panes rendered during an animated transition between panes.

Specified by:
getNumberOfDisplayedPanes in class TitleView
Returns:
the number of titles of panes that are to being displayed when the field is static.
Since:
BlackBerry API 6.0.0

getRegionExtent

public XYRect getRegionExtent(int index)

Provides the region of the Field that represents the touch region of a title within the currently pushed region.

You specify the index of the title.

If the index does not match one of the titles currently being displayed then the method returns an empty XYRect.

The regions map to the touch regions and may not match the rendering extents of the Field objects of the titles.

Specified by:
getRegionExtent in class TitleView
Parameters:
index - the title whose region is to be retrieved.
Returns:
the XYRect of the title at the provided index or an empty XYRect if the index does not match that of a title that is currently visible.
Since:
BlackBerry API 6.0.0

isAnimating

public boolean isAnimating()

Indicates if the view is currently animating the transition between panes.

Specified by:
isAnimating in class TitleView
Returns:
true if the view is currently animating the transition between panes or false if the view is not currently animating the transition between pane.
Since:
BlackBerry API 6.0.0

jumpBackwards

public void jumpBackwards(boolean animate,
                          int duration)

Similar to HorizontalScrollableTitleView.jumpTo(int, int, int, boolean, int, int) except only causes a transition from the currently selected title to the one that preceeds it in the model.

Specified by:
jumpBackwards in class TitleView
Parameters:
animate - true to animate the transition false to just change the positions of the titles.
duration - the amount of time to animate the transition, in milliseconds
Since:
BlackBerry API 6.0.0

jumpForwards

public void jumpForwards(boolean animate,
                         int duration)

Similar to HorizontalScrollableTitleView.jumpTo(int, int, int, boolean, int, int) except only causes a transition from the currently selected title to the one that follows it in the model.

Specified by:
jumpForwards in class TitleView
Parameters:
animate - true to animate the transition false to just change the positions of the titles.
duration - the amount of time to animate the transition, in milliseconds
Since:
BlackBerry API 6.0.0

jumpTo

public void jumpTo(int index,
                   int leftIndex,
                   int rightIndex,
                   boolean animate,
                   int direction,
                   int duration)

Causes the view to move from the currently selected pane to the pane at the specified index. The direction controls the animation of the change from the currently selected pane to the new pane.

Specified by:
jumpTo in class TitleView
Parameters:
index - the index of the pane to become the currently selected pane.
leftIndex - index of the content Field to render to the left the one we are transitioning to.
rightIndex - index of the content Field to render to the right of the one we are transitioning to.
animate - true to animate this change, false to just render the new content pane in the final position.
direction - the control value for the animation to take place PaneManagerView.DIRECTION_BACKWARDS, PaneManagerView.DIRECTION_FORWARDS
duration - the amount of time to animate the transition, in milliseconds
Since:
BlackBerry API 6.0.0

nextFocus

protected int nextFocus(int direction,
                        int axis)
Returns the index of the next field that should be given focus.

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

The direction parameter indicates the direction in which the focus is moving: a value of 1 indicates that the focus is moving forward (generally down and to the right), while a value of -1 indicates that the focus is moving backwards (generally up and to the left).

The axis parameter indicates which axis of movement the direction is in. This can be one of Field.AXIS_SEQUENTIAL, Field.AXIS_HORIZONTAL or Field.AXIS_VERTICAL.

Overrides:
nextFocus in class Manager
Parameters:
direction - Direction the focus is moving within the field.
axis - The axis of movement.
Returns:
Index of the next field that should receive focus, -1 if the focus should leave the manager.
Since:
BlackBerry API 6.0.0

onFocus

protected void onFocus(int direction)
Invoked by the framework when focus is gained.

Overrides:
onFocus in class Manager
Parameters:
direction - (ignored in order to force proper focus display for the whole bar)
Since:
BlackBerry API 6.0.0

onUnfocus

protected void onUnfocus()
Invoked by the framework when focus is lost.

Overrides:
onUnfocus in class Manager
Since:
BlackBerry API 6.0.0

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 the manager to create a custom layout manager, you may want to implement the HorizontalScrollableTitleView.subpaint(net.rim.device.api.ui.Graphics) method, as this method invokes it.

This method also draws the focus indicator as required.

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

setModel

public void setModel(PaneManagerModel model)

Associates a PaneManagerModel to this view.

Overrides:
setModel in class TitleView
Parameters:
model - the PaneManagerModel to associate to this view.
Since:
BlackBerry API 6.0.0

snapToCurrent

public void snapToCurrent(boolean animate,
                          int duration,
                          int direction)

Causes this view to move the currently selected pane back to its default layout position. This undoes any offsets applied by calling HorizontalScrollableTitleView.drag(int, int, int, int, int).

The titles will also be reset to the default position corresponding to the currently selected pane.

This transition will be animated based on the provided direction.

If the view has been offset by calling HorizontalScrollableTitleView.drag(int, int, int, int, int) then calling this method will result in a visual effect of the pane having performed a slight bounce.

Specified by:
snapToCurrent in class TitleView
Parameters:
animate - true to animate the transition false to just change the positions of the titles.
duration - the amount of time to animate the transition, in milliseconds
direction - the animation control for which direction the panes should move with respect to the model: PaneManagerView.DIRECTION_BACKWARDS, PaneManagerView.DIRECTION_FORWARDS.
Since:
BlackBerry API 6.0.0

sublayout

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

To implement 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 setPositionChild for each child during sublayout. Note that setExtent must also be called, but it is the field's responsibility to do this in layout.

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

subpaint

protected void subpaint(Graphics graphics)
Implements custom paint features for this manager. Your implementation of this method should instruct all controlled fields in your Manager to paint themselves. Optimize this method 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).

By default, this method paints all child fields, without regard to the clipping region.

If implementing a custom manager that has requirements for special paint handling, you can override this method for optimization: HorizontalScrollableTitleView.paint(net.rim.device.api.ui.Graphics) invokes this method to perform custom paint functions.

Overrides:
subpaint in class Manager
Parameters:
graphics - Graphics object used for painting.
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.