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 that can be scrolled from side-to-side using the trackpad, trackball or touch gestures. The images slide horizontally with the focused image in the center. The images deccelerate as they approach their new position to give an animated effect.

All images occupy the same amount of space on the slider (as defined by the constructor's imageWidth and imageHeight parameters). If the distance between the horizontal center of two adjacent images is set to less than imageWidth, the images will overlap.

There are two ways to specify the image height:

Since:
BlackBerry API 5.0.0

Nested Class Summary
static class PictureScrollField.HighlightStyle
          A list of highlight styles for the selected picture.
static class PictureScrollField.ScrollEntry
          An entry in the PictureScrollField.
 
Field Summary
static int CONTEXT_CHANGE_SELECTION
          Context hint for the event being triggered by a selection change.
static int USE_ALL_HEIGHT
          Constant for specifying that the Field layout height is to use all remaining visible screen height
static int USE_PREFERRED_HEIGHT
          Constant for specifying that the field layout height is to be calculated with selected options
 
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_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL
 
Constructor Summary
PictureScrollField()
          Creates a new PictureScrollField which occupies all height of the visible screen.
PictureScrollField(int imageWidth, int imageHeight)
          Creates a new PictureScrollField that displays images with the specified width and height.
 
Method Summary
 int getCurrentImageIndex()
          Retrieves the index of the image that is selected.
 float getLensShrink()
          Retrieves the lens shrink value.
 int getPaddingImageTop()
          Retrieves the padding above the image.
 int getPreferredHeight()
          Retrieves this field's preferred height.
 int getPreferredWidth()
          Retrieves this field's preferred width.
 boolean hasCenteredLens()
          Determines if the centered lens is enabled.
 void selectImageAtCoordinate(int xCoordinate)
          Selects the image closest to the absolute x coordinate supplied.
 void setCenteredLens(boolean enabled)
          Enables or disables the centered lens.
 void setData(PictureScrollField.ScrollEntry[] entries, int focusIndex)
          Sets the pictures to display in the field and (optionally) their labels and call-outs.
 void setForegroundAlpha(int foregroundAlpha, int foregroundAlphaUnfocus)
          Sets focus and unfocus foreground alpha.
 void setHighlightBorderColor(int color)
          Sets the color of the border that appears when using Highlight Style SQUARE_BORDER and ILLUMINATE_WITH_SQUARE_BORDER.
 void setHighlightStyle(int style)
          Sets the style used to highlight the selected image.
 void setImageDistance(int gap)
          Sets the distance between the horizontal centers of two adjacent images.
 void setLabelSliderPadding(int padding)
          Sets the padding between the label and the images.
 void setLabelsVisible(boolean visible)
          Sets whether the PictureScrollField displays labels below the images.
 void setLensShrink(float lensShrink)
          Sets the lens shrink.
 void setPaddingImageBottom(int padding)
          Sets the padding below the images, in pixels.
 void setPaddingImageTop(int padding)
          Sets the padding above the images, in pixels.
 void setScalingRegion(int distance)
          Sets the distance between effects region edge and the center of the image.
 void setScrollbarVisible(boolean visible)
          Sets whether or not the scroll bar visible.
 void setStyle(int style)
          Sets the PictureScrollField instance's layout height style.
 void setTextColor(int color)
          Sets the color of the label text.
protected  boolean touchEvent(TouchEvent message)
          Indicates a touch event.
 void updateImage(Bitmap image, int index)
          Update the Bitmap image of the ScrollEntry at the specified index.
 
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, 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, onDisplay, onExposed, 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, setExtent, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, 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 by a selection change.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

USE_PREFERRED_HEIGHT

public static final int USE_PREFERRED_HEIGHT
Constant for specifying that the field layout height is to be calculated with selected options

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

USE_ALL_HEIGHT

public static final int USE_ALL_HEIGHT
Constant for specifying that the Field layout height is to use all remaining visible screen height

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0


Constructor Detail

PictureScrollField

public PictureScrollField()
Creates a new PictureScrollField which occupies all height of the visible screen. The image height is automatically calculated in layout and the image width is the same as image height.

Since:
BlackBerry API 6.0.0

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

setStyle

public void setStyle(int style)
Sets the PictureScrollField instance's layout height style.

Parameters:
style - The PictureScrollField layout height style. USE_PREFERRED_HEIGHT occupies the height which is calculated based on the desired image height and highlight style. USE_ALL_HEIGHT allows this field to take up all the remaining visible screen height.
Since:
BlackBerry API 6.0.0

getCurrentImageIndex

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

Returns:
The index.
Since:
BlackBerry API 5.0.0

getLensShrink

public float getLensShrink()
Retrieves the lens shrink value.

If the #SHRINK_LENS highlighting style is specified, the images not selected will decrease in size by this factor in a linear function away from the selected (center) image.

If the #MAGNIFY_LENS highlighting style is specified, the select (center) image will increase in size by this factor and the not selected images will not be resized.

Returns:
The lens shrink value.
Since:
BlackBerry API 5.0.0

getPaddingImageTop

public int getPaddingImageTop()
Retrieves 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()
Determines if the centered lens is enabled.

Returns:
true if the centered lens is enabled; false otherwise.
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)
Enables or disables the centered lens.

Parameters:
enabled - if true the lens is visible; if false, the lens is not visible
Since:
BlackBerry API 5.0.0

setData

public void setData(PictureScrollField.ScrollEntry[] entries,
                    int focusIndex)
Sets the pictures to display in the field 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 ScrollEntry objects to display in the PictureScrollField.
focusIndex - The index to select.
Since:
BlackBerry API 5.0.0

updateImage

public void updateImage(Bitmap image,
                        int index)
Update the Bitmap image of the ScrollEntry at the specified index.

Parameters:
image - the new Bitmap image.
index - The index of the ScrollEntry with updated image in array
Since:
BlackBerry API 6.0.0

setHighlightBorderColor

public void setHighlightBorderColor(int color)
Sets the color of the border that appears when using Highlight Style SQUARE_BORDER and ILLUMINATE_WITH_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 PictureScrollField.HighlightStyle constant (for example, PictureScrollField.HighlightStyle.NO_HIGHLIGHT, PictureScrollField.HighlightStyle.ILLUMINATE, and so on).
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 displays 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

setPaddingImageBottom

public void setPaddingImageBottom(int padding)
Sets the padding below the images, in pixels. By default the padding is set to 12 pixels.

Parameters:
padding - The desired padding in pixels.
Since:
BlackBerry API 6.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

setImageDistance

public void setImageDistance(int gap)
Sets the distance between the horizontal centers of two adjacent images. If the distance is larger than the image desired width, there is space between two adjacent images. If the distance is less than the image width, there is an overlap in images.

Parameters:
gap - The distance between two adjacent images horizontal center. By default, the distance is the desired image width plus horizontal padding.
Since:
BlackBerry API 6.0.0

setScrollbarVisible

public void setScrollbarVisible(boolean visible)
Sets whether or not the scroll bar visible.

Parameters:
visible - true to make the scroll bar visible, false otherwise.
Since:
BlackBerry API 6.0.0

setScalingRegion

public void setScalingRegion(int distance)
Sets the distance between effects region edge and the center of the image.

Parameters:
distance - The desired distance between effects region edge and the center of the image.
Since:
BlackBerry API 6.0.0

setForegroundAlpha

public void setForegroundAlpha(int foregroundAlpha,
                               int foregroundAlphaUnfocus)
Sets focus and unfocus foreground alpha. It is applied to images, label and scrollbar. Field background transparent alpha setting does not affected by this setting.

Parameters:
foregroundAlpha -
foregrounfAlphaUnfocus -
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.