SHOW Framework

net.rim.device.api.ui
Class Field

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

public abstract class Field
extends Object
implements IComponent

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'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.
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 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 READONLY
          Field style bit to indicate whether or not the user can change the contents.
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).
 
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
 Category: Framework protected  void drawFocus(Graphics graphics, boolean on)
          Draws the focus indicator for this field.
 Category: Framework 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.
 Category: Framework protected  void fieldChangeNotify(int context)
          Invoked for this field when a change event occurs.
 Category: Framework protected  void focusAdd(boolean draw)
          Adds focus to this field.
 Category: Framework protected  void focusRemove()
          Removes focus from this field.
   FieldChangeListener getChangeListener()
          Retrieves the current change listener.
   int getContentHeight()
          Retrieves this field's content height.
   int getContentLeft()
          Retrieves this field's content's left-most extent.
   XYRect getContentRect()
          Retrieves this field's extent (region occupied in its manager's child region).
   void getContentRect(XYRect rect)
          Retrieves this field's extent (region occupied in its manager's child region).
   int getContentTop()
          Retrieves this field's content's top-most extent.
   int getContentWidth()
          Retrieves this field's content width.
   ContextMenu getContextMenu()
          Gets the current context menu for this field.
   Object getCookie()
          Retrieves previously set cookie.
   XYRect getExtent()
          Retrieves this field's extent (region occupied in its manager's child region).
   void getExtent(XYRect extent)
          Retrieves this field's extent (region occupied in its manager's child region).
   int getFieldStyle()
          Retrieves this field's current custom field styles as an integer.
   FocusChangeListener getFocusListener()
          Retrieves the current focus listener.
   void getFocusRect(XYRect rect)
          Retrieves this field's current focus region.
   Font getFont()
          Retrieves this field's current font.
   int getHeight()
          Retrieves this field's height.
   int getIndex()
          Retrieves position of this field within its manager.
   Field getLeafFieldWithFocus()
          Retrieves the leaf (non-manager) field with the focus.
   int getLeft()
          Retrieves this field's left-offset position.
   Manager getManager()
          Retrieves this field's manager.
   Field getOriginal()
          Retrieves original instance of this field.
   int getPreferredHeight()
          Retrieves this field's preferred height.
   int getPreferredWidth()
          Retrieves this field's preferred width.
   Screen getScreen()
          Retrieves the screen that currently owns this field.
   long getStyle()
          Retrieves this field's current style bits.
   int getTop()
          Retrieves this field's top-offset position.
   int 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).
 Category: Framework protected  boolean invokeAction(int action)
          Invokes an action on this field.
   boolean isDataValid()
          Indicates whether the data on the screen is valid.
   boolean isDirty()
          Determines if this field is dirty.
   boolean isEditable()
          Determines if this field is editable.
   boolean isFocus()
          Determines if this field currently has the focus.
   boolean isFocusable()
          Determines if this field accepts the focus.
   boolean isMuddy()
          Indicates whether this field has recently become muddy and the focus has not yet changed.
   boolean isPasteable()
          Determines if this field supports paste operations.
   boolean isSelectable()
          Determines if this field supports selection.
   boolean isSelecting()
          Determines if this field is in selection mode.
   boolean isSelectionCopyable()
          Determines if this field supports copy operations.
   boolean isSelectionCutable()
          Determines if this field supports cut operations.
   boolean isSelectionDeleteable()
          Determines if this field supports the delete operation.
   boolean isStyle(long style)
          Determines if this field has all the provided styles.
   boolean isVisible()
          Determines whether or not this UI element is visible.
 Category: Framework protected  boolean keyChar(char character, int status, int time)
          Handles character generation events.
 Category: Framework protected  boolean keyControl(char character, int status, int time)
          Handles control character generation events.
 Category: Framework protected  boolean keyDown(int keycode, int time)
          Handles key down events.
 Category: Framework protected  boolean keyRepeat(int keycode, int time)
          Handles key repeat events.
 Category: Framework protected  boolean keyStatus(int keycode, int time)
          Handles key status events.
 Category: Framework protected  boolean keyUp(int keycode, int time)
          Handles key up events.
 Category: Framework protected abstract  void layout(int width, int height)
          Lays out field contents.
 Category: Framework protected  void makeContextMenu(ContextMenu contextMenu)
          Builds this field's context menu.
 Category: Framework protected  int moveFocus(int amount, int status, int time)
          Handles moving the focus within this field.
 Category: Framework protected  void moveFocus(int x, int y, int status, int time)
          Moves the focus to an exact position within this field.
 Category: Framework protected  boolean navigationClick(int status, int time)
          Invoked when the navigational action is selected.
 Category: Framework protected  boolean navigationMovement(int dx, int dy, int status, int time)
          Invoked when a navigational motion occurs.
 Category: Framework protected  boolean navigationUnclick(int status, int time)
          Invoked when the navigational action is released.
 Category: Framework protected  void onDisplay()
          Invoked when the screen this field is attached to is pushed onto the display stack.
 Category: Framework protected  void onExposed()
          Invoked when the screen this field is attached to is revealed by a screen getting popped off the display stack.
 Category: Framework 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).
 Category: Framework protected  void onObscured()
          Invoked when the screen this field is attached to is obscured by a new screen pushed on the display stack.
 Category: Framework protected  void onUndisplay()
          Invoked when the screen this field is attached to is popped off the display stack.
 Category: Framework protected  void onUnfocus()
          Invoked when a field loses the focus.
 Category: Framework protected  void onVisibilityChange(boolean visible)
          This method is called when the field's visibility changes.
 Category: Framework 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 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.
 Category: Framework protected  boolean trackwheelClick(int status, int time)
          Indicates a trackwheel click event.
 Category: Framework protected  boolean trackwheelUnclick(int status, int time)
          Indicates a trackwheel release event.
 Category: Framework 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

ACTION_INVOKE

public static final int ACTION_INVOKE
Constant to indicate that the default action was invoked.
Since:
JDE 4.2.0

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.


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
 

FIELD_BOTTOM

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

FIELD_HALIGN_MASK

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

FIELD_HCENTER

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

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_TOP

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

FIELD_VALIGN_MASK

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

FIELD_VCENTER

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

FOCUSABLE

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

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
 

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.

NON_FOCUSABLE

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

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.


STATUS_MOVE_FOCUS_HORIZONTALLY

public static final int STATUS_MOVE_FOCUS_HORIZONTALLY
Focus movement event has a horizontal bias.
Since:
JDE 4.2.0

STATUS_MOVE_FOCUS_VERTICALLY

public static final int STATUS_MOVE_FOCUS_VERTICALLY
Focus movement event has a vertical bias.
Since:
JDE 4.2.0

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.


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.

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.

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

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 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 drawHighlightRegion(net.rim.device.api.ui.Graphics, int, boolean, int, int, int, int) to render the focus indicator using the rect obtained from getFocusRect(net.rim.device.api.ui.XYRect).

Parameters:
graphics - Graphics context for drawing the focus.
on - True if the focus should be set; otherwise, false.
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

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

Parameters:
graphics - Graphics object for drawing the highlight.
style - Style of highlight to render.
on - True if the highlight should be set; otherwise, false.
x - Left side of the highlight region.
y - Top edge of the highlight region.
width - Width of the highlight region.
height - Height of the highlight region.
Throws:
IllegalArgumentException - If style is invalid.
NullPointerException - If graphics is null.
Category:
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.
Throws:
IllegalArgumentException - If the field is a manager (a non-leaf 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.

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 focusAdd(boolean) 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).
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

getChangeListener

public FieldChangeListener getChangeListener()
Retrieves the current change listener.
Returns:
Current change listener; otherwise, if there is no listener object set, returns null.

getContentHeight

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

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

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

getContentLeft

public final int getContentLeft()
Retrieves this field's content's left-most extent.

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

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

getContentRect

public final XYRect getContentRect()
Retrieves this field's extent (region occupied in its manager's child region).
Returns:
Object encoding the field's region in its parent manager's coordinates.
Since:
JDE 4.2.0

getContentRect

public final void getContentRect(XYRect rect)
Retrieves this field's extent (region occupied in its manager's child region).
Returns:
Object encoding the field's region in its parent manager's coordinates.
Since:
JDE 4.2.0

getContentTop

public final int getContentTop()
Retrieves this field's content's top-most extent.

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

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

getContentWidth

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

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

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

getContextMenu

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

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

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

Returns:
Context menu for this field.

getCookie

public final Object getCookie()
Retrieves previously set cookie.

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

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

getExtent

public final XYRect getExtent()
Retrieves this field's extent (region occupied in its manager's child region). The extent is the union of the field's drawable area, its area for padding, and its area for borders. The field is not able to draw in its padding or border areas. Only the field's manager, its manager's manager, etc., may draw in the padding and border areas.
Returns:
The extent of the field in its parent Manager's co-ordinate system.

getExtent

public final void getExtent(XYRect extent)
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.

getFocusListener

public FocusChangeListener getFocusListener()
Retrieves the current focus listener.
Returns:
Current focus listener; otherwise, if there is no listener object set, returns null.

getFocusRect

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

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

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

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

getFont

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

getHeight

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

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

Returns:
Height of this field.

getIndex

public final int getIndex()
Retrieves position of this field within its manager.
Returns:
The ordinal position of the field within its manager. If the field does not currently belong to a manager, this method returns -1.

getLeafFieldWithFocus

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

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

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

getLeft

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

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

Returns:
X offset of the field.

getManager

public final Manager getManager()
Retrieves this field's manager.
Returns:
This field's manager; otherwise, if no manager has been set for this field, this method returns null.

getOriginal

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

getPreferredHeight

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

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

Returns:
Preferred height for this field in pixels.

getPreferredWidth

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

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

Returns:
Preferred width for this field in pixels.

getScreen

public final Screen getScreen()
Retrieves the screen that currently owns this field.
Returns:
Screen that currently owns this field, null if there isn't one.

getStyle

public final long getStyle()
Retrieves this field's current style bits.
Returns:
Combination of the current style bits.

getTop

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

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

Returns:
Y-offset of this field.

getWidth

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

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

Returns:
Width of the field.

invalidate

protected void invalidate()
Marks this entire field invalid.

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

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


invalidate

protected void invalidate(int x,
                          int y,
                          int width,
                          int height)
Marks a region of this field as invalid (requiring repainting).

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

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

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

invalidateAll

protected void invalidateAll(int x,
                             int y,
                             int width,
                             int height)
Marks a region of this field as invalid (requiring repainting).

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

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

Parameters:
x - X-offset in the field's non-ContentRect coordinates.
y - Y-offset in the field's non-ContentRect coordinates.
width - Width of the region.
height - Height of the region.
Since:
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.

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

isEditable

public boolean isEditable()
Determines if this field is editable.
Returns:
True if the field can be edited; otherwise, false.

isFocus

public boolean isFocus()
Determines if this field currently has the focus.
Returns:
True if this field has the focus; otherwise, false.
Since:
JDE 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 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.

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

isPasteable

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

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

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

isSelectable

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

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

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

isSelecting

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

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

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

isSelectionCopyable

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

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

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

isSelectionCutable

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

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

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

isSelectionDeleteable

public boolean isSelectionDeleteable()
Determines if this field supports the delete operation.

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

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

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.

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

Parameters:
character - Character generated.
status - Modifier key status. See KeypadListener.
time - Number of milliseconds since the device was turned on.
Returns:
True if this method consumed the event; otherwise, false.
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

keyControl

protected boolean keyControl(char character,
                             int status,
                             int time)
Handles control character generation events.

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

Parameters:
character - Character generated.
status - Modifier key status. See KeypadListener.
time - Number of milliseconds since the device was turned on.
Returns:
True if this method consumed the event; otherwise, false.
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

keyDown

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

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

Parameters:
keycode - Code of key pressed.
time - Number of milliseconds since the device was turned on.
Returns:
False (classes that extend Field must override this method to provide specific handling).
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

keyRepeat

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

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

Parameters:
keycode - Code of key repeated.
time - Number of milliseconds since the device was turned on.
Returns:
False (classes that extend Field must override this method to provide specific handling).
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

keyStatus

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

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

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

makeContextMenu

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

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

Parameters:
contextMenu - Context menu to build.
See Also:
ContextMenu
Category:
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 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 (combination of applicable modifier keycode values from KeypadListener).
time - Number of milliseconds since the device was turned on.
Returns:
Remaining scroll amount not used up, with the same sign.
Category:
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.

navigationClick

protected boolean navigationClick(int status,
                                  int time)
Invoked when the navigational action is selected.

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

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

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

Parameters:
status - Bitfield of values defined by KeypadListener.
time - Number of milliseconds since the device was turned on.
Returns:
True if this method consumed the event; otherwise, false.
Since:
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.

navigationMovement

protected boolean navigationMovement(int dx,
                                     int dy,
                                     int status,
                                     int time)
Invoked when a navigational motion occurs.

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

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.

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

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

onDisplay

protected void onDisplay()
Invoked when the screen this field is attached to is pushed onto the display stack.

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

The complementing callback is onUndisplay().

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

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 complimenting callback is onObscured().

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

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.

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

onMenuDismissed

protected void onMenuDismissed(Menu menu)
Called from Screen.onMenuDismissed(Menu) on all the fields and managers that are in focus when the drop-down menu is dismissed (whether it is dismissed by escaping out or by executing a menu item).
Parameters:
menu - Menu to be dismissed
Since:
JDE 4.2.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 complimenting callback is onExposed().

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

onUndisplay

protected void onUndisplay()
Invoked when the screen this field is attached to is popped off the display stack.

The complementing callback is onDisplay().

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

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.
Since:
JDE 3.6.0
See Also:
Screen.onDisplay(), Screen.onExposed(), Screen.onObscured(), Screen.onUndisplay()
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

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

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.

select

public void select(boolean enable)
            throws IllegalStateException
Enables or disables selection mode.

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

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

selectionCopy

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

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

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

selectionCut

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

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

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

selectionDelete

public void selectionDelete()
Performs a delete operation on this field.

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

See Also:
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 this method with null.

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

setCookie

public final void setCookie(Object cookie)
Sets a cookie object for later retrieval.

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

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

Parameters:
cookie - Object associated with this field.

setDirty

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

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

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

setEditable

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

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

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

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.

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 mangaer's first field.

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

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

setFocusListener

public void setFocusListener(FocusChangeListener listener)
Specifies a listener for focus changes to this field.

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

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

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.

setMuddy

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

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

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

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.

trackwheelClick

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

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

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

Parameters:
status - Bitfield of values defined by KeypadListener.
time - Number of milliseconds since the device was turned on.
Returns:
True if this method consumed the event; otherwise, false.
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

trackwheelUnclick

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

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

Parameters:
status - Bitfield of values defined by KeypadListener.
time - Number of milliseconds since the device was turned on.
Returns:
False (classes that extend Field must override this method to provide specific handling).
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

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.

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


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