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

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by 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, 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, 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, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setNonSpellCheckable, 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





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.