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

EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, READONLY, USE_ALL_HEIGHT, USE_ALL_WIDTH

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.

Method Summary

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(ResourceBundleFamily family, int id) Sets this field's label text.
String	toString() Returns a string representation of the object.

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

drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getChangeListener, getContextMenu, getCookie, getExtent, getFieldStyle, getFocusListener, getFocusRect, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getScreen, getStyle, getTop, getWidth, invalidate, invalidate, isDirty, isEditable, isFocusable, isMuddy, isPasteable, isSelectable, isSelecting, isSelectionCutable, isSelectionDeleteable, isVisible, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, makeContextMenu, moveFocus, moveFocus, onFocus, onUnfocus, onVisibilityChange, paste, select, selectionCut, selectionDelete, setChangeListener, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setPosition, 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.

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: can be a String, StringBuffer, char[] or byte[] (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: can be a String, StringBuffer, char[] or byte[] (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: can be a String, StringBuffer, char[] or byte[] (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.

Method Detail

isSelectionCopyable

public boolean isSelectionCopyable()

Determines if this field is copyable.

Overrides:

isSelectionCopyable in class Field

Returns:

True (label fields are always copyable).

getText

public String getText()

Retrieves this field's label text.

Invoke this method to retrieve the value of this labe 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.

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.

Since:

JDE 3.6

getPosition

public int getPosition()

Retrieves drawing offset of this field's label text.

Returns:

Drawing offset (in pixels) from the left edge.

getPreferredWidth

public int getPreferredWidth()

Retrieves this field's preferred width.

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.

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.

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.

Overrides:

layout in class Field

Parameters:

width - Amount of available horizontal space.

height - Amount of available vertical space.

Since:

JDE 3.6

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.

Overrides:

paint in class Field

Parameters:

graphics - Graphics context for repainting this field.

Since:

JDE 3.6

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.

Since:

JDE 3.6

setText

public void setText(Object text)

Sets this field's label text.

Parameters:

text - Label text: can be a String, StringBuffer, char[] or byte[] (may be null for an empty label).

Throws:

IllegalArgumentException - if text parameter is an unsupported type.

Since:

JDE 3.6

setText

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

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

Parameters:

text - Label text: can be a String, StringBuffer, char[] or byte[] (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.

Since:

JDE 3.6

setText

public void setText(ResourceBundleFamily family,
                    int id)

Sets this field's label text.

Since:

JDE 3.6

toString

public String toString()

Description copied from class: Object

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Overrides:

toString in class Object

Following copied from class: java.lang.Object

Returns:

a string representation of the object.