Field (BlackBerry JDE 7.1.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:: ShortcutIconField, ViewfinderOverlay.VideoControlOverlayField, MapField, MapField, GLField, VGField, ScrollView, BitmapField, ButtonField, CheckboxField, ChoiceField, DateField, GaugeField, LabelField, ListField, NullField, RadioButtonField, SeparatorField, SpinBoxField, TextField, TextFieldBase, TreeField, ActivityImageField, ProgressBarField, PictureScrollField, ToolbarButtonField

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 the layout. The manager, rather than the contained fields, completely handles scrolling.

You can't instantiate Field directly. Instead, 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 Field.layout(int, int) and Field.paint(net.rim.device.api.ui.Graphics) abstract methods to provide the behavior needed by your field.

You should also override the Field.getPreferredWidth() and Field.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 Field.isFocusable() to return true.

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

The framework invokes Field.moveFocus(int, int, int) 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. If the user does not press the ALT key during a trackwheel event, the choice field delegates to moveFocus() on the base class.

You can change the appearance of the default focus indicator by overriding Field.drawFocus(net.rim.device.api.ui.Graphics, boolean).

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 Field.invalidate() to force the entire field to repaint itself. Use Field.invalidate(int, int, int, int) 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` 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 boolean`	`cursorClick(int x, int y, int status, int time)` Indicates a cursor click event.
`protected boolean`	`cursorUnclick(int x, int y, int status, int time)` Indicates a cursor unclick event.
`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()` Retrieves the current background object based on current visual state of the field.
`Background`	`getBackground(int visual)` Retrieves the current background object based on a specified visual state of the field.
`Border`	`getBorder()` Retrieves the current border object for this field based on the current visual state of the field.
`Border`	`getBorder(int visual)` Retrieves 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 and places the dimensions into the specified `XYEdges` object.
`FieldChangeListener`	`getChangeListener()` Retrieves the current change listener.
`CommandItemProvider`	`getCommandItemProvider()` Gets the command item provider.
`int`	`getContentHeight()` Retrieves the height of this field's content.
`int`	`getContentLeft()` Retrieves the left-most extent of this field's content.
`XYRect`	`getContentRect()` Retrieves the region that is occupied by this field's content and padding within the coordinate space of its manager.
`void`	`getContentRect(XYRect rect)` Retrieves the region that is occupied by this field's content and padding within the coordinate space of its manager.
`int`	`getContentTop()` Retrieves the top-most extent of this field's content.
`int`	`getContentWidth()` Retrieves this field's content width.
`ContextMenu`	`getContextMenu()` Gets this field's current context menu.
`Object`	`getCookie()` Retrieves the previously set cookie.
`XYRect`	`getExtent()` Retrieves this field's extent (the region occupied in its manager's child region).
`void`	`getExtent(XYRect extent)` Retrieves this field's extent (the 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.
`void`	`getMargin(XYEdges margin)` Retrieves the margin outer-coordinates of this field.
`int`	`getMarginBottom()` Retrieves the bottom-edge coordinates of this field's margin.
`int`	`getMarginLeft()` Retrieves the left-most coordinates of this field's margin.
`int`	`getMarginRight()` Retrieves the right-most coordinates of this field's margin.
`int`	`getMarginTop()` Retrieves the top-most coordinates of the margin.
`Field`	`getOriginal()` Retrieves original instance of this field.
`void`	`getPadding(XYEdges padding)` Retrieves the coordinates of this field's padding.
`int`	`getPaddingBottom()` Retrieves the bottom-edge coordinates of this field's padding.
`int`	`getPaddingLeft()` Retrieves the left-most coordinate of the padding.
`int`	`getPaddingRight()` Retrieves the right-most padding coordinate.
`int`	`getPaddingTop()` Retrieves the top-most padding coordinate.
`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`	`getTextFillColor()` Retrieves the current text fill color.
`int`	`getTextStrokeColor()` Retrieves the current text stroke color.
`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`	`isEnabled()` Determines if this field is enabled.
`boolean`	`isFocus()` Determines if this field currently has the focus.
`boolean`	`isFocusable()` Determines if this field accepts the focus.
`boolean`	`isLeftToRight()` Indicates whether this field's text should be left-to-right.
`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.
`protected boolean`	`isScrollCopyable()` Indicates whether a field may scroll by copying paintable regions.
`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()` Deprecated. Use #onUiEngineAttached.
`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()` Deprecated. Use #onUiEngineAttached.
`protected void`	`onUnfocus()` Invoked when a field loses the focus.
`protected void`	`onVisibilityChange(boolean visible)` 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`	`setCommandItemProvider(CommandItemProvider commandItemProvider)` Sets this field as a command item provider.
`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)` Sets the editable state of this field.
`void`	`setEnabled(boolean enabled)` Sets this field to be enabled or disabled.
`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`	`setFont(Font font, boolean layout)` Sets the font for this field and updates the display if necessary.
`void`	`setMargin(int top, int right, int bottom, int left)` Sets the margin for this field.
`void`	`setMargin(XYEdges margin)` Sets the margin for this field.
`void`	`setMuddy(boolean muddy)` Sets the muddy state for this field.
`void`	`setNonSpellCheckable(boolean nonSpellCheckable)` Sets the spell-checkable style for this field.
`void`	`setPadding(int top, int right, int bottom, int left)` Sets the padding for this field.
`void`	`setPadding(XYEdges padding)` Sets the padding 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

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 6.0.0

AXIS_HORIZONTAL

public static final int AXIS_HORIZONTAL

Axis specifier.

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

AXIS_VERTICAL

public static final int AXIS_VERTICAL

Axis specifier.

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

VISUAL_STATE_NORMAL

public static final int VISUAL_STATE_NORMAL

Normal visual state. There is no current interaction with the 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. The user is interacting with the 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. The field has focus (is highlighted).

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. There is no possible interaction with the 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. The field is highlighted, but there is no other possible interaction with the 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 that are specific to their implementations.

Parameters:: style - A 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 XYRect obtained from Field.getFocusRect(net.rim.device.api.ui.XYRect).

Parameters:: graphics - The graphics context for drawing the focus.; on - If true the focus should be set, if false the focus should not be set.

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 the Field.paint(net.rim.device.api.ui.Graphics) method of a Field 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 - The graphics object for drawing the highlight.; style - The style of highlight to render.; on - If true the highlight should be set, if false the highlight should not be set.; x - The left side of the highlight region.; y - The top edge of the highlight region.; width - The width of the highlight region.; height - The 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 - If true the new focus should be drawn, if false the new focus should not be drawn.
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()

Retrieves the current border object for this field based on the current visual state of the field.

A border represents the area within a field outside the padding and inside 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. This method returns null if no custom or theme border exists.

Returns:: The border object that is currently displayed, or null if one does not exist.
Since:: BlackBerry API 4.6.0

getBorder

public final Border getBorder(int visual)

Retrieves the current border object for this field based on a specified visual state of the field.

Parameters:: visual - The visual state associated with the background: Field.VISUAL_STATE_NORMAL, Field.VISUAL_STATE_ACTIVE, Field.VISUAL_STATE_FOCUS, Field.VISUAL_STATE_DISABLED, or Field.VISUAL_STATE_DISABLED_FOCUS.
Returns:: The border object that is currently displayed, or 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 and places the dimensions into the specified XYEdges object. If no border exists, no change is made to the specified XYEdges object.

Parameters:: edges - The XYEdges object 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:: The current change listener, or null if there is no listener object set.

getContentHeight

public final int getContentHeight()

Retrieves the height of this field's content.

This method uses getContentRect().height to retrieve the height of the content in this field.

Returns:: The height of the field that is modifiable by this field's paint() method.
Since:: BlackBerry API 4.2.0

getContentLeft

public final int getContentLeft()

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

This method uses getContentRect().x to retrieve this field's left-most extent.

Returns:: The left-most extent of the part of the field that is modifiable by this field's paint() method.
Since:: BlackBerry API 4.2.0

getContentRect

public final XYRect getContentRect()

Retrieves the region that is occupied by this field's content and padding within the coordinate space of its manager. This is the region for which the field has control of its rendering. This region does not include the border or margin for this field.

Returns:: An object that represents the field's region in its parent manager's coordinates.
Since:: BlackBerry API 4.2.0

getContentRect

public final void getContentRect(XYRect rect)

Parameters:: rect - The XYRect object to be populated with the content parameters of this field.
Since:: BlackBerry API 4.2.0

getContentTop

public final int getContentTop()

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

This method uses getContentRect().y to retrieve this field's top-most extent.

Returns:: The top-most extent of the part of the field that is modifiable by the field's paint method.
Since:: BlackBerry API 4.2.0

getContentWidth

public final int getContentWidth()

Retrieves this field's content width.

This method uses getContentRect().width to retrieve this field's width.

Returns:: The width of the field that is modifiable by the field.
Since:: BlackBerry API 4.2.0

getContextMenu

public ContextMenu getContextMenu()

Gets this field's current context menu.

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

Calling this method will invalidate any ContextMenu objects that were returned previously from this method in the current process.

Returns:: The context menu for this field.

getCookie

public final Object getCookie()

Retrieves the previously set cookie.

Each field has storage for one cookie object. Use this method to retrieve the last one that was set.

Returns:: The cookie that was 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 (the 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 - An XYRect object to populate with 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:: An integer representing the combination of the current custom field style bits.

getFocusListener

public FocusChangeListener getFocusListener()

Retrieves the current focus listener.

Returns:: The current focus listener, or null if there is no listener object set.

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 - The object to contain the focus region 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().

getTextStrokeColor

public int getTextStrokeColor()

Retrieves the current text stroke color.

Note: Color is inherited from the theme or parent field if available.

Returns:: The current text stroke color in the form 0x00RRGGBB.
Since:: BlackBerry API 7.0.0

getTextFillColor

public int getTextFillColor()

Retrieves the current text fill color.

Note: Color is inherited from the theme or parent Field if available.

Returns:: The current text fill color in the form 0x00RRGGBB.
Since:: BlackBerry API 7.0.0

getHeight

public final int getHeight()

Retrieves this field's height.

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

Returns:: The 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:: The leaf field with focus, or null if no contained leaf field has the focus.

getLeft

public final int getLeft()

Retrieves this field's left-offset position.

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

Returns:: The left-offset position of the field.

getMargin

public final void getMargin(XYEdges margin)

Retrieves the margin outer-coordinates of this field.

Parameters:: margin - An XYEdges object to receive the margin coordinates.
Since:: BlackBerry API 6.0.0

getMarginBottom

public final int getMarginBottom()

Retrieves the bottom-edge coordinates of this field's margin.

Returns:: The bottom-edge coordinates of the margin.
Since:: BlackBerry API 6.0.0

getMarginLeft

public final int getMarginLeft()

Retrieves the left-most coordinates of this field's margin.

Returns:: The left-most margin coordinates.
Since:: BlackBerry API 6.0.0

getMarginRight

public final int getMarginRight()

Retrieves the right-most coordinates of this field's margin.

Returns:: The right-most margin coordinates.
Since:: BlackBerry API 6.0.0

getMarginTop

public final int getMarginTop()

Retrieves the top-most coordinates of the margin.

Returns:: The top-most margin coordinates.
Since:: BlackBerry API 6.0.0

getManager

public final Manager getManager()

Retrieves this field's manager.

Returns:: This field's manager, or null if no manager has been set for this field.

getOriginal

public Field getOriginal()

Retrieves original instance of this field.

Returns:: The original instance of this field.

getPadding

public final void getPadding(XYEdges padding)

Retrieves the coordinates of this field's padding.

Parameters:: padding - An XYEdges object to contain this field's padding coordinates.
Since:: BlackBerry API 6.0.0

getPaddingBottom

public final int getPaddingBottom()

Retrieves the bottom-edge coordinates of this field's padding.

Returns:: The bottom-edge coordinate of this field's padding edge.
Since:: BlackBerry API 6.0.0

getPaddingLeft

public final int getPaddingLeft()

Retrieves the left-most coordinate of the padding.

Returns:: The left-most padding coordinate.
Since:: BlackBerry API 6.0.0

getPaddingRight

public final int getPaddingRight()

Retrieves the right-most padding coordinate.

Returns:: The right-most padding coordinate.
Since:: BlackBerry API 6.0.0

getPaddingTop

public final int getPaddingTop()

Retrieves the top-most padding coordinate.

Returns:: The top-edge padding coordinate.
Since:: BlackBerry API 6.0.0

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:: The 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:: The preferred width for this field in pixels.

getScreen

public final Screen getScreen()

Retrieves the screen that currently owns this field.

Returns:: The screen that currently owns this field, or null if no screen currently owns this field.

getVisualState

public final int getVisualState()

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

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

getStyle

public final long getStyle()

Retrieves this field's current style bits.

Returns:: A combination of the current style bits.

getTop

public final int getTop()

Retrieves this field's top-offset position.

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

Returns:: The top-offset position of this field.

getWidth

public final int getWidth()

Retrieves this field's width.

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

Returns:: The 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 - The X-offset in the field's ContentRect coordinates.; y - The Y-offset in the field's ContentRect coordinates.; width - The width of the region.; height - The 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 - The X-offset in the field's non-ContentRect coordinates.; y - The Y-offset in the field's non-ContentRect coordinates.; width - The width of the region.; height - The height of the region.
Since:: BlackBerry API 4.2.0

isScrollCopyable

protected boolean isScrollCopyable()

Indicates whether a field may scroll by copying paintable regions.

This is allowed if the field's background is a solid color (regardless of alpha). Field sub-classes may override this method if they have a non-scrollable static background with a scrolling foreground (like the ribbon app).

Returns:: true if scrolling can be animated by copying and dragging the field's graphics, false if the field needs to be repainted during scrolling animation.
Since:: BlackBerry API 6.0.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, false otherwise.
See Also:: Field.isMuddy(), Field.setDirty(boolean)

isEnabled

public boolean isEnabled()

Determines if this field is enabled.

Returns:: true if this field is enabled, false otherwise.
Since:: BlackBerry API 6.0.0

isEditable

public boolean isEditable()

Determines if this field is editable.

It is not recommended to override this method. Use Field.setEditable(boolean) to change the status of the field.

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

isFocus

public boolean isFocus()

Determines if this field currently has the focus.

Returns:: true if this field has the focus, false otherwise.
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, false otherwise.

isLeftToRight

public final boolean isLeftToRight()

Indicates whether this field's text should be left-to-right.

This method returns the Left-to-Rightness of the current field based on an explicitly set value or, in its absence, based on the parent Manager's value or, finally, the Left-to-Rightness of the current Locale.

Returns:: true if text should be drawn Left-to-Right, false otherwise.
Since:: BlackBerry API 7.0.0

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, false otherwise.
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 operations, false otherwise.

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, false otherwise.

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, false otherwise.
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, false otherwise.

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 Field.isSelectionCopyable() methods.

Returns:: true if the selection is both copyable and deletable, false otherwise.

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, false otherwise.

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, false otherwise.
Since:: BlackBerry API 4.3.0

isStyle

public final boolean isStyle(long style)

Determines if this field has all the provided styles.

Parameters:: style - The style(s) to check.
Returns:: true if this field's styles exactly match the provided style bits, false otherwise.
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:: true if the element is visible, false otherwise.
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 - The character generated.; status - The modifier key status. See KeypadListener.; time - The number of milliseconds since the device was turned on.
Returns:: true if this method consumed the event, false otherwise.

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 - The character generated.; status - The modifier key status. See KeypadListener.; time - The number of milliseconds since the device was turned on.
Returns:: true if this method consumed the event, false otherwise.

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 - The code of the key that was pressed.; time - The 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 - The code of the key that was repeated.; time - The 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 - The code of the status key.; time - The 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 - The code of the key that was released.; time - The 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.

This method is 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 refetches and caches these attributes.

Parameters:: width - The amount of available horizontal space.; height - The 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 - The 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 - The 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. This method also clears this field's muddy state.

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

Parameters:: amount - The number of positions to move. Positive values mean down, negative values mean up.; status - The modifier key status applied when the trackwheel roll occurred (combination of applicable modifier keycode values from KeypadListener).; time - The number of milliseconds since the device was turned on.
Returns:: The 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 - The horizontal axis (field local) of new focus position.; y - The vertical axis (field local) of new focus position.; status - The key modifiers applicable to the focus movement.; time - The number of milliseconds since the device was turned on.

onFocus

protected void onFocus(int direction)

Invoked when a field receives the focus.

The framework will not invoke this method if this field already has the focus or is not focusable (Field.isFocusable() returns false).

Managers should find a child field that accepts focus and trigger 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 - The direction from which 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() returns an equivalent value to 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 - The graphics context for drawing in this field.

getBackground

public final Background getBackground()

Retrieves the current background object based on current visual state of the field.

A custom background set via Field.setBackground(Background) or Field.setBackground(int, Background) will override the existing theme background. This method returns null if no custom or theme background exists.

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

getBackground

public final Background getBackground(int visual)

Retrieves the current background object based on a specified visual state of the field.

Parameters:: visual - The visual state associated with background: Field.VISUAL_STATE_NORMAL, Field.VISUAL_STATE_ACTIVE, Field.VISUAL_STATE_FOCUS, Field.VISUAL_STATE_DISABLED, or Field.VISUAL_STATE_DISABLED_FOCUS.
Returns:: The Background object that is currently displayed, or 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 - The Background object to display, or 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 - The Background object to display, or null to use default theme background.; visual - The visual state associated with background. One of the following: Field.VISUAL_STATE_NORMAL, Field.VISUAL_STATE_ACTIVE, Field.VISUAL_STATE_FOCUS, Field.VISUAL_STATE_DISABLED, or 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 - The Clipboard object containing data to paste.
Returns:: true if the operation was successful, false otherwise.

setExtent

protected 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 - The width of the field.; height - The height of the field.

setFont

public void setFont(Font font)

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

Parameters:: font - The new font for this field.

setFont

public void setFont(Font font,
                    boolean layout)

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

Parameters:: font - The new font for this field.; layout - If true the layout needs to be updated, if false the layout does not need to be updated.
Since:: BlackBerry API 7.0.0

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 - The offset of the left of the field in its manager.; y - The 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, and must throw an IllegalStateException if the field is not selectable.

Parameters:: enable - If true selection mode is enabled, if false selection mode is disabled.
Throws:: IllegalStateException - if this field is not selectable.

selectionCopy

public void selectionCopy(Clipboard cb)
                   throws IllegalStateException

Performs a copy operation on this field.

Custom fields that support copy operations must override this method.

Parameters:: cb - The Clipboard object to use.
Throws:: IllegalStateException - if cb is invalid.

selectionCut

public void selectionCut(Clipboard cb)
                  throws IllegalStateException

Performs a cut operation on this field.

This is a convenience method that, by default, wraps selectionCopy(cb) and selectionDelete(). Custom fields that support cut operations must override this method.

Parameters:: cb - The Clipboard object to use.
Throws:: IllegalStateException - if cb is invalid.

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 inside the margin. Note that this field's layout is automatically updated.

This is a convenience method for setBorder(int, Border, boolean) that sets the VISUAL_STATE_NORMAL and VISUAL_STATE_FOCUS visual states.

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

setBorder

public 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.

The border is the area within a field outside the padding and inside the margin.

This is a convenience method for setBorder(Border, boolean) that sets the VISUAL_STATE_NORMAL and VISUAL_STATE_FOCUS visual states.

Parameters:: border - The Border object to display, or null to use default theme border.; updateLayout - A 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 inside the margin. Note that this field's layout is automatically updated.

Parameters:: visual - The visual state associated with background: Field.VISUAL_STATE_NORMAL, Field.VISUAL_STATE_ACTIVE, Field.VISUAL_STATE_FOCUS, Field.VISUAL_STATE_DISABLED, or Field.VISUAL_STATE_DISABLED_FOCUS.; border - The Border object to display, or 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)

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 inside the margin. 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 - The visual state associated with background: Field.VISUAL_STATE_NORMAL, Field.VISUAL_STATE_ACTIVE, Field.VISUAL_STATE_FOCUS, Field.VISUAL_STATE_DISABLED, or Field.VISUAL_STATE_DISABLED_FOCUS.; border - The Border object to display, or null to use default theme border.; updateLayout - A flag to indicate whether to update the field's layout.
Throws:: IllegalArgumentException - 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 a null parameter.

Parameters:: listener - The object to listen for field changes, or null to remove the currently registered listener.
Throws:: IllegalStateException - if there is already a listener set and the 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 - The 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 - If true the field is dirty, if false the field is clean.
See Also:: Field.isDirty(), Field.setMuddy(boolean)

setEnabled

public void setEnabled(boolean enabled)

Sets this field to be enabled or disabled.

Parameters:: enabled - If true this field is enabled, if false this field is disabled.
Since:: BlackBerry API 6.0.0

setEditable

public void setEditable(boolean editable)

Sets 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 this field is made editable, if false this field is made not 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 to remove the old listener.

Parameters:: listener - The object to listen for focus changes, or null to remove the old listener.
Throws:: IllegalStateException - if there is already a listener set and the provided parameter is not null.

setMargin

public void setMargin(int top,
                      int right,
                      int bottom,
                      int left)

Sets the margin for this field.

The margin is the area outside a field, after the border. It is up to a manager to allocate margins properly since these overlap.

Parameters:: top - The top-most coordinate of the margin.; right - The right-most coordinate of the margin.; bottom - The bottom-most coordinate of the margin.; left - The left-most coordinate of the margin.
Since:: BlackBerry API 6.0.0

setMargin

public void setMargin(XYEdges margin)

Sets the margin for this field.

The margin is the area outside a field, after the border. It is up to a manager to allocate margins properly since these overlap.

Parameters:: margin - The margin coordinates; must not be null.
Throws:: IllegalArgumentExcpetion - if margin is null.
Since:: BlackBerry API 6.0.0

setPadding

public void setPadding(int top,
                       int right,
                       int bottom,
                       int left)

Sets the padding for this field.

The padding is the area within a field between the content and the border.

Parameters:: top - The top-most padding coordinate.; right - The right-most padding coordinate.; bottom - The bottom-most padding coordinate.; left - The left-most padding coordinate.
Throws:: IllegalArgumentException - if any of the padding coordinates are negative and larger in magnitude than the border.
Since:: BlackBerry API 6.0.0

setPadding

public void setPadding(XYEdges padding)

Sets the padding for this field.

The padding is the area within a field between the content and the border.

Parameters:: padding - The padding coordinates; must not be null.
Since:: BlackBerry API 6.0.0

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 - If true this field should be made muddy and dirty, if false this field should be made un-muddy.
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, if true make this field 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, or Field.VISUAL_STATE_DISABLED_FOCUS.
Since:: BlackBerry API 4.6.0

touchEvent

protected boolean touchEvent(TouchEvent message)

Indicates a touch event.

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

cursorClick

protected boolean cursorClick(int x,
                              int y,
                              int status,
                              int time)

Indicates a cursor click event.

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

Parameters:: x - X coordinate of the cursor event.; y - Y coordinate of the cursor event.; 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 7.0.0

cursorUnclick

protected boolean cursorUnclick(int x,
                                int y,
                                int status,
                                int time)

Indicates a cursor unclick event.

The system invokes this method when passing on a cursor unclick event.

Parameters:: x - X coordinate of the cursor event.; y - Y coordinate of the cursor event.; 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 7.0.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 - A bitfield of values defined by KeypadListener.; time - The number of milliseconds since the device was turned on.
Returns:: true if this method consumed the event, false otherwise.
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 - A bitfield of values defined by KeypadListener.; time - The 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 - The magnitude of navigational motion: negative for a move left and positive for a move right.; dy - The magnitude of navigational motion: negative for an upwards move, and positive for a downwards move.; status - A bitfield of values defined by KeypadListener.; time - The 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 - A bitfield of values defined by KeypadListener.; time - The number of milliseconds since the device was turned on.
Returns:: true if this method consumed the event, false otherwise.

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 - A bitfield of values defined by KeypadListener.; time - The 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)

Called when the field's visibility changes.

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

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

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

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

onDisplay

protected void onDisplay()

Deprecated. Use #onUiEngineAttached.

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()

Deprecated. Use #onUiEngineAttached.

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:: An AccessibleContext instance that represents the field for a screen reader.
Since:: BlackBerry API 4.6.1

setCommandItemProvider

public final void setCommandItemProvider(CommandItemProvider commandItemProvider)

Sets this field as a command item provider. If set, this field will provide CommandItems (for example, to provide command items to add to the pop-up menu).

Parameters:: commandItemProvider - The CommandItemProvider for this field, can be null.
Since:: BlackBerry API 6.0.0

getCommandItemProvider

public final CommandItemProvider getCommandItemProvider()

Gets the command item provider.

Returns:: The command item provider, or null if one is not set.
Since:: BlackBerry API 6.0.0

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-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal

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

getTextStrokeColor

getTextFillColor

getHeight

getIndex

getLeafFieldWithFocus

getLeft

getMargin

getMarginBottom

getMarginLeft

getMarginRight

getMarginTop

getManager

getOriginal

getPadding

getPaddingBottom

getPaddingLeft

getPaddingRight

getPaddingTop

getPreferredHeight

getPreferredWidth

net.rim.device.api.ui
Class Field