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

java.lang.Object
  net.rim.device.api.ui.Field
      net.rim.device.api.ui.component.LabelField

All Implemented Interfaces:

DrawStyle

public class LabelField
extends Field
implements DrawStyle

Contains a simple label.

Behaviour
Displays a label. Optionally focusable. Optionally can shorten text (with an ellipsis) that is too long.

Field Summary
static int	DEFAULT_POSITION Default horizontal position.

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

LabelField()
Constructs a new LabelField instance.

LabelField(Object text)
Constructs a new LabelField instance with initial text.

LabelField(Object text, int offset, int length, long style)
Construct a new LabelField with provided style, and substring of provided text.

LabelField(Object text, long style)
Constructs a new LabelField with provided style.

LabelField(ResourceBundleFamily rb, int key)
Constructs a new LabelField instance with initial text from a resource bundle.

Method Summary
AccessibleContext	getAccessibleContext() Returns accessible representation of the field for a screen reader.
int	getPosition() Retrieves drawing offset of this field's label text.
int	getPreferredHeight() Retrieves this field's preferred height.
int	getPreferredWidth() Retrieves this field's preferred width.
String	getText() Retrieves this field's label text.
boolean	isSelectionCopyable() Determines if this field is copyable.
protected void	layout(int width, int height) Lays out this field's contents.
protected void	paint(Graphics graphics) Redraws this field.
void	selectionCopy(Clipboard cb) Copies this field's label text to the clipboard.
void	setPosition(int position) Sets horizontal drawing position for label text.
void	setText(Object text) Sets this field's label text.
void	setText(Object text, int offset, int length) Sets this field's label with substring of provided text.
void	setText(String text, int offset, int length) Sets this field's label with substring of provided text.
void	setText(ResourceBundleFamily rb, int key) Sets this field's label text.
String	toString() Retreives this field's text in a string.

Methods inherited from class net.rim.device.api.ui.Field

drawFocus, 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, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isMuddy, isPasteable, isScrollCopyable, isSelectable, isSelecting, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, makeContextMenu, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, onDisplay, onExposed, onFocus, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onUnfocus, onVisibilityChange, paste, select, 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, touchEvent, trackwheelClick, trackwheelUnclick, updateLayout

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_POSITION

public static final int DEFAULT_POSITION

Default horizontal position.

See Also:

Constant Field Values

Constructor Detail

LabelField

public LabelField()

Constructs a new LabelField instance.

Builds a new label field with no initial text.

LabelField

public LabelField(Object text)

Constructs a new LabelField instance with initial text.

Parameters:

text - Label text which may be a String, StringBuffer, StringProvider, character array (char[]), or byte array (byte[]). It may be null for an empty label.

Throws:

IllegalArgumentException - if text parameter is an unsupported type.

LabelField

public LabelField(Object text,
                  long style)

Constructs a new LabelField with provided style.

Valid styles for a label field are: Field.FOCUSABLE, Field.USE_ALL_WIDTH, DrawStyle.ELLIPSIS, any of Field's horizontal or vertical alignment styles.

Parameters:

text - Label text which may be a String, StringBuffer, StringProvider, character array (char[]), or byte array (byte[]). It may be null for an empty label.

style - Style for this field.

Throws:

IllegalArgumentException - If text parameter is an unsupported type.

LabelField

public LabelField(Object text,
                  int offset,
                  int length,
                  long style)

Construct a new LabelField with provided style, and substring of provided text.

Parameters:

text - Label text which may be a String, StringBuffer, StringProvider, character array (char[]), or byte array (byte[]. It may be null for an empty label.

offset - First character of text to use for the label.

length - Number of characters to use for the label (specify -1 to use the rest of the text after your offset).

style - Style for this field.

Throws:

IllegalArgumentException - If offset parameter is negative or beyond the end of the text parameter's length, if length parameter is invalid, or text parameter is an unsupported type.

LabelField

public LabelField(ResourceBundleFamily rb,
                  int key)

Constructs a new LabelField instance with initial text from a resource bundle.

Parameters:

rb - Resource bundle containing label text.

key - Key for resource containing label text.

Since:

BlackBerry API 4.0.0

Method Detail

isSelectionCopyable

public boolean isSelectionCopyable()

Determines if this field is copyable.

Overrides:

isSelectionCopyable in class Field

Returns:

True (label fields are always copyable).

getPosition

public int getPosition()

Retrieves drawing offset of this field's label text.

Returns:

Drawing offset (in pixels) from the left edge.

getPreferredHeight

public int getPreferredHeight()

Retrieves this field's preferred height.

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.

getText

public String getText()

Retrieves this field's label text.

Invoke this method to retrieve the value of this label field. If the label text was set to null, this method returns an empty string.

Note: this method may allocate a new String object each time you invoke it.

Returns:

Label text string.

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.

Specified by:

paint in class Field

Parameters:

graphics - Graphics context for repainting this field.

selectionCopy

public void selectionCopy(Clipboard cb)

Copies this field's label text to the clipboard.

Overrides:

selectionCopy in class Field

Parameters:

cb - Clipboard object to contain the clipped value from this field.

setPosition

public void setPosition(int position)

Sets horizontal drawing position for label text.

Parameters:

position - Offset (in pixels) from left edge of this field.

Throws:

IllegalArgumentException - If position parameter is negative.

setText

public void setText(Object text)

Sets this field's label text.

Parameters:

text - Label text which may be a string, string buffer, character array, or byte array (may be null for an empty label).

Throws:

IllegalArgumentException - if text parameter is an unsupported type.

setText

public void setText(Object text,
                    int offset,
                    int length)

Sets this field's label with substring of provided text.

Parameters:

text - Label text which may be a String, StringBuffer, char array, or byte array (may be null for an empty label).

offset - First character of text to use for label.

length - Number of characters to use for label (provide -1 to mean from offset to end of text parameter).

Throws:

IllegalArgumentException - if offset parameter is negative or beyond the end of the text parameter's length, if length parameter is invalid, or text parameter is an unsupported type.

setText

public void setText(String text,
                    int offset,
                    int length)

Sets this field's label with substring of provided text.

Parameters:

text - Label text which may be a String

offset - First character of text to use for label.

length - Number of characters to use for label (provide -1 to mean from offset to end of text parameter).

Throws:

IllegalArgumentException - if offset parameter is negative or beyond the end of the text parameter's length, if length parameter is invalid, or text parameter is an unsupported type.

Since:

BlackBerry API 4.1.0, 4.0.2

setText

public void setText(ResourceBundleFamily rb,
                    int key)

Sets this field's label text.

Parameters:

rb - Resource bundle containing label text.

key - Key for resource containing label text.

Since:

BlackBerry API 3.6.0

toString

public String toString()

Retreives this field's text in a string.

Overrides:

toString in class Object

Returns:

String form of this field's text.

getAccessibleContext

public AccessibleContext getAccessibleContext()

Returns accessible representation of the field for a screen reader.

Overrides:

getAccessibleContext in class Field

Returns:

AccessibleContext instance

Since:

BlackBerry API 4.6.1