|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.ui.Field
public abstract class Field
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
specialized 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
behavior 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 behavior 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 behavior. 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 int |
AXIS_HORIZONTAL
Axis specifier. |
|
static int |
AXIS_SEQUENTIAL
Axis specifier. |
|
static int |
AXIS_VERTICAL
Axis specifier. |
|
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_LEADING
Field is aligned to the current locale's start-of-line. |
|
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). |
|
static long |
FIELD_TRAILING
Field is aligned to the current locale's end-of-line. |
|
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 whether 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 |
NON_SPELLCHECKABLE
Field style bit to indicate that field is not spellcheckable. |
|
static long |
READONLY
Field style bit to indicate whether or not the user can change the contents. |
|
static long |
SPELLCHECKABLE
Field style bit to indicate that field is spellcheckable. |
|
protected static long |
SPELLCHECKABLE_MASK
Field style mask to indicate whether spelling check can be run for this field. |
|
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). |
|
static int |
VISUAL_STATE_ACTIVE
Active visual state. |
|
static int |
VISUAL_STATE_DISABLED
Disabled visual state. |
|
static int |
VISUAL_STATE_DISABLED_FOCUS
Disabled, but focused visual state. |
|
static int |
VISUAL_STATE_FOCUS
Focus visual state. |
|
static int |
VISUAL_STATE_NORMAL
Normal visual state. |
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 | ||
---|---|---|
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. |
|
AccessibleContext |
getAccessibleContext()
Returns accessible representation of the field for a screen reader. |
|
Background |
getBackground()
Retrieve the current background object based on current visual state of the field. |
|
Background |
getBackground(int visual)
Retrieve the current background object based on a specified visual state of the field. |
|
Border |
getBorder()
Retrieve the current border object for this field based on current visual state of the field. |
|
Border |
getBorder(int visual)
Retrieve the current border object for this field based on a specified visual state of the field. |
|
void |
getBorder(XYEdges edges)
Retrieves the current border edges for this field into the specified XYEdges object. |
|
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 |
getVisualState()
Retrieves this field's current visual state, which can be set via Field.setVisualState(int) . |
|
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). |
|
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 |
isSpellCheckable()
Determines if this field is spell-checkable. |
|
boolean |
isStyle(long style)
Determines if this field has all the provided styles. |
|
boolean |
isVisible()
Determines whether or not this UI element is visible. |
|
protected boolean |
keyChar(char character,
int status,
int time)
Handles character generation events. |
|
protected boolean |
keyControl(char character,
int status,
int time)
Handles control character generation events. |
|
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 boolean |
navigationClick(int status,
int time)
Invoked when the navigational action is selected. |
|
protected boolean |
navigationMovement(int dx,
int dy,
int status,
int time)
Invoked when a navigational motion occurs. |
|
protected boolean |
navigationUnclick(int status,
int time)
Invoked when the navigational action is released. |
|
protected void |
onDisplay()
Invoked when the screen this field is attached to is pushed onto the display stack. |
|
protected void |
onExposed()
Invoked when the screen this field is attached to is revealed by a screen getting popped off the display stack. |
|
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). |
|
protected void |
onObscured()
Invoked when the screen this field is attached to is obscured by a new screen pushed on the display stack. |
|
protected void |
onUndisplay()
Invoked when the screen this field is attached to is popped off the display stack. |
|
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 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 |
setBackground(int visual,
Background background)
Sets a custom background for a specified visual state in this field and overrides the existing theme background if it exists. |
|
void |
setBackground(Background background)
Sets a custom background for this field (normal and focus states) and overrides the existing theme background if it exists. |
|
void |
setBorder(int visual,
Border border)
Sets a custom border for the specified visual state in this field and overrides the existing theme border if it exists. |
|
void |
setBorder(int visual,
Border border,
boolean updateLayout)
Sets a custom border for the specified visual state in this field and overrides the existing theme border if it exists. |
|
void |
setBorder(Border border)
Sets a custom border for this field (normal and focus states) and overrides the existing theme border if it exists. |
|
void |
setBorder(Border border,
boolean updateLayout)
Sets a custom border for this field (normal and focus states) and overrides the existing theme border if it exists. |
|
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. |
|
void |
setNonSpellCheckable(boolean nonSpellCheckable)
Sets the spell-checkable style for this field. |
|
protected void |
setPosition(int x,
int y)
Places this field within a manager's child region. |
|
void |
setVisualState(int visual)
Sets this field's current visual state, which can be subsequently accessed via Field.getVisualState() . |
|
protected boolean |
touchEvent(TouchEvent message)
Indicates a touch event. |
|
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 |
---|
public static final long FIELD_LEFT
public static final long FIELD_RIGHT
public static final long FIELD_HCENTER
public static final long FIELD_LEADING
public static final long FIELD_TRAILING
protected static final long FIELD_HALIGN_MASK
protected static final long FIELD_VALIGN_MASK
public static final long FIELD_TOP
public static final long FIELD_BOTTOM
public static final long FIELD_VCENTER
public static final long USE_ALL_WIDTH
Not all fields accept this style.
public static final long USE_ALL_HEIGHT
Not all fields accept this style.
protected static final long EDITABLE_MASK
Examples:
(style & EDITABLE_MASK) == 0 // default for field or (style & EDITABLE_MASK) == EDITABLE or (style & EDITABLE_MASK) == READONLY
public static final long EDITABLE
Not all fields accept this style.
public static final long READONLY
Not all fields accept this style.
protected static final long SPELLCHECKABLE_MASK
public static final long SPELLCHECKABLE
public static final long NON_SPELLCHECKABLE
protected static final long FOCUSABLE_MASK
Examples:
(style & FOCUSABLE_MASK) == 0 // default for field or (style & FOCUSABLE_MASK) == FOCUSABLE or (style & FOCUSABLE_MASK) == NON_FOCUSABLE
public static final long FOCUSABLE
public static final long NON_FOCUSABLE
public static final int HIGHLIGHT_FOCUS
public static final int HIGHLIGHT_SELECT
public static final int ACTION_INVOKE
public static final int STATUS_MOVE_FOCUS_HORIZONTALLY
public static final int STATUS_MOVE_FOCUS_VERTICALLY
public static final int AXIS_SEQUENTIAL
public static final int AXIS_HORIZONTAL
public static final int AXIS_VERTICAL
public static final int VISUAL_STATE_NORMAL
Field.getVisualState()
,
Constant Field Valuespublic static final int VISUAL_STATE_ACTIVE
Field.getVisualState()
,
Constant Field Valuespublic static final int VISUAL_STATE_FOCUS
Field.getVisualState()
,
Constant Field Valuespublic static final int VISUAL_STATE_DISABLED
Field.getVisualState()
,
Constant Field Valuespublic static final int VISUAL_STATE_DISABLED_FOCUS
Field.getVisualState()
,
Constant Field ValuesConstructor Detail |
---|
protected Field()
protected Field(long style)
Use this constructor to create a field, providing an integer value embodying 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.
style
- Combination of field style bits to specify display
attributes.
IllegalArgumentException
- if style
specifies
Field.FOCUSABLE_MASK
, Field.EDITABLE_MASK
,
or an undefined style.Method Detail |
---|
protected void drawFocus(Graphics graphics, boolean on)
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 Field.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 Field.drawHighlightRegion(net.rim.device.api.ui.Graphics, int, boolean, int, int, int, int)
to render
the focus indicator using the rect obtained from Field.getFocusRect(net.rim.device.api.ui.XYRect)
.
graphics
- Graphics context for drawing the focus.on
- True if the focus should be set; otherwise, false.protected final void drawHighlightRegion(Graphics graphics, int style, boolean on, int x, int y, int width, int height)
The style parameter indicates the type of highlight to draw. Valid
styles are Field.HIGHLIGHT_FOCUS
, Field.HIGHLIGHT_SELECT
and
(HIGHLIGHT_FOCUS | HIGHLIGHT_SELECT)
.
Fields that implement custom focus or selection behavior should use this method to draw highlight regions (instead of hardcoding highlight logic).
The Field.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. Field.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.
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.
IllegalArgumentException
- If style is invalid.
NullPointerException
- If graphics is null.protected void fieldChangeNotify(int context)
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.
context
- Information specifying the origin of the change.protected void focusAdd(boolean draw)
This field should invoke this method after it has changed its focus
region. A call to Field.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
Field.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.
draw
- Specify true if the new focus should be drawn; otherwise,
false.
IllegalArgumentException
- If the field is a manager (a non-leaf
field).protected void focusRemove()
This field should call this method when it is changing its focus
region. After making this call, this field should call Field.focusAdd(boolean)
to ensure the new focus is visible and (optionally) drawn.
If also invoking Field.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.
IllegalArgumentException
- If the field is a manager
(a non-leaf field).public final Border getBorder()
Field.setBorder(Border)
,
Field.setBorder(Border, boolean)
, Field.setBorder(int, Border)
, or
Field.setBorder(int, Border, boolean)
will override the existing theme
border. Returns null if no custom or theme border exists.
public final Border getBorder(int visual)
Field.setBorder(Border)
,
Field.setBorder(Border, boolean)
, Field.setBorder(int, Border)
, or
Field.setBorder(int, Border, boolean)
will override the existing theme
border. Returns null if no custom or theme border exists.
visual
- Visual state associated with background: Field.VISUAL_STATE_NORMAL
,
Field.VISUAL_STATE_ACTIVE
, Field.VISUAL_STATE_FOCUS
, Field.VISUAL_STATE_DISABLED
,
Field.VISUAL_STATE_DISABLED_FOCUS
.
IllegalArgumentException
- If visual
is an invalid visual state.public final void getBorder(XYEdges edges)
XYEdges
object. If no border exists,
no change is made to edges.
edges
- XYEdges objects to be populated with the dimensions of the
current border.public FieldChangeListener getChangeListener()
public final int getContentHeight()
Uses getContentRect().height
to retrieve this field's
width.
public final int getContentLeft()
Uses getContentRect().x
to retrieve this field's
left-most extent.
public final XYRect getContentRect()
public final void getContentRect(XYRect rect)
public final int getContentTop()
Uses getContentRect().y
to retrieve this field's
top-most extent.
public final int getContentWidth()
Uses getContentRect().width
to retrieve this field's
width.
public ContextMenu getContextMenu()
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.
public final Object getCookie()
Each field has storage for one cookie object; use this method to retrieve the last one set.
Field.setCookie(java.lang.Object)
, or null if no
cookie is currently set.public final XYRect getExtent()
public final void getExtent(XYRect extent)
extent
- Returns the extent of the field in its parent Manager's co-ordinate system.public final int getFieldStyle()
public FocusChangeListener getFocusListener()
public void getFocusRect(XYRect rect)
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.
rect
- Object to contain the focus rect for this field in local
coordinates.public Font getFont()
Font.getDefault()
.public final int getHeight()
Uses getExtent().height
to retrieve this
field's height. The height includes borders and padding, but does not include margins.
public final int getIndex()
public Field getLeafFieldWithFocus()
This method is useful if this field is a manager (lays out other contained fields).
public final int getLeft()
Uses getExtent().x
to retrieve this field's
left-offset position within its manager's plane.
public final Manager getManager()
public Field getOriginal()
public int getPreferredHeight()
Managers may make use of this value during layout. Override this method to request a certain height for your field.
public int getPreferredWidth()
Managers make use of this value during layout. Override this method to request a certain width for your field.
public final Screen getScreen()
public final int getVisualState()
Field.setVisualState(int)
.
Field.VISUAL_STATE_NORMAL
,
Field.VISUAL_STATE_ACTIVE
, Field.VISUAL_STATE_FOCUS
,
Field.VISUAL_STATE_DISABLED
, Field.VISUAL_STATE_DISABLED_FOCUS
.public final long getStyle()
public final int getTop()
Uses getExtent().y
to retrieve this field's
top-offset position within its manager's plane.
public final int getWidth()
Uses getExtent().width
to retrieve this field's
width. The width includes borders and padding, but does not include margins.
protected void invalidate()
Use this method to mark an entire field, not just its ContentRect, as invalid, signalling that it requires a repaint.
It is safe to call this function without synchronizing on the
event lock
.
protected void invalidate(int x, int y, int width, int height)
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
.
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.protected void invalidateAll(int x, int y, int width, int height)
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
.
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.protected boolean invokeAction(int action)
false
.
If action
is not a recognized action then this method does nothing and
returns false
, indicating that the action was not consumed.
action
- the action to be performed on this field.
true
if the action was consumed; false
if the action was not consumed.public boolean isDataValid()
Derived classes should override this method for more particular handling.
public boolean isDirty()
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 Field.setMuddy(boolean)
). When the user moves the
focus, then the field becomes not muddy but is still dirty.
Field.isMuddy()
,
Field.setDirty(boolean)
public boolean isEditable()
public boolean isFocus()
public boolean isFocusable()
By default, this method checks the field style to determine whether
this field is Field.FOCUSABLE
.
public boolean isMuddy()
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 Field.setMuddy(boolean)
). However, when the user moves
the focus then the field becomes not muddy but is still dirty.
Field.isDirty()
,
Field.setMuddy(boolean)
public boolean isPasteable()
By default, this method returns false; custom fields that support cut operations must override this method.
public boolean isSelectable()
By default, this method returns false; custom fields that support selection must override this method.
public boolean isSelecting()
By default, this method returns false; custom fields that support selection mode reporting must override this method.
Field.select(boolean)
public boolean isSelectionCopyable()
By default, this method returns false; custom fields that support copy operations must override this method.
public final boolean isSelectionCutable()
Custom fields do not have to override this method as it can be controlled by overriding the isSelectionDeletable() and isSelectionCopyable() methods.
public boolean isSelectionDeleteable()
By default, this method returns false; custom fields that support delete operations must override this method.
public boolean isSpellCheckable()
public final boolean isStyle(long style)
style
- Style(s) to check.
public final boolean isVisible()
This method returns true if the UI element is potentially visible. The application must be foreground and the screen must be visible.
However, this method might indicate that a screen or field is visible when it is not.
protected boolean keyChar(char character, int status, int time)
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.
character
- Character generated.status
- Modifier key status. See KeypadListener
.time
- Number of milliseconds since the device was turned on.
protected boolean keyControl(char character, int status, int time)
This field's manager invokes this method to send this field a control character event.
character
- Character generated.status
- Modifier key status. See KeypadListener
.time
- Number of milliseconds since the device was turned on.
protected boolean keyDown(int keycode, int time)
By default, this method returns false; custom fields that specially handle key down events must override this method.
keycode
- Code of key pressed.time
- Number of milliseconds since the device was turned on.
protected boolean keyRepeat(int keycode, int time)
By default, this method returns false; custom fields that specially handle key repeat events must override this method.
keycode
- Code of key repeated.time
- Number of milliseconds since the device was turned on.
protected boolean keyStatus(int keycode, int time)
By default, this method returns false; custom fields that specially handle key status events must override this method.
keycode
- Code of status key.time
- Number of milliseconds since the device was turned on.
protected boolean keyUp(int keycode, int time)
By default, this method returns false; custom fields that specially handle key up events must override this method.
keycode
- Code of key released.time
- Number of milliseconds since the device was turned on.
protected abstract void layout(int width, int height)
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).
Field.getExtent()
will return a valid value after this method is
invoked. Implementations of this method must invoke Field.setExtent(int, int)
with the size used by the field.
During this call, Field.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.
width
- Amount of available horizontal space.height
- Amount of available vertical space.protected void makeContextMenu(ContextMenu contextMenu)
Field.getContextMenu()
invokes this method to construct this field's
context menu.
contextMenu
- Context menu to build.ContextMenu
protected void onMenuDismissed(Menu menu)
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).
menu
- Menu to be dismissedprotected void onMenuDismissed()
protected int moveFocus(int amount, int status, int time)
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
Field.focusRemove()
. After invoking this method, the framework invokes
Field.focusAdd(boolean)
.
This method also clears this field's muddy state.
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.
protected void moveFocus(int x, int y, int status, int time)
This method is called by the framework only when the field already has focus.
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.protected void onFocus(int direction)
The method will not be invoked if this field already has focus. Also,
it will not be invoked if this field returns false from
Field.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:
direction
- Indicates from which direction the focus enters the
field.protected void onUnfocus()
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.
protected abstract void paint(Graphics graphics)
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 required to satisfy 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.
graphics
- Graphics context for drawing in this field.public final Background getBackground()
Field.setBackground(Background)
,
{@link #setBackground(int, Background) will override the existing theme background.
Returns null if no custom or theme background exists.
public final Background getBackground(int visual)
Field.setBackground(Background)
,
{@link #setBackground(int, Background) will override the existing theme background.
Returns null if no custom or theme background exists.
visual
- Visual state associated with background: Field.VISUAL_STATE_NORMAL
,
Field.VISUAL_STATE_ACTIVE
, Field.VISUAL_STATE_FOCUS
, Field.VISUAL_STATE_DISABLED
,
Field.VISUAL_STATE_DISABLED_FOCUS
.
IllegalArgumentException
- If visual
is an invalid visual state.public final void setBackground(Background background)
background
- Background object display, null to use default theme background.public final void setBackground(int visual, Background background)
background
- Background object display, null to use default theme background.visual
- Visual state associated with background: Field.VISUAL_STATE_NORMAL
,
Field.VISUAL_STATE_ACTIVE
, Field.VISUAL_STATE_FOCUS
, Field.VISUAL_STATE_DISABLED
,
Field.VISUAL_STATE_DISABLED_FOCUS
.
IllegalArgumentException
- If visual
is an invalid visual state.public boolean paste(Clipboard cb)
By default, this method returns false; custom fields that support paste operations must override this method.
cb
- Clipboard object containing data to paste.
protected final void setExtent(int width, int height)
The field calls this method during layout to set its extent (height and width).
width
- Width of the field.height
- Height of the field.public void setFont(Font font)
font
- New font for this field.protected final void setPosition(int x, int y)
This field's manager calls this method during layout to place this field within the manager's plane.
x
- Offset of the left of the field in its manager.y
- Offset of the top of the field in its manager.protected final void updateLayout()
Invoke this method when a change is made to a field that requires its extent to change. If the field is currently laid out in a screen, the appropriate updates are made to reflect the new field size.
public void select(boolean enable) throws IllegalStateException
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.
enable
- True to enable selection mode, false to disable it.
IllegalStateException
- If this field is not selectable.public void selectionCopy(Clipboard cb) throws IllegalStateException
By default, this method returns false; custom fields that support copy operations must override this method.
cb
- Clipboard object to use.
IllegalStateException
- If invalid clipboard object.public void selectionCut(Clipboard cb) throws IllegalStateException
By default, this method returns false; custom fields that support cut operations must override this method.
cb
- Clipboard object to use.
IllegalStateException
- If invalid clipboard object.public void selectionDelete()
By default, this method does nothing; custom fields that support deletion operations must override this method.
Field.isSelectionDeleteable()
,
Field.selectionCut(net.rim.device.api.system.Clipboard)
public void setBorder(Border border)
border
- Border object to display, null to use default theme border.public void setBorder(Border border, boolean updateLayout)
border
- Border object to display, null to use default theme border.updateLayout
- Flag to indicate whether to update the field's layout.public void setBorder(int visual, Border border)
visual
- Visual state associated with background: Field.VISUAL_STATE_NORMAL
,
Field.VISUAL_STATE_ACTIVE
, Field.VISUAL_STATE_FOCUS
,
Field.VISUAL_STATE_DISABLED
, Field.VISUAL_STATE_DISABLED_FOCUS
.border
- Border object to display, null to use default theme border.
IllegalArgumentException
- If visual
is an invalid visual state.public void setBorder(int visual, Border border, boolean updateLayout)
Setting the border to null
will reset it back to the default theme border.
Additionally, if the existing border has a background and if that background
has been set in the custom theme attribute set, then the background in the
custom theme attribute set is also reset to null
.
visual
- Visual state associated with background: Field.VISUAL_STATE_NORMAL
,
Field.VISUAL_STATE_ACTIVE
, Field.VISUAL_STATE_FOCUS
,
Field.VISUAL_STATE_DISABLED
, Field.VISUAL_STATE_DISABLED_FOCUS
.border
- Border object to display, null to use default theme border.updateLayout
- Flag to indicate whether to update the field's layout.
IllegalArgumentExsetThemeAttributeSetception
- If visual
is an invalid visual state.public void setChangeListener(FieldChangeListener listener)
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.
listener
- The object to listen for field changes.
IllegalStateException
- When there is already a listener set and
provided parameter is not null.public final void setCookie(Object cookie)
A cookie is an arbitrary object stored in association with a field. Applications may use it to store extra information about this field.
Use Field.getCookie()
to retrieve this field's cookie.
cookie
- Object associated with this field.public void setDirty(boolean dirty)
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).
dirty
- Specify true if the field is dirty; otherwise, specify false
to set the field to clean.Field.isDirty()
,
Field.setMuddy(boolean)
public void setEditable(boolean editable)
This method lets you change the style of this field by either adding,
or removing, the Field.EDITABLE
style.
editable
- If True, make this field editable; otherwise, make this
field non-editable.public void setFocus()
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 manager's first field.
If this field already has the focus, invoking this method has no effect.
IllegalStateException
- If the field is not attached to a screen.public void setFocusListener(FocusChangeListener listener)
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.
listener
- The object to listen for focus changes.
IllegalStateException
- When there is already a listener set and
provided parameter is not null.public void setMuddy(boolean muddy)
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.
muddy
- True if this field should be made muddy and dirty; false to
un-muddy this field.Field.isMuddy()
,
Field.setDirty(boolean)
public void setNonSpellCheckable(boolean nonSpellCheckable)
Any external module (like model or application) can use this method to assign this field with the spellcheckable style.
nonSpellCheckable
- If false make this field
Field.SPELLCHECKABLE
; otherwise, make it
Field.NON_SPELLCHECKABLE
.Field.isSpellCheckable()
public final void setVisualState(int visual)
Field.getVisualState()
.
visual
- One of the following visual states: Field.VISUAL_STATE_NORMAL
,
Field.VISUAL_STATE_ACTIVE
, Field.VISUAL_STATE_FOCUS
,
Field.VISUAL_STATE_DISABLED
, Field.VISUAL_STATE_DISABLED_FOCUS
.protected boolean touchEvent(TouchEvent message)
message
- TouchEvent
object containing various input parameters
including the event type and touch coordinates.
protected boolean navigationClick(int status, int time)
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.
status
- Bitfield of values defined by KeypadListener
.time
- Number of milliseconds since the device was turned on.
protected boolean navigationUnclick(int status, int time)
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.
status
- Bitfield of values defined by KeypadListener
.time
- Number of milliseconds since the device was turned on.
protected boolean navigationMovement(int dx, int dy, int status, int time)
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.
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.
protected boolean trackwheelClick(int status, int time)
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.
status
- Bitfield of values defined by KeypadListener
.time
- Number of milliseconds since the device was turned on.
protected boolean trackwheelUnclick(int status, int time)
The system invokes this method when passing on a trackwheel release event.
status
- Bitfield of values defined by KeypadListener
.time
- Number of milliseconds since the device was turned on.
protected void onVisibilityChange(boolean visible)
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 Field.isVisible()
, for example,
this method may be called with visible as false, but isVisible still
returns true.
visible
- True if the field has just become visible; otherwise,
false.Screen.onDisplay()
,
Screen.onExposed()
,
Screen.onObscured()
,
Screen.onUiEngineAttached(boolean)
protected void onDisplay()
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 #onUiEngineAttached
.
protected void onUndisplay()
The complementing callback is Field.onDisplay()
.
protected void onExposed()
The complementing callback is Field.onObscured()
.
protected void onObscured()
The complementing callback is Field.onExposed()
.
public AccessibleContext getAccessibleContext()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.