net.rim.device.api.ui.component
Class DateField

java.lang.Object
  net.rim.device.api.ui.Field
      net.rim.device.api.ui.component.DateField

All Implemented Interfaces:

DrawStyle

public class DateField
extends Field
implements DrawStyle

Stores date and time values.

Note: the DateFormat object supports setting the current timezone.

Behaviour
Displays a label followed by a date.

If created with DateField.DATE mode, this field only displays the date component of the currently set value.

If created with DateField.DATE_TIME mode, this field displays the date and time of the currently set value.

If created with DateField.TIME mode, this field only displays the time component of the currently set value.

If created in Field.EDITABLE mode, each supported part acts as a focus position and can be edited. The text values behave like a ChoiceField (eg. months, weekdays). The numeric portions behave a bit like a choice field, a bit like an edit field: ALT+roll increases or decreases the value as with a choice field; typing appends the new digit and throws away as many digits at the start as it must to make the number valid again.

If the user rolls over the bounds of the range, the excess carries over to the other fields (for example increasing the day of month one starting from Jan 31, 2001 results in Feb 1, 2001).

The field also adds a menu item to change its value. When invoked, a dialog appears in which one can use the trackwheel to change the date without holding the ALT key. The entire date is shown, but only the current field is selected and editable. This dialog supports the same carry-over effect as the base control. Pressing ENTER or clicking dismisses the dialog and changes the choice. Pressing ESCAPE dismisses the dialog and cancels the change. Other keys work as defined above.

If created in Field.READONLY mode, this field supports only one focus position and the entire date portion becomes highlighted.

See Also:

DateTimePicker

Field Summary
static int	DATE Input mode for date (year, month, day).
static int	DATE_TIME Input mode for date and time (year, month, day, hour, minute, second).
static int	TIME Input mode for time (hour, minute, second).

Fields inherited from class net.rim.device.api.ui.Field

ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL

Fields inherited from interface net.rim.device.api.ui.DrawStyle

BASELINE, BOTTOM, ELLIPSIS, HALIGN_MASK, HCENTER, HDEFAULT, HFULL, LEADING, LEFT, RIGHT, TOP, TRAILING, TRUNCATE_BEGINNING, VALIGN_MASK, VCENTER, VDEFAULT, VFULL

Constructor Summary

DateField()
Constructs a new DateField instance.

DateField(String label, long date, int style, DateFormat format)
Deprecated.

DateField(String label, long date, long style)
Constructs a new DateField instance with label, initial value, and style.

DateField(String label, long date, long style, DateFormat format)
Deprecated.

DateField(String label, long date, DateFormat format)
Constructs a new DateField instance with label, initial value, and format.

DateField(String label, long date, DateFormat format, long style)
Constructs a new DateField instance with label, initial value, style, and format.

Method Summary
protected void	drawFocus(Graphics graphics, boolean on) Draws the focus at the current cursor position.
AccessibleContext	getAccessibleContext() Returns accessible representation of the field for a screen reader.
protected int	getCurrentSubfield() Gets the current field with the focus within the date field.
long	getDate() Retrieves the absolute value of this field in ticks.
void	getFocusRect(XYRect rect) Override Field.getFocusRect().
String	getLabel() Retrieves this field's label.
int	getMode() Retrieves this field's mode.
int	getPreferredHeight() Retrieves this field's preferred height.
int	getPreferredWidth() Retrieves this field's preferred width.
TimeZone	getTimeZone() Retrieves this field's set timezone.
protected boolean	invokeAction(int action) Invokes an action on this field.
boolean	isSelectionCopyable() Determines if this field is copyable.
protected boolean	keyChar(char key, int status, int time) Traps key events when modifying this field.
protected boolean	keyControl(char key, int status, int time) Special handling for control character events.
protected boolean	keyStatus(int keycode, int time) Handles key status events.
protected void	layout(int width, int height) Lays out this field's 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	onFocus(int direction) Invoked upon receiving the focus.
protected void	paint(Graphics graphics) Redraws this field.
void	selectionCopy(Clipboard cb) Copies this field's contents to the clipboard.
void	setDate(Date date) Sets the date for this field from date object.
protected void	setDate(Date date, int context) Sets the date for this field from date object.
void	setDate(long date) Sets the date for this field from long integer value.
protected void	setDate(long date, int context) Sets the date for this field from long integer value.
void	setEditable(boolean editable) Sets editable state of this field.
void	setFormat(DateFormat format) Sets the display format for this field.
void	setLabel(String label) Sets the text label for this field.
void	setMinuteIncrements(long minuteIncrements) Sets the interval for which scrolling increments/decrements the minute field.
void	setTimeZone(TimeZone tz) Set the timezone for this field.
String	toString() Retrieves a string version of this field.

Methods inherited from class net.rim.device.api.ui.Field

drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isMuddy, isPasteable, isScrollCopyable, isSelectable, isSelecting, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyDown, keyRepeat, keyUp, moveFocus, navigationClick, navigationMovement, navigationUnclick, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onUnfocus, onVisibilityChange, paste, select, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEnabled, setExtent, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, touchEvent, trackwheelClick, trackwheelUnclick, updateLayout

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DATE

public static final int DATE

Input mode for date (year, month, day).

See Also:

Constant Field Values

TIME

public static final int TIME

Input mode for time (hour, minute, second).

See Also:

Constant Field Values

DATE_TIME

public static final int DATE_TIME

Input mode for date and time (year, month, day, hour, minute, second).

See Also:

Constant Field Values

Constructor Detail

DateField

public DateField()

Constructs a new DateField instance.

This builds a date field with no label, no initial value, in the default style.

DateField

public DateField(String label,
                 long date,
                 long style)

Constructs a new DateField instance with label, initial value, and style.

This builds a date field, inferring the required date format for this field from the style parameter you provide. Thus, at the very least, style must include one of DateField.DATE, DateField.TIME, or DateField.DATE_TIME.

Parameters:

label - Label for this field.

date - Initial date value for this field. This is the number of milliseconds since January 1st 1970 midnight. To create an empty date field, set this parameter to Long.MIN_VALUE. The method will then remove the date value from this field, setting it to null.

style - Input mode/date format for this field.

Throws:

IllegalArgumentException - If you provide an unknown style, or a style from which a date format cannot be inferred (see description).

DateField

public DateField(String label,
                 long date,
                 DateFormat format)

Constructs a new DateField instance with label, initial value, and format.

This builds a date field, inferring the required style for this field from the format parameter you provide. If the date format you provide specifies only date, then this method builds a field in DateField.DATE mode; if the date format specifies only time, the field is built in DateField.TIME mode; if the date format specifies both date and time values, the field is built in DateField.DATE_TIME mode.

Parameters:

label - Label for this field.

date - Initial date value for this field. This is the number of milliseconds since January 1st 1970 midnight. To create an empty date field, set this parameter to Long.MIN_VALUE. The method will then remove the date value from this field, setting it to null.

format - Date format object specifying how this field's value looks.

DateField

public DateField(String label,
                 long date,
                 long style,
                 DateFormat format)

Deprecated.

Constructs a new DateField instance with label, initial value, style, and format.

This builds a date field, inferring the required style for this field from the format parameter you provide. If the date format you provide specifies only date, then this method builds a field in DateField.DATE mode; if the date format specifies only time, the field is built in DateField.TIME mode; if the date format specifies both date and time values, the field is built in DateField.DATE_TIME mode.

Parameters:

label - Label for this field.

date - Initial date value for this field. This is the number of milliseconds since January 1st 1970 midnight. To create an empty date field, set this parameter to Long.MIN_VALUE. The method will then remove the date value from this field, setting it to null.

style - Input mode for this field.

format - Date format object specifying how this field's value looks.

Throws:

IllegalArgumentException - If you provide an unknown style (see description).

Since:

BlackBerry API 4.0.2

DateField

public DateField(String label,
                 long date,
                 int style,
                 DateFormat format)

Deprecated.

Constructs a new DateField instance with label, initial value, style, and format.

This builds a date field, inferring the required style for this field from the format parameter you provide. If the date format you provide specifies only date, then this method builds a field in DateField.DATE mode; if the date format specifies only time, the field is built in DateField.TIME mode; if the date format specifies both date and time values, the field is built in DateField.DATE_TIME mode.

Parameters:

label - Label for this field.

date - Initial date value for this field. This is the number of milliseconds since January 1st 1970 midnight. To create an empty date field, set this parameter to Long.MIN_VALUE. The method will then remove the date value from this field, setting it to null.

style - Input mode for this field.

format - Date format object specifying how this field's value looks.

Throws:

IllegalArgumentException - If you provide an unknown style (see description).

Since:

BlackBerry API 4.0.2

DateField

public DateField(String label,
                 long date,
                 DateFormat format,
                 long style)

Constructs a new DateField instance with label, initial value, style, and format.

This builds a date field, inferring the required style for this field from the format parameter you provide. If the date format you provide specifies only date, then this method builds a field in DateField.DATE mode; if the date format specifies only time, the field is built in DateField.TIME mode; if the date format specifies both date and time values, the field is built in DateField.DATE_TIME mode.

Parameters:

label - Label for this field.

date - Initial date value for this field. This is the number of milliseconds since January 1st 1970 midnight. To create an empty date field, set this parameter to Long.MIN_VALUE. The method will then remove the date value from this field, setting it to null.

style - Input mode for this field.

format - Date format object specifying how this field's value looks.

Throws:

IllegalArgumentException - If you provide an unknown style (see description).

Since:

BlackBerry API 4.0.0

Method Detail

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)

Draws the focus at the current cursor position.

This method draws the focus at the current cursor position: all the pixels under the current cursor become inverted (if the cursor is not sitting over a character, it appears as a black rectangle).

Overrides:

drawFocus in class Field

Parameters:

graphics - Graphics context for the paint operation.

on - This parameter ignored; the focus is always considered set on the cursor, if the cursor is set on this field.

getCurrentSubfield

protected int getCurrentSubfield()

Gets the current field with the focus within the date field.

The default return value is the first subfield. For example, if the format is "HH:mm", the return would be HOUR_OF_DAY. Note that DateFormat.XX_FIELD == Calendar.XX where XX is YEAR, MONTH, DATE, HOUR, HOUR_OF_DAY, etc.

A different value is returned every time focus is changed. This is done either through user action, or as a result of changing the current format (in which case this value is clamped to the bounds of the new format).

This method returns the DateFormat *_FIELD constant corresponding to the user's current position within this date field.

On touch screen Blackberry devices this method works on the sub block level of the date field. This change is motivated by low precision of finger touches that may cover several date components simultaneously. Therefore, several neighboring date components are collected into two sub blocks: 1) date and 2) time. These blocks are large enough to guarantee precise selection. Clicking on a sub block brings up the dialog window with larger view of the date components within selected sub block. Only within this dialog it is reasonable to invoke getCurrentSubfield method to get current date component which holds the focus within the date field.

Returns:

The current field with the focus.

getDate

public long getDate()

Retrieves the absolute value of this field in ticks.

This method returns the number of milliseconds since the epoch (midnight Jan 1, 1970) represented by this field's date.

Returns:

If time is represented in this field, returns a value between 0 and (24*60*60*1000). In the TIME mode any long value outside the range specified can be set and returned afterwards by the getDate() method. If this field's value is unspecified, returns Long.MIN_VALUE.

getLabel

public String getLabel()

Retrieves this field's label.

Returns:

Label string for this field.

getMode

public int getMode()

Retrieves this field's mode.

This method returns the field's current mode, inferred from the format of its contained value.

See Also:

DateFormat, DateField.DateField(String,long,DateFormat)

getPreferredWidth

public int getPreferredWidth()

Retrieves this field's preferred width. See Field.getPreferredWidth() for more information.

Managers make use of this value during layout.

Overrides:

getPreferredWidth in class Field

Returns:

Preferred width for the field.

Since:

BlackBerry API 3.6.0

getPreferredHeight

public int getPreferredHeight()

Retrieves this field's preferred height. See Field.getPreferredHeight() for more information.

Overrides:

getPreferredHeight in class Field

Returns:

Preferred height for this field.

Since:

BlackBerry API 4.0.0

getTimeZone

public TimeZone getTimeZone()

Retrieves this field's set timezone.

Returns:

Timezone value for this field.

isSelectionCopyable

public boolean isSelectionCopyable()

Determines if this field is copyable.

Overrides:

isSelectionCopyable in class Field

Returns:

True (date fields are always copyable).

keyChar

protected boolean keyChar(char key,
                          int status,
                          int time)

Traps key events when modifying this field.

This method handles and consumes a key generation event, only if this field is Field.EDITABLE; otherwise, it does nothing and does not consume the event.

If the key generated was a SPACE character, this method increments the current date component to the next value as if it were a choice field. (That is, pressing the space bar on the "Tuesday" field component switches the value to "Wednesday"; pressing the space bar on a "1" field component switches the value to "2".)

If the key generated was a numeric character, and the current field component is a numeric value, this method appends the new digit to the field's value and then throws away as many digits at the start as it must to make the number a valid value again.

If the key generated was a character, and the current field component is a string value, this method behaves like a choice field: it seeks to the next string in the choice list that starts with the letter typed (or does nothing, if no value in the choice list starts with the letter typed).

On SureTypeŽ BlackBerry devices, if the key generated was a space character, the DateField is modified as if the '0' key is pressed. If the key generated was the '0' numeric character, the DateField is modified as if the space character was pressed - the value of the DateField is incremented.

Numeric keys generated do nothing in string components.

If an Alpha letter key is generated, this method handles the key as if it were a numeric key: the key is translated by Keypad.getAltedChar(key) into a numeric key.

If the key generated was ENTER, this method removes focus from this field, accepting the currently changed value. If the key generated was ESCAPE, this method leaves the field untouched and passes the escape event on.

The keyChar method has two implementation differences with regards to touch screen Blackberry devices with virtual keyboard:

1) keyChar traps key events from the virtual keyboard.

2) This method handles and consumes key generation events only on so called "sub block" level. This functionality is motivated by low precision of finger touches that may cover several date components simultaneously. Therefore, several neighboring date components are collected into two sub blocks: 1) date and 2) time. These blocks are large enough to guarantee precise selection. Clicking on a sub block brings up the dialog window with larger view of the date components within selected sub block. In this dialog each date component can be selected individually and then modified by the keyChar method.

Note: This method does not modify the time zone field.

Overrides:

keyChar in class Field

Parameters:

key - Character generated by the event.

status - State of the modifier keys (this parameter is ignored).

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

Returns:

True if this event was consumed; otherwise, false.

keyControl

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

Special handling for control character events.

Overrides:

keyControl in class Field

Parameters:

key - Character generated by the event.

status - State of the modifier keys.

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

Returns:

True if this event was consumed; otherwise, false.

Since:

BlackBerry API 3.6.0

keyStatus

protected boolean keyStatus(int keycode,
                            int time)

Handles key status events.

This method traps ALT-key events; other status key events are not consumed.

Overrides:

keyStatus in class Field

Parameters:

keycode - Code of status key.

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

Returns:

True if event was consumed; otherwise, false.

Since:

BlackBerry API 3.6.0

invokeAction

protected boolean invokeAction(int action)

Invokes an action on this field. The only action that is recognized by this method is Field.ACTION_INVOKE, which opens this field to have its value changed by the user.

If action is not a recognized action then this method does nothing and returns false, indicating that the action was not consumed.

Note that if this field is not editable (ie. Field.isEditable() returns false) then the action will not be consumed.

Overrides:

invokeAction in class Field

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:

BlackBerry API 4.2.0

layout

protected void layout(int width,
                      int height)

Lays out this field's contents.

This field's manager invokes this method during the layout process to instruct this field to arrange its contents, given an amount of available space.

Specified by:

layout in class Field

Parameters:

width - Amount of available horizontal space.

height - Amount of available vertical space.

makeContextMenu

protected void makeContextMenu(ContextMenu contextMenu)

Builds this field's context menu.

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

If UiInternal.getShouldShowChangeOptionMenuItem() returns true and this field is Field.EDITABLE, this method builds this field's context menu adding a menu item for changing this field's value.

Overrides:

makeContextMenu in class Field

Parameters:

contextMenu - Context menu to build.

See Also:

ContextMenu

moveFocus

protected int moveFocus(int amount,
                        int status,
                        int time)

Handles moving the focus within this field.

This field's manager invokes this method only when this field already has the focus.

If this field is Field.EDITABLE, then this method handles the case where the user ALT-rolls the trackwheel (trapping the events to move to the next or subsequent choices in each field component's list of values, depending on the roll amount passed in to this method).

If the user is not ALT-rolling the trackwheel, then this method moves the focus to the next (or previous) component in this field (once again, depending on the amount rolled).

Overrides:

moveFocus in class Field

Parameters:

amount - Number of positions to move, positive means downwards (or forwards through this field's components), negative means upwards (or backwards through this field's components).

status - Modifier key state: if STATUS_ALT, then this method uses the movement to change the value of this field's currently selected component; otherwise, the movement is used to move the focus between this field's components.

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

Returns:

Remaining scroll amount not used up. If the trackwheel is being ALT-rolled, then this method always returns 0 (that is, this method consumes all the trackwheel movement); otherwise, once this method either consumes all the movement or reaches its first (or last) component, it passes back the remaining movement.

getFocusRect

public void getFocusRect(XYRect rect)

Override Field.getFocusRect().

Overrides:

getFocusRect in class Field

Parameters:

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

Since:

BlackBerry API 4.1.0, 4.1

onFocus

protected void onFocus(int direction)

Invoked upon receiving the focus.

This field's manager invokes this method when this field newly receives the focus.

Overrides:

onFocus in class Field

Parameters:

direction - If 1, the focus came from the previous field; if -1, the focus came from the subsequent field; if 0, the focus was set directly (not as a result of trackwheel movement).

paint

protected void paint(Graphics graphics)

Redraws this field.

This field's manager invokes this method during the repainting process to instruct this field to repaint itself.

Specified by:

paint in class Field

Parameters:

graphics - Graphics context for repainting this field.

selectionCopy

public void selectionCopy(Clipboard cb)

Copies this field's contents to the clipboard.

Overrides:

selectionCopy in class Field

Parameters:

cb - Clipboard object to contain the clipped value from this field.

setDate

public void setDate(long date)

Sets the date for this field from long integer value.

If your parameter is equal to Long.MIN_VALUE, this method removes the date value from this field (sets it to null).

Parameters:

date - New date value for this field.

setDate

protected void setDate(long date,
                       int context)

Sets the date for this field from long integer value.

If your parameter is equal to Long.MIN_VALUE, this method removes the date value from this field (sets it to null).

Parameters:

date - New date value for this field.

context - Information specifying the origin of the change.

setDate

public void setDate(Date date)

Sets the date for this field from date object.

Given a date object, this method sets this field's date value to the same as contained in the date object. If your provided date object is null, this method removes the date value from this field (sets it to null).

Parameters:

date - Reference date object from which to set this field's value.

setDate

protected void setDate(Date date,
                       int context)

Sets the date for this field from date object.

Given a date object, this method sets this field's date value to the same as contained in the date object. If your provided date object is null, this method removes the date value from this field (sets it to null).

Parameters:

date - Reference date object from which to set this field's value.

context - Information specifying the origin of the change.

setEditable

public void setEditable(boolean editable)

Sets editable state of this field.

Overrides:

setEditable in class Field

Parameters:

editable - If true, this field becomes editable; otherwise, this field becomes read only.

setFormat

public void setFormat(DateFormat format)

Sets the display format for this field.

Parameters:

format - Date format to use for this field.

setLabel

public void setLabel(String label)

Sets the text label for this field.

Parameters:

label - Label for this field.

setMinuteIncrements

public void setMinuteIncrements(long minuteIncrements)

Sets the interval for which scrolling increments/decrements the minute field.

Parameters:

minuteIncrements - Minute increments in milliseconds.

Since:

BlackBerry API 4.0.0

setTimeZone

public void setTimeZone(TimeZone tz)

Set the timezone for this field.

Parameters:

tz - New timezone for this field.

Throws:

NullPointerException - If timezone parameter is null.

toString

public String toString()

Retrieves a string version of this field.

Overrides:

toString in class Object

Returns:

String representation of the contents of this field, formatted using the mode or formatter set on this field.

getAccessibleContext

public AccessibleContext getAccessibleContext()

Returns accessible representation of the field for a screen reader.

Overrides:

getAccessibleContext in class Field

Returns:

AccessibleContext instance

Since:

BlackBerry API 4.6.1