SHOW Framework
 

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:
AccessibleContext, DrawStyle, FieldLabelProvider, IComponent, InputMethodListener

public class DateField
extends Field
implements DrawStyle, FieldLabelProvider

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 DATE mode, this field only displays the date component of the currently set value.

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

If created with 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.


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, 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, 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.
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.  
 
Method Summary
  protected  void drawFocus(Graphics graphics, boolean on)
          Draws the focus at the current cursor position.
  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.
 Category: Framework 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, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, isDataValid, isDirty, isEditable, isFocus, isFocusable, isMuddy, isPasteable, isSelectable, isSelecting, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyDown, keyRepeat, keyUp, navigationClick, navigationMovement, navigationUnclick, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onUnfocus, onVisibilityChange, paste, select, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCookie, setDirty, setExtent, setFocus, setFocusListener, setFont, setMuddy, setNonSpellCheckable, setPosition, setVisualState, 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).

DATE_TIME

public static final int DATE_TIME
Input mode for date and time (year, month, day, hour, minute, second).

TIME

public static final int TIME
Input mode for time (hour, minute, second).
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,
                 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 DATE mode; if the date format specifies only time, the field is built in TIME mode; if the date format specifies both date and time values, the field is built in DATE_TIME mode.

Parameters:
label - Label for this field.
date - Initial date value for this field. 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,
                 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 DATE mode; if the date format specifies only time, the field is built in TIME mode; if the date format specifies both date and time values, the field is built in DATE_TIME mode.

Parameters:
label - Label for this field.
date - Initial date value for this field. 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:
JDE 4.0.0

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 DATE mode; if the date format specifies only time, the field is built in TIME mode; if the date format specifies both date and time values, the field is built in DATE_TIME mode.

Parameters:
label - Label for this field.
date - Initial date value for this field. 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:
JDE 4.0.2

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 DATE, TIME, or DATE_TIME.

Parameters:
label - Label for this field.
date - Initial date value for this field. 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,
                 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 DATE mode; if the date format specifies only time, the field is built in TIME mode; if the date format specifies both date and time values, the field is built in DATE_TIME mode.

Parameters:
label - Label for this field.
date - Initial date value for this field. 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:
JDE 4.0.2
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.

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.

getFocusRect

public void getFocusRect(XYRect rect)
Override Field.getFocusRect().
Overrides:
getFocusRect in class Field
Since:
4.1

Following copied from class: Field
Parameters:
rect - Object to contain the focus rect for this field in local coordinates.

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(String,long,DateFormat)

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

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

getTimeZone

public TimeZone getTimeZone()
Retrieves this field's set timezone.
Returns:
Timezone value for this field.

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

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.

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

Overrides:
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 the UI is not operating in MODE_ADVANCED mode, this method builds this field's context menu adding a menu item for changing this field's value.

Overrides:
makeContextMenu in class Field

Following copied from 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.

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.

Overrides:
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(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.

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.

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



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