SHOW Colour

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, net.rim.device.api.ui.component.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 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

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

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

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

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

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

getChangeListener

public FieldChangeListener getChangeListener()

Retrieves the current change listener.

Returns:

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

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.

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.

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.

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

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

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.

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

Managers may make use of this value during layout.

Returns:

Preferred height for 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.

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.

getStyle

public final long getStyle()

Retrieves this field's current style bits.

Returns:

Long representing combination of the current style bits.

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.

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

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.

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.

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.

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.

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.

Since:

JDE 3.6.0

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

keyControl

protected boolean keyControl(char character,
                             int status,
                             int time)

Like keyChar, but for control characters.

Since:

JDE 3.7.0

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

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

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

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

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

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

See Also:

ContextMenu

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

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

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

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.

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

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

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

setPosition

protected final void setPosition(int x,
                                 int y)

Places this field within a manager's child region.

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

Parameters:

x - Offset of the left of the field in its manager.

y - Offset of the top of the field in its manager.

Since:

JDE 3.7.0

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.

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

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

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

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

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

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

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

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

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

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

trackwheelClick

protected boolean trackwheelClick(int status,
                                  int time)

Indicates a trackwheel click event.

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

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

Parameters:

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

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

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

See Also:

Screen.onDisplay(), Screen.onExposed(), Screen.onObscured(), Screen.onUndisplay()