net.rim.device.api.ui.extension.component
Class PictureScrollField

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.extension.component.PictureScrollField

public class PictureScrollField
extends Field

A slider component that draws a row of images which can be scrolled from side-to-side using the track-ball or touch gestures. The images slide horizontally to align the focus image in a vertically centered position. The images decelerate as they approach their new position to give an animated effect. There are also several configurable effects to highlight the focus image.

All images are allocated the same amount of space on slider (as defined by the constructor's imageWidth and imageHeight parameters). Images can differ from that size in which case the scroll field behaves as follows:

Since:
BlackBerry API 5.0.0

Nested Class Summary
static class PictureScrollField.HighlightStyle
          A list of configurable effects to highlight the focus picture.
static class PictureScrollField.ScrollEntry
          An entry in the PictureScrollField.
 
Field Summary
static int CONTEXT_CHANGE_SELECTION
          Context hint for the event being triggered from a selection change.
 
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
PictureScrollField(int imageWidth, int imageHeight)
          Creates a new PictureScrollField that displays images with the specified width and height.
 
Method Summary
protected  void drawFocus(Graphics graphics, boolean on)
          Draws the focus indicator for this field.
 int getCurrentImageIndex()
          Gets the index of the image that is selected.
 float getLensShrink()
          Gets the lens shrink.
 int getPaddingImageTop()
          Gets the padding above the image.
 int getPreferredHeight()
          Retrieves this field's preferred height.
 int getPreferredWidth()
          Retrieves this field's preferred width.
 boolean hasCenteredLens()
          Returns true if the centered lens is enabled, false otherwise.
protected  boolean keyChar(char character, int status, int time)
          Handles character generation events.
protected  void layout(int width, int height)
          Lays out field contents.
protected  boolean navigationMovement(int dx, int dy, int status, int time)
          Invoked when a navigational motion occurs.
protected  void onFocus(int direction)
          Invoked when a field receives the focus.
protected  void onUnfocus()
          Invoked when a field loses the focus.
protected  void paint(Graphics graphics)
          Invoked by the framework to redraw a portion of this field.
 void selectImageAtCoordinate(int xCoordinate)
          Selects the image closest to the absolute x coordinate supplied.
 void setCenteredLens(boolean enabled)
          Sets whether or not the centered lens in enabled.
 void setData(PictureScrollField.ScrollEntry[] entries, int focusIndex)
          Set the pictures and (optionally) their labels and call-outs.
 void setHighlightBorderColor(int color)
          Sets the color of the border that appears when using Highlight Style SQUARE_BORDER.
 void setHighlightStyle(int style)
          Sets the style used to highlight the selected image.
 void setLabelSliderPadding(int padding)
          Sets the padding between the label and the images.
 void setLabelsVisible(boolean visible)
          Sets whether the PictureScrollField will display labels below the images.
 void setLensShrink(float lensShrink)
          Sets the lens shrink.
 void setPaddingImageTop(int padding)
          Sets the padding above the images in pixels.
 void setTextColor(int color)
          Sets the color of the label text.
protected  boolean touchEvent(TouchEvent message)
          Indicates a touch event.
 
Methods inherited from class net.rim.device.api.ui.Field
drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getAccessibleContext, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFocusRect, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isFocus, isFocusable, isMuddy, isPasteable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyControl, keyDown, keyRepeat, keyStatus, keyUp, makeContextMenu, moveFocus, moveFocus, navigationClick, navigationUnclick, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setNonSpellCheckable, setPosition, setVisualState, trackwheelClick, trackwheelUnclick, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

CONTEXT_CHANGE_SELECTION

public static final int CONTEXT_CHANGE_SELECTION
Context hint for the event being triggered from a selection change.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0


Constructor Detail

PictureScrollField

public PictureScrollField(int imageWidth,
                          int imageHeight)
Creates a new PictureScrollField that displays images with the specified width and height.

Parameters:
imageWidth - The width of the images displayed in the field.
imageHeight - The height of the images displayed in the field.
Throws:
IllegalArgumentException - if imageWidth or imageHeight are <= 0.
Since:
BlackBerry API 5.0.0


Method Detail

drawFocus

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

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 5.0.0

getCurrentImageIndex

public int getCurrentImageIndex()
Gets the index of the image that is selected.

Returns:
The index.
Since:
BlackBerry API 5.0.0

getLensShrink

public float getLensShrink()
Gets the lens shrink.

Returns:
The lens shrink.
Since:
BlackBerry API 5.0.0

getPaddingImageTop

public int getPaddingImageTop()
Gets the padding above the image.

Returns:
The padding in pixels.
Since:
BlackBerry API 5.0.0

getPreferredHeight

public final int getPreferredHeight()
Retrieves this field's preferred height.

Overrides:
getPreferredHeight in class Field
Returns:
The height of the slider.
Since:
BlackBerry API 5.0.0

getPreferredWidth

public int getPreferredWidth()
Retrieves this field's preferred width. By default this method returns the width of the display. Override this method if you want the slider to consume less space.

Overrides:
getPreferredWidth in class Field
Returns:
The width of the display.
Since:
BlackBerry API 5.0.0

hasCenteredLens

public boolean hasCenteredLens()
Returns true if the centered lens is enabled, false otherwise.

Returns:
true if the centered lens is enabled, false otherwise.
Since:
BlackBerry API 5.0.0

navigationMovement

protected boolean navigationMovement(int dx,
                                     int dy,
                                     int status,
                                     int time)
Invoked when a navigational motion occurs.

Overrides:
navigationMovement in class Field
Parameters:
dx - Magnitude of navigational motion: negative for a move left and postive for a move right.
dy - Magnitude of navigational motion: negative for an upwards move, and positive for a downwards move.
status - Bitfield of values defined by KeypadListener.
time - Number of milliseconds since the device was turned on.
Returns:
False (classes that extend Field must override this method to provide specific handling).
Since:
BlackBerry API 5.0.0

keyChar

protected boolean keyChar(char character,
                          int status,
                          int time)
Handles character generation events.

Overrides:
keyChar in class Field
Parameters:
character - Character generated.
status - Modifier key status. See KeypadListener.
time - Number of milliseconds since the device was turned on.
Returns:
True if this method consumed the event; otherwise, false.
Since:
BlackBerry API 5.0.0

layout

protected void layout(int width,
                      int height)
Lays out field contents.

Specified by:
layout in class Field
Parameters:
width - Amount of available horizontal space.
height - Amount of available vertical space.
Since:
BlackBerry API 5.0.0

onFocus

protected void onFocus(int direction)
Invoked when a field receives the focus.

Overrides:
onFocus in class Field
Parameters:
direction - Indicates from which direction the focus enters the field.
Since:
BlackBerry API 5.0.0

onUnfocus

protected void onUnfocus()
Invoked when a field loses the focus.

Overrides:
onUnfocus in class Field
Since:
BlackBerry API 5.0.0

paint

protected void paint(Graphics graphics)
Invoked by the framework to redraw a portion of this field.

Specified by:
paint in class Field
Parameters:
graphics - Graphics context for drawing in this field.
Since:
BlackBerry API 5.0.0

selectImageAtCoordinate

public void selectImageAtCoordinate(int xCoordinate)
Selects the image closest to the absolute x coordinate supplied.

Parameters:
xCoordinate - The coordinate where selection should occur.
Since:
BlackBerry API 5.0.0

setCenteredLens

public void setCenteredLens(boolean enabled)
Sets whether or not the centered lens in enabled.

Parameters:
enabled - true to make the lens visible, false otherwise
Since:
BlackBerry API 5.0.0

setData

public void setData(PictureScrollField.ScrollEntry[] entries,
                    int focusIndex)
Set the pictures and (optionally) their labels and call-outs. This can be set multiple times on the same instance. Each call will discard any data set in previous calls.

Parameters:
entries - the array of ScrollEntries to display in the PictureScrollField.
focusIndex - the index to select.
Since:
BlackBerry API 5.0.0

setHighlightBorderColor

public void setHighlightBorderColor(int color)
Sets the color of the border that appears when using Highlight Style SQUARE_BORDER.

Parameters:
color - The color to use for the border.
Since:
BlackBerry API 5.0.0

setHighlightStyle

public void setHighlightStyle(int style)
Sets the style used to highlight the selected image.

Parameters:
style - the desired HighlightStyle
Since:
BlackBerry API 5.0.0

setLabelSliderPadding

public void setLabelSliderPadding(int padding)
Sets the padding between the label and the images.

Parameters:
padding - the desired padding in pixels
Since:
BlackBerry API 5.0.0

setLabelsVisible

public void setLabelsVisible(boolean visible)
Sets whether the PictureScrollField will display labels below the images.

Parameters:
visible - true if labels should be displayed, otherwise false.
Since:
BlackBerry API 5.0.0

setLensShrink

public void setLensShrink(float lensShrink)
Sets the lens shrink. Defaults to 0.7f.

Parameters:
lensShrink - The desired lens shrink factor.
Since:
BlackBerry API 5.0.0

setTextColor

public void setTextColor(int color)
Sets the color of the label text. By default the text is white.

Parameters:
color - The desired Color
Since:
BlackBerry API 5.0.0

setPaddingImageTop

public void setPaddingImageTop(int padding)
Sets the padding above the images in pixels. By default the padding is set to 12 pixels.

Parameters:
padding - The desired padding in pixels.
Since:
BlackBerry API 5.0.0

touchEvent

protected boolean touchEvent(TouchEvent message)
Indicates a touch event.

Overrides:
touchEvent in class Field
Parameters:
message - TouchEvent object containing various input parameters including the event type and touch coordinates.
Returns:
True if this method consumed the event; otherwise, false.
Since:
BlackBerry API 5.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.