Field (BlackBerry JDE 5.0.0 API Reference)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

net.rim.device.api.ui
Class Field

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

Direct Known Subclasses:: MapField, Manager, BitmapField, ButtonField, CheckboxField, ChoiceField, DateField, GaugeField, LabelField, ListField, NullField, RadioButtonField, SeparatorField, SpinBoxField, TextField, TreeField, PictureScrollField

public abstract class Field
extends Object
extends Object

Provides fundamental functionality for all field components.

A field represents a rectangular region contained by a manager. The field sizes itself according to its needs in layout. The manager, rather than the contained fields, completely handles scrolling.

You can't instantiate Field directly, rather, use one of the provided specialized field components in net.rim.device.api.ui.component, or extend Field to create your own, custom field type.

Creating your own custom fields
To design your own custom field, you must (at least) implement the layout and paint abstract methods to provide the behavior needed by your field.

You should also override the getPreferredWidth and getPreferredHeight methods, to ensure proper layout within some of the layout managers.

Handling focus issues
If you want your field to receive the focus, then you must override isFocusable to return true.

The framework invokes onFocus when the field gains focus, and onUnfocus when the field loses focus. You can override the methods if your field requires specific behavior for these events.

The framework invokes moveFocus to handle focus movements within a field. This corresponds to the trackwheelRoll event, and you can override moveFocus for special behavior. For example, a ChoiceField overrides this method and returns false (consumes the event) when the user presses the ALT key. When the ALT key is not pressed, the choice field delegates to the base class moveFocus method.

You can change the appearance of the default focus indicator by overriding drawFocus.

Forcing field repainting
To force a field to update or redraw itself, you should invoke its invalidate method. This class provides two forms of the method: use one to force the entire field to repaint itself, use the second to specify a region within the field that requires repainting.

Field's "cleanliness" state
A field's cleanliness state tracks when changes happen to a field. When a field's contents are changed and the field still has the focus, the field is set to be both "muddy" and "dirty" (dirty is implied by the muddy state). After the focus moves away from the field, it loses the muddy state, but remains dirty, as its contents have still been changed. Only when the field is explicitly set to the clean state (by invoking setDirty(false)) does it become clean again.

Field Summary
`static int`	`ACTION_INVOKE` Constant to indicate that the default action was invoked.
`static int`	`AXIS_HORIZONTAL` Axis specifier.
`static int`	`AXIS_SEQUENTIAL` Axis specifier.
`static int`	`AXIS_VERTICAL` Axis specifier.
`static long`	`EDITABLE` Field style bit to indicate whether or not the user can change the contents.
`protected static long`	`EDITABLE_MASK` Field style mask to indicate whether or not the user can change the contents.
`static long`	`FIELD_BOTTOM` Field is aligned to the bottom (style bit).
`protected static long`	`FIELD_HALIGN_MASK` Bitfield mask of the horizontal alignment style specifier.
`static long`	`FIELD_HCENTER` Field is centered horizontally (style bit).
`static long`	`FIELD_LEADING` Field is aligned to the current locale's start-of-line.
`static long`	`FIELD_LEFT` Field is aligned to the left (style bit).
`static long`	`FIELD_RIGHT` Field is aligned to the right (style bit).
`static long`	`FIELD_TOP` Field is aligned to the top (style bit).
`static long`	`FIELD_TRAILING` Field is aligned to the current locale's end-of-line.
`protected static long`	`FIELD_VALIGN_MASK` Bitfield mask of the vertical alignment style specifier.
`static long`	`FIELD_VCENTER` Specifies that the field is centered vertically (style bit).
`static long`	`FOCUSABLE` Field style bit to indicate whether or not the field is focusable.
`protected static long`	`FOCUSABLE_MASK` Field style mask to indicate whether the field allows focus.
`static int`	`HIGHLIGHT_FOCUS` Highlight bit to indicate focus highlighting.
`static int`	`HIGHLIGHT_SELECT` Highlight bit to indicate select highlighting.
`static long`	`NON_FOCUSABLE` Field style bit to indicate whether or not the field is non-focusable.
`static long`	`NON_SPELLCHECKABLE` Field style bit to indicate that field is not spellcheckable.
`static long`	`READONLY` Field style bit to indicate whether or not the user can change the contents.
`static long`	`SPELLCHECKABLE` Field style bit to indicate that field is spellcheckable.
`protected static long`	`SPELLCHECKABLE_MASK` Field style mask to indicate whether spelling check can be run for this field.
`static int`	`STATUS_MOVE_FOCUS_HORIZONTALLY` Focus movement event has a horizontal bias.
`static int`	`STATUS_MOVE_FOCUS_VERTICALLY` Focus movement event has a vertical bias.
`static long`	`USE_ALL_HEIGHT` Field uses all the height given to it by its manager (style bit).
`static long`	`USE_ALL_WIDTH` Field uses all the width given to it by its manager (style bit).
`static int`	`VISUAL_STATE_ACTIVE` Active visual state.
`static int`	`VISUAL_STATE_DISABLED` Disabled visual state.
`static int`	`VISUAL_STATE_DISABLED_FOCUS` Disabled, but focused visual state.
`static int`	`VISUAL_STATE_FOCUS` Focus visual state.
`static int`	`VISUAL_STATE_NORMAL` Normal visual state.

Constructor Summary
`protected`	`Field()` Constructs a new Field instance with no style attributes.
`protected`	`Field(long style)` Constructs a new Field instance with specified style attributes.

Method Summary
`protected void`	`drawFocus(Graphics graphics, boolean on)` Draws the focus indicator for this field.
`protected void`	`drawHighlightRegion(Graphics graphics, int style, boolean on, int x, int y, int width, int height)` Draws a highlight indicator for a rectangular region.
`protected void`	`fieldChangeNotify(int context)` Invoked for this field when a change event occurs.
`protected void`	`focusAdd(boolean draw)` Adds focus to this field.
`protected void`	`focusRemove()` Removes focus from this field.
`AccessibleContext`	`getAccessibleContext()` Returns accessible representation of the field for a screen reader.
`Background`	`getBackground()` Retrieve the current background object based on current visual state of the field.
`Background`	`getBackground(int visual)` Retrieve the current background object based on a specified visual state of the field.
`Border`	`getBorder()` Retrieve the current border object for this field based on current visual state of the field.
`Border`	`getBorder(int visual)` Retrieve the current border object for this field based on a specified visual state of the field.
`void`	`getBorder(XYEdges edges)` Retrieves the current border edges for this field into the specified `XYEdges` object.
`FieldChangeListener`	`getChangeListener()` Retrieves the current change listener.
`int`	`getContentHeight()` Retrieves this field's content height.
`int`	`getContentLeft()` Retrieves this field's content's left-most extent.
`XYRect`	`getContentRect()` Retrieves this field's extent (region occupied in its manager's child region).
`void`	`getContentRect(XYRect rect)` Retrieves this field's extent (region occupied in its manager's child region).
`int`	`getContentTop()` Retrieves this field's content's top-most extent.
`int`	`getContentWidth()` Retrieves this field's content width.
`ContextMenu`	`getContextMenu()` Gets the current context menu for this field.
`Object`	`getCookie()` Retrieves previously set cookie.
`XYRect`	`getExtent()` Retrieves this field's extent (region occupied in its manager's child region).
`void`	`getExtent(XYRect extent)` Retrieves this field's extent (region occupied in its manager's child region).
`int`	`getFieldStyle()` Retrieves this field's current custom field styles as an integer.
`FocusChangeListener`	`getFocusListener()` Retrieves the current focus listener.
`void`	`getFocusRect(XYRect rect)` Retrieves this field's current focus region.
`Font`	`getFont()` Retrieves this field's current font.
`int`	`getHeight()` Retrieves this field's height.
`int`	`getIndex()` Retrieves position of this field within its manager.
`Field`	`getLeafFieldWithFocus()` Retrieves the leaf (non-manager) field with the focus.
`int`	`getLeft()` Retrieves this field's left-offset position.
`Manager`	`getManager()` Retrieves this field's manager.
`Field`	`getOriginal()` Retrieves original instance of this field.
`int`	`getPreferredHeight()` Retrieves this field's preferred height.
`int`	`getPreferredWidth()` Retrieves this field's preferred width.
`Screen`	`getScreen()` Retrieves the screen that currently owns this field.
`long`	`getStyle()` Retrieves this field's current style bits.
`int`	`getTop()` Retrieves this field's top-offset position.
`int`	`getVisualState()` Retrieves this field's current visual state, which can be set via `Field.setVisualState(int)`.
`int`	`getWidth()` Retrieves this field's width.
`protected void`	`invalidate()` Marks this entire field invalid.
`protected void`	`invalidate(int x, int y, int width, int height)` Marks a region of this field as invalid (requiring repainting).
`protected void`	`invalidateAll(int x, int y, int width, int height)` Marks a region of this field as invalid (requiring repainting).
`protected boolean`	`invokeAction(int action)` Invokes an action on this field.
`boolean`	`isDataValid()` Indicates whether the data on the screen is valid.
`boolean`	`isDirty()` Determines if this field is dirty.
`boolean`	`isEditable()` Determines if this field is editable.
`boolean`	`isFocus()` Determines if this field currently has the focus.
`boolean`	`isFocusable()` Determines if this field accepts the focus.
`boolean`	`isMuddy()` Indicates whether this field has recently become muddy and the focus has not yet changed.
`boolean`	`isPasteable()` Determines if this field supports paste operations.
`boolean`	`isSelectable()` Determines if this field supports selection.
`boolean`	`isSelecting()` Determines if this field is in selection mode.
`boolean`	`isSelectionCopyable()` Determines if this field supports copy operations.
`boolean`	`isSelectionCutable()` Determines if this field supports cut operations.
`boolean`	`isSelectionDeleteable()` Determines if this field supports the delete operation.
`boolean`	`isSpellCheckable()` Determines if this field is spell-checkable.
`boolean`	`isStyle(long style)` Determines if this field has all the provided styles.
`boolean`	`isVisible()` Determines whether or not this UI element is visible.
`protected boolean`	`keyChar(char character, int status, int time)` Handles character generation events.
`protected boolean`	`keyControl(char character, int status, int time)` Handles control character generation events.
`protected boolean`	`keyDown(int keycode, int time)` Handles key down events.
`protected boolean`	`keyRepeat(int keycode, int time)` Handles key repeat events.
`protected boolean`	`keyStatus(int keycode, int time)` Handles key status events.
`protected boolean`	`keyUp(int keycode, int time)` Handles key up events.
`protected abstract void`	`layout(int width, int height)` Lays out field contents.
`protected void`	`makeContextMenu(ContextMenu contextMenu)` Builds this field's context menu.
`protected int`	`moveFocus(int amount, int status, int time)` Handles moving the focus within this field.
`protected void`	`moveFocus(int x, int y, int status, int time)` Moves the focus to an exact position within this field.
`protected boolean`	`navigationClick(int status, int time)` Invoked when the navigational action is selected.
`protected boolean`	`navigationMovement(int dx, int dy, int status, int time)` Invoked when a navigational motion occurs.
`protected boolean`	`navigationUnclick(int status, int time)` Invoked when the navigational action is released.
`protected void`	`onDisplay()` Invoked when the screen this field is attached to is pushed onto the display stack.
`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`	`onFocus(int direction)` Invoked when a field receives the focus.
`protected void`	`onMenuDismissed()` Deprecated. Use onMenuDismissed(Menu).
`protected void`	`onMenuDismissed(Menu menu)` Called from `Screen.onMenuDismissed(Menu)` on all the fields and managers that are in focus when the drop-down menu is dismissed (whether it is dismissed by escaping out or by executing a menu item).
`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`	`onUnfocus()` Invoked when a field loses the focus.
`protected void`	`onVisibilityChange(boolean visible)` This method is called when the field's visibility changes.
`protected abstract void`	`paint(Graphics graphics)` Invoked by the framework to redraw a portion of this field.
`boolean`	`paste(Clipboard cb)` Performs a paste operation on this field.
`void`	`select(boolean enable)` Enables or disables selection mode.
`void`	`selectionCopy(Clipboard cb)` Performs a copy operation on this field.
`void`	`selectionCut(Clipboard cb)` Performs a cut operation on this field.
`void`	`selectionDelete()` Performs a delete operation on this field.
`void`	`setBackground(int visual, Background background)` Sets a custom background for a specified visual state in this field and overrides the existing theme background if it exists.
`void`	`setBackground(Background background)` Sets a custom background for this field (normal and focus states) and overrides the existing theme background if it exists.
`void`	`setBorder(int visual, Border border)` Sets a custom border for the specified visual state in this field and overrides the existing theme border if it exists.
`void`	`setBorder(int visual, Border border, boolean updateLayout)` Sets a custom border for the specified visual state in this field and overrides the existing theme border if it exists.
`void`	`setBorder(Border border)` Sets a custom border for this field (normal and focus states) and overrides the existing theme border if it exists.
`void`	`setBorder(Border border, boolean updateLayout)` Sets a custom border for this field (normal and focus states) and overrides the existing theme border if it exists.
`void`	`setChangeListener(FieldChangeListener listener)` Specifies a listener for changes to this field.
`void`	`setCookie(Object cookie)` Sets a cookie object for later retrieval.
`void`	`setDirty(boolean dirty)` Sets the dirty state of the field.
`void`	`setEditable(boolean editable)` Set the editable state of this field.
`protected void`	`setExtent(int width, int height)` Sets this field's extent.
`void`	`setFocus()` Sets the focus to this field.
`void`	`setFocusListener(FocusChangeListener listener)` Specifies a listener for focus changes to this field.
`void`	`setFont(Font font)` Sets the font for this field and updates the display if necessary.
`void`	`setMuddy(boolean muddy)` Sets the muddy state for this field.
`void`	`setNonSpellCheckable(boolean nonSpellCheckable)` Sets the spell-checkable style for this field.
`protected void`	`setPosition(int x, int y)` Places this field within a manager's child region.
`void`	`setVisualState(int visual)` Sets this field's current visual state, which can be subsequently accessed via `Field.getVisualState()`.
`protected boolean`	`touchEvent(TouchEvent message)` Indicates a touch event.
`protected boolean`	`trackwheelClick(int status, int time)` Indicates a trackwheel click event.
`protected boolean`	`trackwheelUnclick(int status, int time)` Indicates a trackwheel release event.
`protected void`	`updateLayout()` Updates layout of field after extent change.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

FIELD_LEFT

public static final long FIELD_LEFT

Field is aligned to the left (style bit).

See Also:: Constant Field Values

FIELD_RIGHT

public static final long FIELD_RIGHT

Field is aligned to the right (style bit).

See Also:: Constant Field Values

FIELD_HCENTER

public static final long FIELD_HCENTER

Field is centered horizontally (style bit).

See Also:: Constant Field Values

FIELD_LEADING

public static final long FIELD_LEADING

Field is aligned to the current locale's start-of-line.

See Also:: Constant Field Values
Since:: BlackBerry API 4.6.0

FIELD_TRAILING

public static final long FIELD_TRAILING

Field is aligned to the current locale's end-of-line.

See Also:: Constant Field Values
Since:: BlackBerry API 4.6.0

FIELD_HALIGN_MASK

protected static final long FIELD_HALIGN_MASK

Bitfield mask of the horizontal alignment style specifier.

See Also:: Constant Field Values

FIELD_VALIGN_MASK

protected static final long FIELD_VALIGN_MASK

Bitfield mask of the vertical alignment style specifier.

See Also:: Constant Field Values

FIELD_TOP

public static final long FIELD_TOP

Field is aligned to the top (style bit).

See Also:: Constant Field Values

FIELD_BOTTOM

public static final long FIELD_BOTTOM

Field is aligned to the bottom (style bit).

See Also:: Constant Field Values

FIELD_VCENTER

public static final long FIELD_VCENTER

Specifies that the field is centered vertically (style bit).

See Also:: Constant Field Values

USE_ALL_WIDTH

public static final long USE_ALL_WIDTH

Field uses all the width given to it by its manager (style bit).

Not all fields accept this style.

See Also:: Constant Field Values

USE_ALL_HEIGHT

public static final long USE_ALL_HEIGHT

Field uses all the height given to it by its manager (style bit).

Not all fields accept this style.

See Also:: Constant Field Values

EDITABLE_MASK

protected static final long EDITABLE_MASK

Field style mask to indicate whether or not the user can change the contents.

Examples:

 (style & EDITABLE_MASK) == 0 // default for field
 or
 (style & EDITABLE_MASK) == EDITABLE
 or
 (style & EDITABLE_MASK) == READONLY

See Also:: Constant Field Values

EDITABLE

public static final long EDITABLE

Field style bit to indicate whether or not the user can change the contents.

Not all fields accept this style.

See Also:: Constant Field Values

READONLY

public static final long READONLY

Field style bit to indicate whether or not the user can change the contents.

Not all fields accept this style.

See Also:: Constant Field Values

SPELLCHECKABLE_MASK

protected static final long SPELLCHECKABLE_MASK

Field style mask to indicate whether spelling check can be run for this field.

See Also:: Constant Field Values
Since:: BlackBerry API 4.3.0

SPELLCHECKABLE

public static final long SPELLCHECKABLE

Field style bit to indicate that field is spellcheckable.

See Also:: Constant Field Values
Since:: BlackBerry API 4.3.0

NON_SPELLCHECKABLE

public static final long NON_SPELLCHECKABLE

Field style bit to indicate that field is not spellcheckable.

See Also:: Constant Field Values
Since:: BlackBerry API 4.3.0

FOCUSABLE_MASK

protected static final long FOCUSABLE_MASK

Field style mask to indicate whether the field allows focus.

Examples:

 (style & FOCUSABLE_MASK) == 0 // default for field
 or
 (style & FOCUSABLE_MASK) == FOCUSABLE
 or
 (style & FOCUSABLE_MASK) == NON_FOCUSABLE

See Also:: Constant Field Values

FOCUSABLE

public static final long FOCUSABLE

Field style bit to indicate whether or not the field is focusable.

See Also:: Constant Field Values

NON_FOCUSABLE

public static final long NON_FOCUSABLE

Field style bit to indicate whether or not the field is non-focusable.

See Also:: Constant Field Values

HIGHLIGHT_FOCUS

public static final int HIGHLIGHT_FOCUS

Highlight bit to indicate focus highlighting.

See Also:: Constant Field Values

HIGHLIGHT_SELECT

public static final int HIGHLIGHT_SELECT

Highlight bit to indicate select highlighting.

See Also:: Constant Field Values

ACTION_INVOKE

public static final int ACTION_INVOKE

Constant to indicate that the default action was invoked.

See Also:: Constant Field Values
Since:: BlackBerry API 4.2.0

STATUS_MOVE_FOCUS_HORIZONTALLY

public static final int STATUS_MOVE_FOCUS_HORIZONTALLY

Focus movement event has a horizontal bias.

See Also:: Constant Field Values
Since:: BlackBerry API 4.2.0

STATUS_MOVE_FOCUS_VERTICALLY

public static final int STATUS_MOVE_FOCUS_VERTICALLY

Focus movement event has a vertical bias.

See Also:: Constant Field Values
Since:: BlackBerry API 4.2.0

AXIS_SEQUENTIAL

public static final int AXIS_SEQUENTIAL

Axis specifier.

See Also:: Constant Field Values
Since:: BlackBerry API 5.0.0

AXIS_HORIZONTAL

public static final int AXIS_HORIZONTAL

Axis specifier.

See Also:: Constant Field Values
Since:: BlackBerry API 5.0.0

AXIS_VERTICAL

public static final int AXIS_VERTICAL

Axis specifier.

See Also:: Constant Field Values
Since:: BlackBerry API 5.0.0

VISUAL_STATE_NORMAL

public static final int VISUAL_STATE_NORMAL

Normal visual state. Refers to no current interaction with field.

See Also:: Field.getVisualState(), Constant Field Values
Since:: BlackBerry API 4.6.0

VISUAL_STATE_ACTIVE

public static final int VISUAL_STATE_ACTIVE

Active visual state. Refers to a pressed interaction with field.

See Also:: Field.getVisualState(), Constant Field Values
Since:: BlackBerry API 4.6.0

VISUAL_STATE_FOCUS

public static final int VISUAL_STATE_FOCUS

Focus visual state. Refers to a highlight interaction with field.

See Also:: Field.getVisualState(), Constant Field Values
Since:: BlackBerry API 4.6.0

VISUAL_STATE_DISABLED

public static final int VISUAL_STATE_DISABLED

Disabled visual state. Refers to a no possible interaction with field.

See Also:: Field.getVisualState(), Constant Field Values
Since:: BlackBerry API 4.6.0

VISUAL_STATE_DISABLED_FOCUS

public static final int VISUAL_STATE_DISABLED_FOCUS

Disabled, but focused visual state. Refers to a highlight, but no other possible interaction with field.

See Also:: Field.getVisualState(), Constant Field Values
Since:: BlackBerry API 4.6.0

Constructor Detail

Field

protected Field()

Constructs a new Field instance with no style attributes.

Field

protected Field(long style)

Constructs a new Field instance with specified style attributes.

Use this constructor to create a field, providing an integer value embodying a variety of basic attributes for the field. For example, to create a field with left and top aligned contents, you would specify

     Field( TOP | LEFT )

This class provides a number of static "field style bits" you can use in this fashion. Custom fields can provide their own style bits to indicate attributes particular to their implementations.

Parameters:: style - Combination of field style bits to specify display attributes.
Throws:: IllegalArgumentException - if style specifies Field.FOCUSABLE_MASK, Field.EDITABLE_MASK, or an undefined style.

Method Detail

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)

Draws the focus indicator for this field.

A field's manager invokes this method after painting the field. The manager initializes the graphics object passed in for drawing with field-local coordinates. It is also assumed that the region is already drawn correctly with the opposing state for the on parameter.

When overriding this method, fields should use Field.drawHighlightRegion(net.rim.device.api.ui.Graphics, int, boolean, int, int, int, int) to render focus and select regions instead of hardcoding the logic.

By default this method invokes Field.drawHighlightRegion(net.rim.device.api.ui.Graphics, int, boolean, int, int, int, int) to render the focus indicator using the rect obtained from Field.getFocusRect(net.rim.device.api.ui.XYRect).

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

drawHighlightRegion

protected final void drawHighlightRegion(Graphics graphics,
                                         int style,
                                         boolean on,
                                         int x,
                                         int y,
                                         int width,
                                         int height)

Draws a highlight indicator for a rectangular region.

The style parameter indicates the type of highlight to draw. Valid styles are Field.HIGHLIGHT_FOCUS, Field.HIGHLIGHT_SELECT and (HIGHLIGHT_FOCUS | HIGHLIGHT_SELECT).

Fields that implement custom focus or selection behavior should use this method to draw highlight regions (instead of hardcoding highlight logic).

The Field.HIGHLIGHT_SELECT style is guaranteed to operate cleanly over a non-rectangular region. That is, it can be used to select a larger region by making multiple calls to this function. Field.HIGHLIGHT_FOCUS does not make this guarantee and should only be called for a single rectangular region.

This method can be used within a Field's paint method to turn on highlighting, but should only be used by the drawFocus framework to turn off highlighting. The method may need to call paint on the field to clear the highlight region.

Parameters:: graphics - Graphics object for drawing the highlight.; style - Style of highlight to render.; on - True if the highlight should be set; otherwise, false.; x - Left side of the highlight region.; y - Top edge of the highlight region.; width - Width of the highlight region.; height - Height of the highlight region.
Throws:: IllegalArgumentException - If style is invalid.; NullPointerException - If graphics is null.

fieldChangeNotify

protected void fieldChangeNotify(int context)

Invoked for this field when a change event occurs.

Custom fields should call this function when their state changes.

The dirty state is cleared if the change was programmatic, and is set (dirtied) if the change was user driven.

Parameters:: context - Information specifying the origin of the change.

focusAdd

protected void focusAdd(boolean draw)

Adds focus to this field.

This field should invoke this method after it has changed its focus region. A call to Field.getFocusRect(net.rim.device.api.ui.XYRect) should return the extent of the new region to receive the focus. The new focus region appears, by scrolling, and the new focus indicator is (optionally) drawn.

This call would normally be paired with a previous Field.focusRemove() call. It may not be necessary to draw the new focus if that part of the field has been invalidated. Note that this method should always be called after a focus region change to ensure that the new region is visible.

Parameters:: draw - Specify true if the new focus should be drawn; otherwise, false.
Throws:: IllegalArgumentException - If the field is a manager (a non-leaf field).

focusRemove

protected void focusRemove()

Removes focus from this field.

This field should call this method when it is changing its focus region. After making this call, this field should call Field.focusAdd(boolean) to ensure the new focus is visible and (optionally) drawn.

If also invoking Field.invalidate(), it may not be necessary to explicitly remove the focus. If the region containing the focus becomes invalid, the paint operation will update the focus correctly.

Throws:: IllegalArgumentException - If the field is a manager (a non-leaf field).

getBorder

public final Border getBorder()

Retrieve the current border object for this field based on current visual state of the field. A border represents the area within a field outside the padding and before the margin. A custom border set via Field.setBorder(Border), Field.setBorder(Border, boolean), Field.setBorder(int, Border), or Field.setBorder(int, Border, boolean) will override the existing theme border. Returns null if no custom or theme border exists.

Returns:: Border object currently displayed, null if one does not exist.
Since:: BlackBerry API 4.6.0

getBorder

public final Border getBorder(int visual)

Retrieve the current border object for this field based on a specified visual state of the field. A border represents the area within a field outside the padding and before the margin. A custom border set via Field.setBorder(Border), Field.setBorder(Border, boolean), Field.setBorder(int, Border), or Field.setBorder(int, Border, boolean) will override the existing theme border. Returns null if no custom or theme border exists.

Parameters:: visual - Visual state associated with background: Field.VISUAL_STATE_NORMAL, Field.VISUAL_STATE_ACTIVE, Field.VISUAL_STATE_FOCUS, Field.VISUAL_STATE_DISABLED, Field.VISUAL_STATE_DISABLED_FOCUS.
Returns:: Border object currently displayed, null if one does not exist.
Throws:: IllegalArgumentException - If visual is an invalid visual state.
Since:: BlackBerry API 4.6.0

getBorder

public final void getBorder(XYEdges edges)

Retrieves the current border edges for this field into the specified XYEdges object. If no border exists, no change is made to edges.

Parameters:: edges - XYEdges objects to be populated with the dimensions of the current border.
Since:: BlackBerry API 4.6.0

getChangeListener

public FieldChangeListener getChangeListener()

Retrieves the current change listener.

Returns:: Current change listener; otherwise, if there is no listener object set, returns null.

getContentHeight

public final int getContentHeight()

Retrieves this field's content height.

Uses getContentRect().height to retrieve this field's width.

Returns:: Height of the field which is modifiable by the field.
Since:: BlackBerry API 4.2.0

getContentLeft

public final int getContentLeft()

Retrieves this field's content's left-most extent.

Uses getContentRect().x to retrieve this field's left-most extent.

Returns:: Left-most extent of the part of the field modifiable by the field's paint() routine.
Since:: BlackBerry API 4.2.0

getContentRect

public final XYRect getContentRect()

Retrieves this field's extent (region occupied in its manager's child region).

Returns:: Object encoding the field's region in its parent manager's coordinates.
Since:: BlackBerry API 4.2.0

getContentRect

public final void getContentRect(XYRect rect)

Retrieves this field's extent (region occupied in its manager's child region).

Since:: BlackBerry API 4.2.0

getContentTop

public final int getContentTop()

Retrieves this field's content's top-most extent.

Uses getContentRect().y to retrieve this field's top-most extent.

Returns:: Top-most extent of the part of the field modifiable by the field's paint() routine.
Since:: BlackBerry API 4.2.0

getContentWidth

public final int getContentWidth()

Retrieves this field's content width.

Uses getContentRect().width to retrieve this field's width.

Returns:: Width of the field which is modifiable by the field.
Since:: BlackBerry API 4.2.0

getContextMenu

public ContextMenu getContextMenu()

Gets the current context menu for this field.

The system invokes this method when passing on a context menu event.

Calling this method will invalidate any prior returns from this method in the current process.

Returns:: Context menu for this field.

getCookie

public final Object getCookie()

Retrieves previously set cookie.

Each field has storage for one cookie object; use this method to retrieve the last one set.

Returns:: The cookie previously set with Field.setCookie(java.lang.Object), or null if no cookie is currently set.

getExtent

public final XYRect getExtent()

Retrieves this field's extent (region occupied in its manager's child region). The extent is the union of the field's drawable area, its area for padding, and its area for borders. The field is not able to draw in its padding or border areas. Only the field's manager, its manager's manager, etc., may draw in the padding and border areas.

Returns:: The extent of the field in its parent Manager's co-ordinate system.

getExtent

public final void getExtent(XYRect extent)

Parameters:: extent - Returns the extent of the field in its parent Manager's co-ordinate system.
Since:: BlackBerry API 4.0.0

getFieldStyle

public final int getFieldStyle()

Retrieves this field's current custom field styles as an integer.

Returns:: Integer representing the combination of the current custom field style bits.

getFocusListener

public FocusChangeListener getFocusListener()

Retrieves the current focus listener.

Returns:: Current focus listener; otherwise, if there is no listener object set, returns null.

getFocusRect

public void getFocusRect(XYRect rect)

Retrieves this field's current focus region.

The framework uses this method to retrieve the current focus region for this field, in field-local coordinates; that is, the region that is made visible by the framework (by scrolling) when the field has the focus.

By default, the focus region is the same as the field's entire extent, in content coordinates.

Parameters:: rect - Object to contain the focus rect for this field in local coordinates.

getFont

public Font getFont()

Retrieves this field's current font.

Returns:: This field's current font. If no font has been specifically set for this field, this method returns Font.getDefault().

getHeight

public final int getHeight()

Retrieves this field's height.

Uses getExtent().height to retrieve this field's height. The height includes borders and padding, but does not include margins.

Returns:: Height of this field.

getIndex

public final int getIndex()

Retrieves position of this field within its manager.

Returns:: The ordinal position of the field within its manager. If the field does not currently belong to a manager, this method returns -1.

getLeafFieldWithFocus

public Field getLeafFieldWithFocus()

Retrieves the leaf (non-manager) field with the focus.

This method is useful if this field is a manager (lays out other contained fields).

Returns:: Leaf field with focus; otherwise, if no contained leaf field has the focus, this method returns null.

getLeft

public final int getLeft()

Retrieves this field's left-offset position.

Uses getExtent().x to retrieve this field's left-offset position within its manager's plane.

Returns:: X offset of the field.

getManager

public final Manager getManager()

Retrieves this field's manager.

Returns:: This field's manager; otherwise, if no manager has been set for this field, this method returns null.

getOriginal

public Field getOriginal()

Retrieves original instance of this field.

Returns:: Original instance of this field.

getPreferredHeight

public int getPreferredHeight()

Retrieves this field's preferred height. Your implementation of getPreferredHeight() should return the height of your custom field if it has any amount of space available.

Managers may make use of this value during layout. Override this method to request a certain height for your field.

Returns:: Preferred height for this field in pixels.

getPreferredWidth

public int getPreferredWidth()

Retrieves this field's preferred width. Your implementation of getPreferredWidth() should return the width of your custom field if it has any amount of space available.

Managers make use of this value during layout. Override this method to request a certain width for your field.

Returns:: Preferred width for this field in pixels.

getScreen

public final Screen getScreen()

Retrieves the screen that currently owns this field.

Returns:: Screen that currently owns this field, null if there isn't one.

getVisualState

public final int getVisualState()

Retrieves this field's current visual state, which can be set via Field.setVisualState(int).

Returns:: Current visual state: Field.VISUAL_STATE_NORMAL, Field.VISUAL_STATE_ACTIVE, Field.VISUAL_STATE_FOCUS, Field.VISUAL_STATE_DISABLED, Field.VISUAL_STATE_DISABLED_FOCUS.
Since:: BlackBerry API 4.6.0

getStyle

public final long getStyle()

Retrieves this field's current style bits.

Returns:: Combination of the current style bits.

getTop

public final int getTop()

Retrieves this field's top-offset position.

Uses getExtent().y to retrieve this field's top-offset position within its manager's plane.

Returns:: Y-offset of this field.

getWidth

public final int getWidth()

Retrieves this field's width.

Uses getExtent().width to retrieve this field's width. The width includes borders and padding, but does not include margins.

Returns:: Width of the field.

invalidate

protected void invalidate()

Marks this entire field invalid.

Use this method to mark an entire field, not just its ContentRect, as invalid, signalling that it requires a repaint.

It is safe to call this function without synchronizing on the event lock.

invalidate

protected void invalidate(int x,
                          int y,
                          int width,
                          int height)

Marks a region of this field as invalid (requiring repainting).

Use this method to mark a region within this field as invalid, signalling that it requires a repaint. You can use this method to optimize the time taken for paint operations on a field.

Note: Any thread can safely invoke this method, and does not require to synchronize on the event lock.

Parameters:: x - X-offset in the field's ContentRect coordinates.; y - Y-offset in the field's ContentRect coordinates.; width - Width of the region.; height - Height of the region.

invalidateAll

protected void invalidateAll(int x,
                             int y,
                             int width,
                             int height)

Marks a region of this field as invalid (requiring repainting).

Use this method to mark a region within this field as invalid, signalling that it requires a repaint. You can use this method to optimize the time taken for paint operations on a field.

Note: Any thread can safely invoke this method, and does not require to synchronize on the event lock.

Parameters:: x - X-offset in the field's non-ContentRect coordinates.; y - Y-offset in the field's non-ContentRect coordinates.; width - Width of the region.; height - Height of the region.
Since:: BlackBerry API 4.2.0

invokeAction

protected boolean invokeAction(int action)

Invokes an action on this field. This method is designed to be overridden by subclasses to perform custom behavior for different actions. The implementation in this class does nothing and returns false.

If action is not a recognized action then this method does nothing and returns false, indicating that the action was not consumed.

Parameters:: action - the action to be performed on this field.
Returns:: true if the action was consumed; false if the action was not consumed.
Since:: BlackBerry API 4.2.0

isDataValid

public boolean isDataValid()

Indicates whether the data on the screen is valid.

Derived classes should override this method for more particular handling.

Returns:: True.
Since:: BlackBerry API 4.2.0

isDirty

public boolean isDirty()

Determines if this field is dirty.

When a field is first created, it is clean. When a field's contents change it becomes muddy (either through user changes that prompt change events, or by invoking Field.setMuddy(boolean)). When the user moves the focus, then the field becomes not muddy but is still dirty.

Returns:: True if the field is dirty; otherwise, false.
See Also:: Field.isMuddy(), Field.setDirty(boolean)

isEditable

public boolean isEditable()

Determines if this field is editable.

Returns:: True if the field can be edited; otherwise, false.

isFocus

public boolean isFocus()

Determines if this field currently has the focus.

Returns:: True if this field has the focus; otherwise, false.
Since:: BlackBerry API 4.2.0

isFocusable

public boolean isFocusable()

Determines if this field accepts the focus.

By default, this method checks the field style to determine whether this field is Field.FOCUSABLE.

Returns:: True if this field can accept the focus; otherwise, false.

isMuddy

public boolean isMuddy()

Indicates whether this field has recently become muddy and the focus has not yet changed.

When a field is first created, it is clean. When a field's contents change it becomes muddy (either through user changes that prompt change events, or by invoking Field.setMuddy(boolean)). However, when the user moves the focus then the field becomes not muddy but is still dirty.

Returns:: True if the field is muddy; otherwise, false.
See Also:: Field.isDirty(), Field.setMuddy(boolean)

isPasteable

public boolean isPasteable()

Determines if this field supports paste operations.

By default, this method returns false; custom fields that support cut operations must override this method.

Returns:: True if the field supports paste; otherwise, false.

isSelectable

public boolean isSelectable()

Determines if this field supports selection.

By default, this method returns false; custom fields that support selection must override this method.

Returns:: True if this field supports selection; otherwise, false.

isSelecting

public boolean isSelecting()

Determines if this field is in selection mode.

By default, this method returns false; custom fields that support selection mode reporting must override this method.

Returns:: True if this field is currently in selection mode; otherwise, false.
See Also:: Field.select(boolean)

isSelectionCopyable

public boolean isSelectionCopyable()

Determines if this field supports copy operations.

By default, this method returns false; custom fields that support copy operations must override this method.

Returns:: True if this field supports copy; otherwise, false.

isSelectionCutable

public final boolean isSelectionCutable()

Determines if this field supports cut operations.

Custom fields do not have to override this method as it can be controlled by overriding the isSelectionDeletable() and isSelectionCopyable() methods.

Returns:: True if the selection is both copyable and deletable; otherwise returns false.

isSelectionDeleteable

public boolean isSelectionDeleteable()

Determines if this field supports the delete operation.

By default, this method returns false; custom fields that support delete operations must override this method.

Returns:: True if this field supports delete; otherwise, false.

isSpellCheckable

public boolean isSpellCheckable()

Determines if this field is spell-checkable. Note that just because a component returns true from this method does not mean that it can be spell checked. If a field is marked as not editable, or if the field has an unsupported TextFilter, the field will not be spell-checked.

Returns:: True if this field is spell-checkable
Since:: BlackBerry API 4.3.0

isStyle

public final boolean isStyle(long style)

Determines if this field has all the provided styles.

Parameters:: style - Style(s) to check.
Returns:: True if this field's styles exactly matched provided style bits.
Since:: BlackBerry API 4.0.0

isVisible

public final boolean isVisible()

Determines whether or not this UI element is visible.

This method returns true if the UI element is potentially visible. The application must be foreground and the screen must be visible.

However, this method might indicate that a screen or field is visible when it is not.

Returns:: The visibility state of the field or screen. true if the element is visible.
Since:: BlackBerry API 3.6.0

keyChar

protected boolean keyChar(char character,
                          int status,
                          int time)

Handles character generation events.

This field's manager invokes this method to send this field a character event.

Special keystroke handling code should be implemented in the Field keyDown method. However, this code checks for cut, copy, or paste keystrokes and dispatches to the appropriate field.

While selection mode is on, ESC cancels selection, and SHIFT+DEL cuts selection.

Parameters:: character - Character generated.; status - Modifier key status. See KeypadListener.; time - Number of milliseconds since the device was turned on.
Returns:: True if this method consumed the event; otherwise, false.

keyControl

protected boolean keyControl(char character,
                             int status,
                             int time)

Handles control character generation events.

This field's manager invokes this method to send this field a control character event.

Parameters:: character - Character generated.; status - Modifier key status. See KeypadListener.; time - Number of milliseconds since the device was turned on.
Returns:: True if this method consumed the event; otherwise, false.

keyDown

protected boolean keyDown(int keycode,
                          int time)

Handles key down events.

By default, this method returns false; custom fields that specially handle key down events must override this method.

Parameters:: keycode - Code of key pressed.; time - Number of milliseconds since the device was turned on.
Returns:: False (classes that extend Field must override this method to provide specific handling).

keyRepeat

protected boolean keyRepeat(int keycode,
                            int time)

Handles key repeat events.

By default, this method returns false; custom fields that specially handle key repeat events must override this method.

Parameters:: keycode - Code of key repeated.; time - Number of milliseconds since the device was turned on.
Returns:: False (classes that extend Field must override this method to provide specific handling).

keyStatus

protected boolean keyStatus(int keycode,
                            int time)

Handles key status events.

By default, this method returns false; custom fields that specially handle key status events must override this method.

Parameters:: keycode - Code of status key.; time - Number of milliseconds since the device was turned on.
Returns:: False (classes that extend Field must override this method to provide specific handling).

keyUp

protected boolean keyUp(int keycode,
                        int time)

Handles key up events.

By default, this method returns false; custom fields that specially handle key up events must override this method.

Parameters:: keycode - Code of key released.; time - Number of milliseconds since the device was turned on.
Returns:: False (classes that extend Field must override this method to provide specific handling).

layout

protected abstract void layout(int width,
                               int height)

Lays out field contents.

This method is abstract; any class that extends Field must implement this method appropriate to its needs.

Invoked after the screen has been created, or when system parameters change (for example, after a system font change). Field.getExtent() will return a valid value after this method is invoked. Implementations of this method must invoke Field.setExtent(int, int) with the size used by the field.

During this call, Field.setExtent(int, int) must be called with parameters such that both width and height are between 0 and the values passed into this function for the Manager to be able to position this Field properly.

Fields may cache system attributes for efficiency (such as the current system font); however, they cannot depend on these attributes remaining unchanged. When one of these attributes changes, a message event is sent to that effect: in these cases, this method refetch and cache these attributes.

Parameters:: width - Amount of available horizontal space.; height - Amount of available vertical space.

makeContextMenu

protected void makeContextMenu(ContextMenu contextMenu)

Builds this field's context menu.

Field.getContextMenu() invokes this method to construct this field's context menu.

Parameters:: contextMenu - Context menu to build.
See Also:: ContextMenu

onMenuDismissed

protected void onMenuDismissed(Menu menu)

Called from Screen.onMenuDismissed(Menu) on all the fields and managers that are in focus when the drop-down menu is dismissed (whether it is dismissed by escaping out or by executing a menu item).

Parameters:: menu - Menu to be dismissed
Since:: BlackBerry API 4.2.0

onMenuDismissed

protected void onMenuDismissed()

Deprecated. Use onMenuDismissed(Menu).

Called on all the fields and managers that are in focus when the drop-down menu is dismissed (whether it is dismissed by escaping out or by executing a menu item).

Since:: BlackBerry API 4.0.2

moveFocus

protected int moveFocus(int amount,
                        int status,
                        int time)

Handles moving the focus within this field.

This method is called by the framework only when the field already has focus.

By default, this method returns the amount parameter provided to it; custom fields must override this method to handle focus movement events.

Prior to invoking this method, the framework invokes Field.focusRemove(). After invoking this method, the framework invokes Field.focusAdd(boolean).

This method also clears this field's muddy state.

Parameters:: amount - Number of positions to move, positive means down, negative means up.; status - Modifier key status applied when the trackwheel roll occurred (combination of applicable modifier keycode values from KeypadListener).; time - Number of milliseconds since the device was turned on.
Returns:: Remaining scroll amount not used up, with the same sign.

moveFocus

protected void moveFocus(int x,
                         int y,
                         int status,
                         int time)

Moves the focus to an exact position within this field.

This method is called by the framework only when the field already has focus.

Parameters:: x - Horizontal axis (field local) of new focus position.; y - Veritcal axis (field local) of new focus position.; status - Key modifiers applicable to the focus movement.; time - Number of milliseconds since the device was turned on.

onFocus

protected void onFocus(int direction)

Invoked when a field receives the focus.

The method will not be invoked if this field already has focus. Also, it will not be invoked if this field returns false from Field.isFocusable().

Managers should find a child field that accepts focus and cascade this method's call to it.

The direction value indicates how the focus came to enter the field:

1 indicates that the focus came from the previous field.
-1 indicates that the focus came from the following field.
0 indicates that the focus was set directly, (that is, not by rolling the trackwheel)

Parameters:: direction - Indicates from which direction the focus enters the field.

onUnfocus

protected void onUnfocus()

Invoked when a field loses the focus.

The method will not be invoked if this field does not already have the focus.

By default, this method clears the muddy bit and removes selection. If your custom field requires special handling upon losing the focus, you must override this method. Don't forget to call this method on the parent though, or the muddy bit won't get cleared.

paint

protected abstract void paint(Graphics graphics)

Invoked by the framework to redraw a portion of this field.

This is an abstract method; any class that extends Field must implement this method appropriate to its needs.

A field's manager invokes this method when an area of this field has been marked as invalid. All painting should be done in field-local coordinates (for example, 0,0 is the top left corner of the field's pane).

The clipping rectangle is available (in local coordinates) through Graphics.getClippingRect(). You can use this rectangle to determine the minimal amount of drawing required to satisfy the paint request. Large controls should make use of this for more efficient painting, particularly during scroll operations.

Preconditions for the paint method
Routines that invoke this method on a field ensure that this.getFont() == graphics.getFont() and that the appropriate clipping rect and transformation stack are set up, so that this method draws on the appropriate area of this field.

Should you implement a layout manager (for example) of your own, be aware that you must ensure these conditions are met before invoking this method in child Fields.

Parameters:: graphics - Graphics context for drawing in this field.

getBackground

public final Background getBackground()

Retrieve the current background object based on current visual state of the field. A custom background set via Field.setBackground(Background), {@link #setBackground(int, Background) will override the existing theme background. Returns null if no custom or theme background exists.

Returns:: Background object currently displayed, null if one does not exist.
Since:: BlackBerry API 4.6.0

getBackground

public final Background getBackground(int visual)

Retrieve the current background object based on a specified visual state of the field. A custom background set via Field.setBackground(Background), {@link #setBackground(int, Background) will override the existing theme background. Returns null if no custom or theme background exists.

Parameters:: visual - Visual state associated with background: Field.VISUAL_STATE_NORMAL, Field.VISUAL_STATE_ACTIVE, Field.VISUAL_STATE_FOCUS, Field.VISUAL_STATE_DISABLED, Field.VISUAL_STATE_DISABLED_FOCUS.
Returns:: Background object currently displayed, null if one does not exist.
Throws:: IllegalArgumentException - If visual is an invalid visual state.
Since:: BlackBerry API 4.6.0

setBackground

public final void setBackground(Background background)

Sets a custom background for this field (normal and focus states) and overrides the existing theme background if it exists. Setting the background to null will reset it back to the default theme background.

Parameters:: background - Background object display, null to use default theme background.
Since:: BlackBerry API 4.6.0

setBackground

public final void setBackground(int visual,
                                Background background)

Sets a custom background for a specified visual state in this field and overrides the existing theme background if it exists. Setting the background to null will reset it back to the default theme background.

Parameters:: background - Background object display, null to use default theme background.; visual - Visual state associated with background: Field.VISUAL_STATE_NORMAL, Field.VISUAL_STATE_ACTIVE, Field.VISUAL_STATE_FOCUS, Field.VISUAL_STATE_DISABLED, Field.VISUAL_STATE_DISABLED_FOCUS.
Throws:: IllegalArgumentException - If visual is an invalid visual state.
Since:: BlackBerry API 4.6.0

paste

public boolean paste(Clipboard cb)

Performs a paste operation on this field.

By default, this method returns false; custom fields that support paste operations must override this method.

Parameters:: cb - Clipboard object containing data to paste.
Returns:: True if the operation was successful; otherwise, false.

setExtent

protected final void setExtent(int width,
                               int height)

Sets this field's extent.

The field calls this method during layout to set its extent (height and width).

Parameters:: width - Width of the field.; height - Height of the field.

setFont

public void setFont(Font font)

Sets the font for this field and updates the display if necessary.

Parameters:: font - New font for this field.

setPosition

protected final void setPosition(int x,
                                 int y)

Places this field within a manager's child region.

This field's manager calls this method during layout to place this field within the manager's plane.

Parameters:: x - Offset of the left of the field in its manager.; y - Offset of the top of the field in its manager.

updateLayout

protected final void updateLayout()

Updates layout of field after extent change.

Invoke this method when a change is made to a field that requires its extent to change. If the field is currently laid out in a screen, the appropriate updates are made to reflect the new field size.

select

public void select(boolean enable)
            throws IllegalStateException

Enables or disables selection mode.

This method is called to indicate to a Field whether it should consider itself to be in the process of selecting. Custom fields that support select mode must override this method.

Parameters:: enable - True to enable selection mode, false to disable it.
Throws:: IllegalStateException - If this field is not selectable.

selectionCopy

public void selectionCopy(Clipboard cb)
                   throws IllegalStateException

Performs a copy operation on this field.

By default, this method returns false; custom fields that support copy operations must override this method.

Parameters:: cb - Clipboard object to use.
Throws:: IllegalStateException - If invalid clipboard object.

selectionCut

public void selectionCut(Clipboard cb)
                  throws IllegalStateException

Performs a cut operation on this field.

By default, this method returns false; custom fields that support cut operations must override this method.

Parameters:: cb - Clipboard object to use.
Throws:: IllegalStateException - If invalid clipboard object.

selectionDelete

public void selectionDelete()

Performs a delete operation on this field.

By default, this method does nothing; custom fields that support deletion operations must override this method.

See Also:: Field.isSelectionDeleteable(), Field.selectionCut(net.rim.device.api.system.Clipboard)

setBorder

public void setBorder(Border border)

Sets a custom border for this field (normal and focus states) and overrides the existing theme border if it exists. The border is the area within a field outside the padding and before the margin. Setting the background to null will reset it back to the default theme border. Note that this field's layout is automatically updated.

Parameters:: border - Border object to display, null to use default theme border.
Since:: BlackBerry API 4.6.0

setBorder

public void setBorder(Border border,
                      boolean updateLayout)

Parameters:: border - Border object to display, null to use default theme border.; updateLayout - Flag to indicate whether to update the field's layout.
Since:: BlackBerry API 4.6.0

setBorder

public void setBorder(int visual,
                      Border border)

Sets a custom border for the specified visual state in this field and overrides the existing theme border if it exists. The border is the area within a field outside the padding and before the margin. Setting the background to null will reset it back to the default theme border. Note that this field's layout is automatically updated.

Parameters:: visual - Visual state associated with background: Field.VISUAL_STATE_NORMAL, Field.VISUAL_STATE_ACTIVE, Field.VISUAL_STATE_FOCUS, Field.VISUAL_STATE_DISABLED, Field.VISUAL_STATE_DISABLED_FOCUS.; border - Border object to display, null to use default theme border.
Throws:: IllegalArgumentException - If visual is an invalid visual state.
Since:: BlackBerry API 4.6.0

setBorder

public void setBorder(int visual,
                      Border border,
                      boolean updateLayout)

Setting the border to null will reset it back to the default theme border. Additionally, if the existing border has a background and if that background has been set in the custom theme attribute set, then the background in the custom theme attribute set is also reset to null.

Parameters:: visual - Visual state associated with background: Field.VISUAL_STATE_NORMAL, Field.VISUAL_STATE_ACTIVE, Field.VISUAL_STATE_FOCUS, Field.VISUAL_STATE_DISABLED, Field.VISUAL_STATE_DISABLED_FOCUS.; border - Border object to display, null to use default theme border.; updateLayout - Flag to indicate whether to update the field's layout.
Throws:: IllegalArgumentExsetThemeAttributeSetception - If visual is an invalid visual state.
Since:: BlackBerry API 4.6.0

setChangeListener

public void setChangeListener(FieldChangeListener listener)

Specifies a listener for changes to this field.

Note that each field notifies its listener only of its own change events: managers do not notify the listener for changes to its child fields. However, groups of fields can use the same field listener object--each one must register that object as its listener.

Each field can have only one change listener object. If you want to provide a new change listener for a field, you must first invoke this method with null.

Parameters:: listener - The object to listen for field changes.
Throws:: IllegalStateException - When there is already a listener set and provided parameter is not null.

setCookie

public final void setCookie(Object cookie)

Sets a cookie object for later retrieval.

A cookie is an arbitrary object stored in association with a field. Applications may use it to store extra information about this field.

Use Field.getCookie() to retrieve this field's cookie.

Parameters:: cookie - Object associated with this field.

setDirty

public void setDirty(boolean dirty)

Sets the dirty state of the field.

Invoke this method to indicate either that a field's contents have changed (passing true), or that a field's changes have been dealt with and is no longer dirty (passing false).

Parameters:: dirty - Specify true if the field is dirty; otherwise, specify false to set the field to clean.
See Also:: Field.isDirty(), Field.setMuddy(boolean)

setEditable

public void setEditable(boolean editable)

Set the editable state of this field.

This method lets you change the style of this field by either adding, or removing, the Field.EDITABLE style.

Parameters:: editable - If True, make this field editable; otherwise, make this field non-editable.

setFocus

public void setFocus()

Sets the focus to this field.

This method removes the focus from the field that currently has it (if any) and moves it to this field. The screen performs any necessary scrolling to ensure the new focus region is visible.

If this field is a manager, this method gives the focus to this manager's first field.

If this field already has the focus, invoking this method has no effect.

Throws:: IllegalStateException - If the field is not attached to a screen.

setFocusListener

public void setFocusListener(FocusChangeListener listener)

Specifies a listener for focus changes to this field.

Each field can have only one focus listener object. If you want to provide a new focus listener for a field, you must first invoke this method with null remove the old listener.

Parameters:: listener - The object to listen for focus changes.
Throws:: IllegalStateException - When there is already a listener set and provided parameter is not null.

setMuddy

public void setMuddy(boolean muddy)

Sets the muddy state for this field.

Note: If a field is muddy, then it must also be dirty. Therefore calling setMuddy(true) immediately followed by setMuddy(false) results in a field that is dirty, but not still muddy.

Parameters:: muddy - True if this field should be made muddy and dirty; false to un-muddy this field.
See Also:: Field.isMuddy(), Field.setDirty(boolean)

setNonSpellCheckable

public void setNonSpellCheckable(boolean nonSpellCheckable)

Sets the spell-checkable style for this field.

Any external module (like model or application) can use this method to assign this field with the spellcheckable style.

Parameters:: nonSpellCheckable - If false make this field Field.SPELLCHECKABLE; otherwise, make it Field.NON_SPELLCHECKABLE.
See Also:: Field.isSpellCheckable()
Since:: BlackBerry API 4.3.0

setVisualState

public final void setVisualState(int visual)

Sets this field's current visual state, which can be subsequently accessed via Field.getVisualState().

Parameters:: visual - One of the following visual states: Field.VISUAL_STATE_NORMAL, Field.VISUAL_STATE_ACTIVE, Field.VISUAL_STATE_FOCUS, Field.VISUAL_STATE_DISABLED, Field.VISUAL_STATE_DISABLED_FOCUS.
Since:: BlackBerry API 4.6.0

touchEvent

protected boolean touchEvent(TouchEvent message)

Indicates a touch event.

Parameters:: message - TouchEvent object containing various input parameters including the event type and touch coordinates.
Returns:: True if this method consumed the event; otherwise, false.
Since:: BlackBerry API 4.7.0

navigationClick

protected boolean navigationClick(int status,
                                  int time)

Invoked when the navigational action is selected.

The system invokes this method when passing on a navigational click event.

The ALT-click combination will enter selection mode, or if in selection mode will copy.

The source of the navigation event can be determined by checking the KeypadListener.STATUS_TRACKWHEEL and KeypadListener.STATUS_FOUR_WAY bits in the status parameter; exactly one of them will be set.

Parameters:: status - Bitfield of values defined by KeypadListener.; time - Number of milliseconds since the device was turned on.
Returns:: True if this method consumed the event; otherwise, false.
Since:: BlackBerry API 4.2.0

navigationUnclick

protected boolean navigationUnclick(int status,
                                    int time)

Invoked when the navigational action is released.

The system invokes this method when passing on a navigational release event.

Parameters:: status - Bitfield of values defined by KeypadListener.; time - Number of milliseconds since the device was turned on.
Returns:: False (classes that extend Field must override this method to provide specific handling).
Since:: BlackBerry API 4.2.0

navigationMovement

protected boolean navigationMovement(int dx,
                                     int dy,
                                     int status,
                                     int time)

Invoked when a navigational motion occurs.

Parameters:: dx - Magnitude of navigational motion: negative for a move left and postive for a move right.; dy - Magnitude of navigational motion: negative for an upwards move, and positive for a downwards move.; status - Bitfield of values defined by KeypadListener.; time - Number of milliseconds since the device was turned on.
Returns:: False (classes that extend Field must override this method to provide specific handling).
Since:: BlackBerry API 4.2.0

trackwheelClick

protected boolean trackwheelClick(int status,
                                  int time)

Indicates a trackwheel click event.

The system invokes this method when passing on a trackwheel click event.

The ALT-click combination will enter selection mode, or if in selection mode will copy.

Parameters:: status - Bitfield of values defined by KeypadListener.; time - Number of milliseconds since the device was turned on.
Returns:: True if this method consumed the event; otherwise, false.

trackwheelUnclick

protected boolean trackwheelUnclick(int status,
                                    int time)

Indicates a trackwheel release event.

The system invokes this method when passing on a trackwheel release event.

Parameters:: status - Bitfield of values defined by KeypadListener.; time - Number of milliseconds since the device was turned on.
Returns:: False (classes that extend Field must override this method to provide specific handling).

onVisibilityChange

protected void onVisibilityChange(boolean visible)

This method is called when the field's visibility changes.

Whenever an event occurs that changes the value returned from 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 Field.isVisible(), for example, this method may be called with visible as false, but isVisible still returns true.

Parameters:: visible - True if the field has just become visible; otherwise, false.
See Also:: Screen.onDisplay(), Screen.onExposed(), Screen.onObscured(), Screen.onUiEngineAttached(boolean)
Since:: BlackBerry API 3.6.0

onDisplay

protected void onDisplay()

Invoked when the screen this field is attached to is pushed onto the display stack.

This method is invoked by the system after the screen is pushed onto the stack and layout has been done, but before any painting occurs.

The complementing callback is #onUiEngineAttached.

Since:: BlackBerry API 4.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().

Since:: BlackBerry API 4.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().

Since:: BlackBerry API 4.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().

Since:: BlackBerry API 4.0.0

getAccessibleContext

public AccessibleContext getAccessibleContext()

Returns accessible representation of the field for a screen reader.

Returns:: AccessibleContext instance
Since:: BlackBerry API 4.6.1

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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.

net.rim.device.api.ui Class Field

FIELD_LEFT

FIELD_RIGHT

FIELD_HCENTER

FIELD_LEADING

FIELD_TRAILING

FIELD_HALIGN_MASK

FIELD_VALIGN_MASK

FIELD_TOP

FIELD_BOTTOM

FIELD_VCENTER

USE_ALL_WIDTH

USE_ALL_HEIGHT

EDITABLE_MASK

EDITABLE

READONLY

SPELLCHECKABLE_MASK

SPELLCHECKABLE

NON_SPELLCHECKABLE

FOCUSABLE_MASK

FOCUSABLE

NON_FOCUSABLE

HIGHLIGHT_FOCUS

HIGHLIGHT_SELECT

ACTION_INVOKE

STATUS_MOVE_FOCUS_HORIZONTALLY

STATUS_MOVE_FOCUS_VERTICALLY

AXIS_SEQUENTIAL

AXIS_HORIZONTAL

AXIS_VERTICAL

VISUAL_STATE_NORMAL

VISUAL_STATE_ACTIVE

VISUAL_STATE_FOCUS

VISUAL_STATE_DISABLED

VISUAL_STATE_DISABLED_FOCUS

Field

Field

drawFocus

drawHighlightRegion

fieldChangeNotify

focusAdd

focusRemove

getBorder

getBorder

getBorder

getChangeListener

getContentHeight

getContentLeft

getContentRect

getContentRect

getContentTop

getContentWidth

getContextMenu

getCookie

getExtent

getExtent

getFieldStyle

getFocusListener

getFocusRect

getFont

getHeight

getIndex

getLeafFieldWithFocus

getLeft

getManager

getOriginal

getPreferredHeight

getPreferredWidth

getScreen

getVisualState

getStyle

getTop

getWidth

invalidate

invalidate

invalidateAll

invokeAction

isDataValid

isDirty

isEditable

net.rim.device.api.ui
Class Field