net.rim.device.api.ui
Class Field

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
Direct Known Subclasses:
BitmapField, ButtonField, CheckboxField, ChoiceField, DateField, GaugeField, LabelField, ListField, Manager, NullField, RadioButtonField, SeparatorField, net.rim.device.api.ui.component.TextField, TreeField

public abstract class Field
extends Object

Provides fundamental functionality for all field components.

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

You can't instantiate Field directly, rather, use one of the provided 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 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.
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_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).
protected static long FIELD_VALIGN_MASK
          Bitfield mask of the vertical alignment style specifier.
static long FIELD_VCENTER
          Specifies that the field is centered vertically (style bit).
static long FOCUSABLE
          Field style bit to indicate wether 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 style bit to indicate focus highlighting.
static int HIGHLIGHT_SELECT
          Highlight style bit to indicate select highlighting.
static long NON_FOCUSABLE
          Field style bit to indicate whether or not the field is non-focusable.
static long READONLY
          Field style bit to indicate whether or not the user can change the contents.
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).
 
Constructor Summary
protected Field()
          Constructs a field with no style attributes.
protected Field(long style)
          Constructs a field with specified style attributes.
 
Method Summary
protected  void drawFocus(Graphics graphics, boolean on)
          Draws the focus indicator for this field.
protected  void drawHighlightRegion(Graphics graphics, int style, boolean on, int x, int y, int width, int height)
          Draws a highlight indicator for a rectangular region.
protected  void fieldChangeNotify(int context)
          Invoked for this field when a change event occurs.
protected  void focusAdd(boolean draw)
          Adds focus to this field.
protected  void focusRemove()
          Removes focus from this field.
 FieldChangeListener getChangeListener()
          Retrieves the current change listener.
 ContextMenu getContextMenu()
          Gets the current context menu for this field.
 Object getCookie()
          Retrieves previously set cookie.
 XYRect getExtent()
          Retrieves this field's extent (region occupied in its manager's child region).
 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 in its manager.
 Field getLeafFieldWithFocus()
          Retrieves the leaf (non-manager) field with the focus.
 int getLeft()
          Retrieves this field's left-offset position.
 Manager getManager()
          Retrieves this field's manager.
 Field getOriginal()
          Retrieves original instance of this field.
 int getPreferredHeight()
          Retrieves this field's preferred height.
 int getPreferredWidth()
          Retrieves this field's preferred width.
 Screen getScreen()
          Returns the screen that currently owns this field.
 long getStyle()
          Retrieves this field's current style bits.
 int getTop()
          Retrieves this field's top-offset position.
 int 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).
 boolean isDirty()
          Indicates whether this field is dirty.
 boolean isEditable()
          Indicates whether this field is editable.
 boolean isFocusable()
          Determines if this field accepts the focus.
 boolean isMuddy()
          Indicates whether this field has recently become muddy and the focus has not yet changed.
 boolean isPasteable()
          Determines if this field supports paste operations.
 boolean isSelectable()
          Determines if this field supports selection.
 boolean isSelecting()
          Determines if this field is in selection mode.
 boolean isSelectionCopyable()
          Determines if this field supports copy operations.
 boolean isSelectionCutable()
          Determines if this field supports cut operations.
 boolean isSelectionDeleteable()
          Determines if this field supports the delete operation.
 boolean isVisible()
          Determines whether or not this UI element is visible.
protected  boolean keyChar(char character, int status, int time)
          Signals generation of a character.
protected  boolean keyControl(char character, int status, int time)
          Like keyChar, but for control characters.
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  void onFocus(int direction)
          Invoked when a field receives the focus.
protected  void onUnfocus()
          Invoked when a field loses the focus.
protected  void onVisibilityChange(boolean visible)
          This method is called when the field's visibility changes.
protected abstract  void paint(Graphics graphics)
          Invoked by the framework to redraw a portion of this field.
 boolean paste(Clipboard cb)
          Performs a paste operation on this field.
 void select(boolean toggle)
          Sets or unsets 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 setChangeListener(FieldChangeListener listener)
          Specifies a listener for changes to this field.
 void setCookie(Object cookie)
          Sets a cookie object for later retrieval.
 void setDirty(boolean dirty)
          Sets the dirty state of the field.
 void setEditable(boolean editable)
          Set the editable state of this field.
protected  void setExtent(int width, int height)
          Sets this field's extent.
 void setFocus()
          Sets the focus to this field.
 void setFocusListener(FocusChangeListener listener)
          Specifies a listener for focus changes to this field.
 void setFont(Font font)
          Sets the font for this field and updates the display if necessary.
 void setMuddy(boolean muddy)
          Sets the muddy state for this field.
protected  void setPosition(int x, int y)
          Places this field within a manager's child region.
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_HALIGN_MASK

protected static final long FIELD_HALIGN_MASK
Bitfield mask of the horizontal alignment style specifier.

FIELD_LEFT

public static final long FIELD_LEFT
Field is aligned to the left (style bit).

FIELD_RIGHT

public static final long FIELD_RIGHT
Field is aligned to the right (style bit).

FIELD_HCENTER

public static final long FIELD_HCENTER
Field is centered horizontally (style bit).

FIELD_VALIGN_MASK

protected static final long FIELD_VALIGN_MASK
Bitfield mask of the vertical alignment style specifier.

FIELD_TOP

public static final long FIELD_TOP
Field is aligned to the top (style bit).

FIELD_BOTTOM

public static final long FIELD_BOTTOM
Field is aligned to the bottom (style bit).

FIELD_VCENTER

public static final long FIELD_VCENTER
Specifies that the field is centered vertically (style bit).

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.


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.


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
 

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.

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.

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
 

FOCUSABLE

public static final long FOCUSABLE
Field style bit to indicate wether or not the field is focusable.

NON_FOCUSABLE

public static final long NON_FOCUSABLE
Field style bit to indicate whether or not the field is non-focusable.

HIGHLIGHT_FOCUS

public static final int HIGHLIGHT_FOCUS
Highlight style bit to indicate focus highlighting.

HIGHLIGHT_SELECT

public static final int HIGHLIGHT_SELECT
Highlight style bit to indicate select highlighting.
Constructor Detail

Field

protected Field()
Constructs a field with no style attributes.

Field

protected Field(long style)
Constructs a field 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.

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

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.
Since:
JDE 3.6

getChangeListener

public FieldChangeListener getChangeListener()
Retrieves the current change listener.

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

getCookie

public final Object getCookie()
Retrieves previously set cookie.

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

Returns:
The cookie previously set with setCookie, or null if no cookie is currently set.

getFieldStyle

public final int getFieldStyle()
Retrieves this field's current custom field styles as an integer.
Returns:
Integer representing the combination of the current custom field style bits.

getFocusListener

public FocusChangeListener getFocusListener()
Retrieves the current focus listener.

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

getFocusRect

public void getFocusRect(XYRect rect)
Retrieves this field's current focus region.

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

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

Parameters:
rect - To contain the focus rect for this field in local coordinates.
Since:
JDE 3.6

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

getIndex

public final int getIndex()
Retrieves position of this field in 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.

getManager

public final Manager getManager()
Retrieves this field's manager.

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

getOriginal

public Field getOriginal()
Retrieves original instance of this field.

Returns:
Original instance of this field.

getStyle

public final long getStyle()
Retrieves this field's current style bits.

Returns:
Long representing combination of the current style bits.

getExtent

public final XYRect getExtent()
Retrieves this field's extent (region occupied in its manager's child region).

Returns:
XYRect encoding the field's region in its parent manager's coordinates.

getHeight

public final int getHeight()
Retrieves this field's height.

Uses getExtent().height to retrieve this field's height.

Returns:
Height of the field.

getLeft

public final int getLeft()
Retrieves this field's left-offset position.

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

Returns:
X offset of the field.

getPreferredHeight

public int getPreferredHeight()
Retrieves this field's preferred height.

Managers may make use of this value during layout.

Returns:
Preferred height for the field.

getTop

public final int getTop()
Retrieves this field's top-offset position.

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

Returns:
Y offset of the field.

getWidth

public final int getWidth()
Retrieves this field's width.

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

Returns:
Width of the field.

getPreferredWidth

public int getPreferredWidth()
Retrieves this field's preferred width.

Managers make use of this value during layout.

Returns:
Preferred width for the field.

isSelectionCopyable

public boolean isSelectionCopyable()
Determines if this field supports copy operations.

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

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

isSelectionCutable

public final boolean isSelectionCutable()
Determines if this field supports cut operations.

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

Returns:
True if this field supports cut; otherwise, 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.

isDirty

public boolean isDirty()
Indicates whether this field is dirty.

When a field is first created, it is clean. When a field's contents change it becomes dirty (either through user changes that prompt change events, or by invoking setDirty(boolean)).

Returns:
True if the field is dirty; otherwise, false.

isEditable

public boolean isEditable()
Indicates whether this field is editable.

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

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

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

isSelecting

public boolean isSelecting()
Determines if this field is in selection mode.

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

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

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

Returns:
True if the field is muddy; otherwise, false.

isPasteable

public boolean isPasteable()
Determines if this field supports paste operations.

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

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

isSelectable

public boolean isSelectable()
Determines if this field supports selection.

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

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

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 .
Since:
JDE 3.6

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 oposing state for the on parameter.

When overriding this methods fields should use drawHighlightRegion to render focus and select regions instead of hardcoding the logic.

By default this method invokes drawHighlightRegion to render the focus indicator using the rect obtained from getFocusRect.

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

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 HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT and (HIGHLIGHT_FOCUS | HIGHLIGHT_SELECT).

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. i.e., 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.

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

paint

protected abstract void paint(Graphics graphics)
Invoked by the framework to redraw a portion of this field.

paint 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 a field's paint method ensure that this.getFont() == graphics.getFont() and that the appropriate clipping rect and transformation stack are set up, so that paint 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 the paint methods of child fields.

Parameters:
graphics - The graphics object for drawing in the current field
Since:
JDE 3.6

setExtent

protected final void setExtent(int width,
                               int height)
Sets this field's extent.

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

Parameters:
width - Width of the field.
height - Height of the field.
Since:
JDE 3.6

setFont

public void setFont(Font font)
Sets the font for this field and updates the display if necessary.

Parameters:
font - New font for this field.
Since:
JDE 3.6

setPosition

protected final void setPosition(int x,
                                 int y)
Places this field within a manager's child region.

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

Parameters:
x - Offset of the left of the field in its manager.
y - Offset of the top of the field in its manager.
Since:
JDE 3.6

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 layed out in a screen, the appropriate updates are made to reflect the new field size.


getLeafFieldWithFocus

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

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

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

invalidate

protected void invalidate()
Marks this entire field invalid.

Use this method to mark an entire field 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.

Parameters:
x - The x offset in field coordinates.
y - The y offset in field coordinates.
width - The width of the region.
height - The height of the region.
Since:
JDE 3.6

focusRemove

protected void focusRemove()
Removes focus from this field.

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

If also invoking 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).

focusAdd

protected void focusAdd(boolean draw)
Adds focus to this field.

This field should invoke focusAdd 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 focusAdd should always be called after a focus region change to ensure that the new region is visible.

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

getContextMenu

public ContextMenu getContextMenu()
Gets the current context menu for this field.

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

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


getScreen

public final Screen getScreen()
Returns the screen that currently owns this field.

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

keyChar

protected boolean keyChar(char character,
                          int status,
                          int time)
Signals generation of a character.

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

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

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

Parameters:
character - Character generated.
status - Modifier key status. See KeypadListener.
time - Ticks since device reset.
Returns:
True if this method consumed the event; otherwise, false.
Since:
JDE 3.6

keyControl

protected boolean keyControl(char character,
                             int status,
                             int time)
Like keyChar, but for control characters.
Since:
JDE 3.6

keyDown

protected boolean keyDown(int keycode,
                          int time)
Handles key down events.

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

Parameters:
keycode - Code of key pressed.
time - Ticks since device reset.
Returns:
False (classes that extend Field must override this method to provide specific handling).
Since:
JDE 3.6

keyRepeat

protected boolean keyRepeat(int keycode,
                            int time)
Handles key repeat events.

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

Parameters:
keycode - Code of key repeated.
time - Ticks since device reset.
Returns:
False (classes that extend Field must override this method to provide specific handling).
Since:
JDE 3.6

keyStatus

protected boolean keyStatus(int keycode,
                            int time)
Handles key status events.

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

Parameters:
keycode - Code of status key.
time - Ticks since device reset.
Returns:
False (classes that extend Field must override this method to provide specific handling).
Since:
JDE 3.6

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 - Ticks since device reset.
Returns:
False (classes that extend Field must override this method to provide specific handling).
Since:
JDE 3.6

moveFocus

protected int moveFocus(int amount,
                        int status,
                        int time)
Handles moving the focus within this field.

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

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

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

This method also clears this field's muddy state.

Parameters:
amount - Number of positions to move, positive means down, negative means up.
status - Modifier key status applied when the trackwheel roll occurred.
time - Ticks since device reset.
Returns:
Remaining scroll amount not used up, with the same sign.
Since:
JDE 3.6

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 - Ticks since device reset.
Since:
JDE 3.6

makeContextMenu

protected void makeContextMenu(ContextMenu contextMenu)
Builds this field's context menu.

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

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.

Since:
JDE 3.6
See Also:
ContextMenu

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 the onFocus 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, (i.e., not by rolling the trackwheel)
Parameters:
direction - Indicates from which direction the focus enters the field.
Since:
JDE 3.6

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 super.onUnFocus() though or the muddy bit won't get cleared.


paste

public boolean paste(Clipboard cb)
Performs a paste operation on this field.

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

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

select

public void select(boolean toggle)
            throws IllegalStateException
Sets or unsets selection mode.

Custom fields that support select mode must override this method.

Parameters:
toggle - True to turn selection mode on, false to turn selection mode off.
Throws:
IllegalStateException - If this field is not selectable.
Since:
JDE 3.6

selectionCopy

public void selectionCopy(Clipboard cb)
                   throws IllegalStateException
Performs a copy operation on this field.

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

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

selectionCut

public void selectionCut(Clipboard cb)
                  throws IllegalStateException
Performs a cut operation on this field.

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

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

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:
isSelectionDeleteable(), selectionCut(net.rim.device.api.system.Clipboard)

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 setChangeListener(null).

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

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 getCookie() to retrieve this field's cookie.

Parameters:
cookie - Object associated with this field.
Since:
JDE 3.6

setDirty

public void setDirty(boolean dirty)
Sets the dirty state of the field.

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

Parameters:
dirty - Specify true if the field is dirty; otherwise, specify false to set the field to clean.
Since:
JDE 3.6

setEditable

public void setEditable(boolean editable)
Set the editable state of this field.

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

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

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, setFocus gives the focus to this mangaer's first field.

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

Throws:
IllegalStateException - If the field is not attached to a screen or if called on a Field that does not accept the focus.

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 setFocusListener(null) to remove the old listener.

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

setMuddy

public void setMuddy(boolean muddy)
Sets the muddy state for this field.

Parameters:
muddy - True if this field should be made muddy; false to un-muddy this field.
Since:
JDE 3.6

trackwheelClick

protected boolean trackwheelClick(int status,
                                  int time)
Indicates a trackwheel click event.

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

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

Parameters:
status - Bitfield of values defined by System.Keypad.
time - Ticks since device reset.
Returns:
True if this method consumed the event; otherwise, false.
Since:
JDE 3.6

trackwheelUnclick

protected boolean trackwheelUnclick(int status,
                                    int time)
Indicates a trackwheel release event.

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

Parameters:
status - Bitfield of values defined by System.Keypad.
time - Ticks since device reset.
Returns:
False (classes that extend Field must override this method to provide specific handling).
Since:
JDE 3.6

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.

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(). e.g., this method may be called with visible as false, but isVisible still returns true.

Parameters:
visible - True if the field has just become visible, false otherwise.
Since:
JDE 3.6
See Also:
Screen.onDisplay(), Screen.onExposed(), Screen.onObscured(), Screen.onUndisplay()


Copyright 1999-2002 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.