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

FOCUSABLE

NON_FOCUSABLE

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

HIGHLIGHT_FOCUS

public static final int HIGHLIGHT_FOCUS

Highlight bit to indicate focus highlighting.

HIGHLIGHT_SELECT

public static final int HIGHLIGHT_SELECT

Highlight bit to indicate select highlighting.

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

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.

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.

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.

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 filled in, or when system
parameters change (for example, after a system font change).
getExtent() should return a valid value after invoking this
method. Iplementations of this method should invoke setExtent(int, int)
with the size needed by the field.

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.

makeContextMenu

By default, this method populates the context menu with cut, copy,
and paste entries, if appropriate. Subclasses should always invoke the
superclass's version of this method, to ensure the full population of the
context menu.

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

moveFocus

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

Moves the focus to an exact position within this field.

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

Parameters:

x - Horizontal axis (field local) of new focus position.

y - Veritcal axis (field local) of new focus position.

status - Key modifiers applicable to the focus movement.

time - Number of milliseconds since the device was turned on.

Category:

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

onFocus

protected void onFocus(int direction)

Invoked when a field receives the focus.

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

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

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

1 indicates that the focus came from the previous field.

-1 indicates that the focus came from the following field.

0 indicates that the focus was set directly, (that is, not by
rolling the trackwheel)

Parameters:

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

Category:

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.

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.

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.

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.

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.