net.rim.device.api.ui.component
Class BitmapField

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.component.BitmapField
All Implemented Interfaces:
DrawStyle

public class BitmapField
extends Field
implements DrawStyle

Displays a bitmap.

By default this field uses only enough area to fit its contained bitmap. If you specify an alignment style at construction, the field always uses the full width of the controlling manager's layout.

Behaviour

Displays a bitmap. By specifying the Field.FOCUSABLE style at construction, you can make this field focusable.

Animated image formats

This field supports the Animated GIF format for animations. The animation is started automatically. The number of loops for the animation is set by the encoded image. Use BitmapField.setImage(net.rim.device.api.system.EncodedImage) to specify the animated encoded image.


Field Summary
static int STAMP_MONOCHROME
          Stamp option.
 
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
 
Fields inherited from interface net.rim.device.api.ui.DrawStyle
BASELINE, BOTTOM, ELLIPSIS, HALIGN_MASK, HCENTER, HDEFAULT, HFULL, LEADING, LEFT, RIGHT, TOP, TRAILING, TRUNCATE_BEGINNING, VALIGN_MASK, VCENTER, VDEFAULT, VFULL
 
Constructor Summary
BitmapField()
          Constructs a new BitmapField instance.
BitmapField(Bitmap bitmap)
          Constructs a new BitmapField instance with provided bitmap.
BitmapField(Bitmap bitmap, long style)
          Constructs a new BitmapField instance with provided bitmap and alignment style.
 
Method Summary
protected  void drawFocus(Graphics graphics, boolean on)
          Draws the focus indicator for this field.
 AccessibleContext getAccessibleContext()
          Accessibility.
 int getBitmapHeight()
          Retrieves the height of this bitmap.
 int getBitmapWidth()
          Retrieves the width of this bitmap.
 int getPreferredHeight()
          Retrieves this field's preferred height.
 int getPreferredWidth()
          Retrieves this field's preferred width.
protected  void layout(int width, int height)
          Lays out this field's contents.
protected  void onExposed()
          Invoked when the screen this field is attached to is revealed by a screen getting popped off the display stack.
protected  void onObscured()
          Invoked when the screen this field is attached to is obscured by a new screen pushed on the display stack.
protected  void onUndisplay()
          Invoked when the screen this field is attached to is popped off the display stack.
protected  void onVisibilityChange(boolean visible)
          Called when the field's visibility changes.
protected  void paint(Graphics graphics)
          Redraws this field.
 void setBitmap(Bitmap bitmap)
          Sets the bitmap for this field.
 void setImage(EncodedImage image)
          Sets the EncodedImage for this field.
 void setSpace(int hSpace, int vSpace)
          Sets the border region for this field.
 
Methods inherited from class net.rim.device.api.ui.Field
cursorClick, cursorUnclick, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, 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, makeContextMenu, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, onDisplay, onFocus, onMenuDismissed, onMenuDismissed, onUnfocus, 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, touchEvent, trackwheelClick, trackwheelUnclick, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

STAMP_MONOCHROME

public static final int STAMP_MONOCHROME
Stamp option. Bitmaps that are 1 bit (in the future, any monochrome) and have alpha defined, are used as a stamp. The non-transparent region will be rendered in the foreground color.

See Also:
Constant Field Values
Since:
BlackBerry API 3.7.0


Constructor Detail

BitmapField

public BitmapField()
Constructs a new BitmapField instance.

This field uses the default style.


BitmapField

public BitmapField(Bitmap bitmap)
Constructs a new BitmapField instance with provided bitmap.

This field uses the default style.

Parameters:
bitmap - Bitmap to display in field.

BitmapField

public BitmapField(Bitmap bitmap,
                   long style)
Constructs a new BitmapField instance with provided bitmap and alignment style.

Use this method to build a bitmap with a specified alignment style. To build an alignment style value, you can combine one of VCENTER, TOP, and BOTTOM with one of HCENTER, LEFT, and RIGHT. If the horizontal alignments is DEFAULT (0), it will remain as DEFAULT, but behave as if it is LEFT. If the vertical alignment is DEFAULT (0), it will remain as DEFAULT, but behave as if it is TOP.

Note: If you want this field to be focusable, then you should also include Field.FOCUSABLE

Parameters:
bitmap - Bitmap to display in field.
style - Alignment style for this field.


Method Detail

drawFocus

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

This field's manager invokes this method after painting the field. Note that this method inverts only the bitmap itself, not the border region.

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

getBitmapHeight

public int getBitmapHeight()
Retrieves the height of this bitmap.

Returns:
Height (in pixels) of this bitmap.

getBitmapWidth

public int getBitmapWidth()
Retrieves the width of this bitmap.

Returns:
Width (in pixels) of this bitmap.

getPreferredHeight

public int getPreferredHeight()
Retrieves this field's preferred height. See Field.getPreferredHeight() for more information.

This field's manager invokes this method to assist in its layout.

Overrides:
getPreferredHeight in class Field
Returns:
Preferred height (in pixels) of this field.

getPreferredWidth

public int getPreferredWidth()
Retrieves this field's preferred width. See Field.getPreferredWidth() for more information.

This field's manager invokes this method to assist in its layout.

Overrides:
getPreferredWidth in class Field
Returns:
Preferred width (in pixels) of this field.

layout

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

This field's manager invokes this method during the layout process to instruct this field to arrange its contents, given an amount of available space.

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

paint

protected void paint(Graphics graphics)
Redraws this field.

This field's manager invokes this method during the repainting process to instruct this field to repaint itself. Note that invoking this method prompts a repaint of the entire bitmap contained in this field.

Specified by:
paint in class Field
Parameters:
graphics - Graphics context for repainting this field.

setBitmap

public void setBitmap(Bitmap bitmap)
Sets the bitmap for this field.

Provide a bitmap to this method to specify the image that this field should contain and display.

Using this method invokes Field.fieldChangeNotify(int), and marks the field as invalid (as long as this field is controlled by a valid manager).

Parameters:
bitmap - Bitmap image to display.

setImage

public void setImage(EncodedImage image)
Sets the EncodedImage for this field.

Provide an EncodedImage to this method to specify the image that this field should contain and display.

Using this method invokes Field.fieldChangeNotify(int), and marks the field as invalid (as long as this field is controlled by a valid manager).

This field supports the Animated GIF format for animations. The animation is started automatically. The number of loops for the animation is set by the encoded image.

Parameters:
image - EncodedImage to display.
Since:
BlackBerry API 3.7.0

setSpace

public void setSpace(int hSpace,
                     int vSpace)
Sets the border region for this field.

Use this method to specify the amount of horizontal and vertical padding placed around this field's contained bitmap image.

Parameters:
hSpace - Number of pixels of padding for both left and right sides.
vSpace - Number of pixels of padding for both top and bottom edges.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Accessibility.

Overrides:
getAccessibleContext in class Field
Returns:
An AccessibleContext instance that represents the field for a screen reader.
Since:
BlackBerry API 6.0.0

onVisibilityChange

protected void onVisibilityChange(boolean visible)
Called when the field's visibility changes.

Whenever an event occurs that changes the value returned from Field.isVisible(), this method is called. This includes when the application is brought to the foreground or background, when fields are added and removed, and when screens are pushed or popped.

UI calls that affect the field hierarchy or screen stack should not be called from this method. These changes can be done by using Application.invokeLater.

Note that in some circumstances this method may notify of a change that is not yet reflected in a call to isVisible. For example, this method may be called with the visible parameter as false, but isVisible still returns true.

Overrides:
onVisibilityChange in class Field
Parameters:
visible - If true the field has just become visible, if false the field has not just become visible.
See Also:
Field.onVisibilityChange(boolean)
Since:
BlackBerry API 6.0.0

onExposed

protected void onExposed()
Invoked when the screen this field is attached to is revealed by a screen getting popped off the display stack.

The complementing callback is Field.onObscured().

Overrides:
onExposed in class Field
See Also:
BitmapField.onObscured(), Field.onObscured()
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

onObscured

protected void onObscured()
Invoked when the screen this field is attached to is obscured by a new screen pushed on the display stack.

The complementing callback is Field.onExposed().

Overrides:
onObscured in class Field
See Also:
BitmapField.onExposed()
Since:
BlackBerry API 6.0.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal