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

java.lang.Object
  net.rim.device.api.ui.Field
      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:

• let the field calculate the height with the preferred highlight style
• let the field occupy all the remaining visible screen 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.
boolean	isLastTapOnFocusedImage() Tracing the latest TAP touch event.
boolean	isLastTapOnNewImage() Tracing the latest TAP touch event.
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

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, 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, 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, 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

isLastTapOnNewImage

public boolean isLastTapOnNewImage()

Tracing the latest TAP touch event.

Returns:

true if the latest TAP touch is vertically aligned with a new image in the field, false otherwise.

Since:

BlackBerry API 7.0.0

isLastTapOnFocusedImage

public boolean isLastTapOnFocusedImage()

Tracing the latest TAP touch event.

Returns:

true if the latest TAP touch is vertically aligned with the focused image in the field, false otherwise.

Since:

BlackBerry API 7.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 - A TouchEvent object containing various input parameters including the event type and touch coordinates.

Returns:

true if this method consumed the event, false otherwise.

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