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
specialised 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
behaviour 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 behaviour 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 behaviour. 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 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.

VISUAL_STATE_NORMAL

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

drawFocus

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.

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

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

Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

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.

Category:

Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

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

getBackground

Retrieve the current background object based on current visual state of the
field. A custom background set via 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:

JDE 4.6.0

getBackground

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

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

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.

Parameters:

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

Since:

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

getFocusRect

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.

invalidate

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:

JDE 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 behaviour 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:

JDE 4.2.0

Category:

Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

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:

JDE 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 setMuddy(boolean)). When the user moves the
cursor, then the field becomes not muddy but is still dirty.

isFocusable

By default, this method checks the field style to determine whether
this field is 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 setMuddy(boolean)). However, when the user moves
the cursor then the field becomes not muddy but is still dirty.

isSelectionCopyable

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:

JDE 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:

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

The method is pessimistic, it may indicate that a screen or field is
visible when it isn't. If a screen or field is visible this method will
return true.

Returns:

The visibility state of the field or screen. true if the element
is visible.

Since:

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

False (classes that extend Field must override this method to
provide specific handling).

Category:

Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

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

Category:

Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

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).
getExtent() will return a valid value after this method is
invoked. Implementations of this method must invoke setExtent(int, int)
with the size used by the field.

During this call, 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.

Category:

Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

onUndisplay

Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

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.

Category:

Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

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

paint

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 requried to statisfy 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.

Category:

Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

setBackground

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.

setBackground

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.

setBorder

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:

JDE 4.6.0

setBorder

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.

Parameters:

border - Border object to display, null to use default theme border.

updateLayout - Flag to indicate whether to update the field's layout.

Since:

JDE 4.6.0

setBorder

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.

setBorder

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.

setChangeListener

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.