|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.ui.Field
net.rim.device.api.ui.component.DateField
public class DateField
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.
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 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 java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final int DATE
public static final int TIME
public static final int DATE_TIME
Constructor Detail |
---|
public DateField()
This builds a date field with no label, no initial value, in the default style.
public DateField(String label, long date, long 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
.
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.
IllegalArgumentException
- If you provide an unknown style, or a style
from which a date format cannot be inferred (see description).public DateField(String label, long date, DateFormat 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.
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.public DateField(String label, long date, long style, DateFormat 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.
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.
IllegalArgumentException
- If you provide an unknown style (see description).public DateField(String label, long date, int style, DateFormat 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.
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.
IllegalArgumentException
- If you provide an unknown style (see description).public DateField(String label, long date, DateFormat format, long style)
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.
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.
IllegalArgumentException
- If you provide an unknown style (see description).Method Detail |
---|
protected void drawFocus(Graphics graphics, boolean on)
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).
drawFocus
in class Field
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.protected int getCurrentSubfield()
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.
public long getDate()
This method returns the number of milliseconds since the epoch (midnight Jan 1, 1970) represented by this field's date.
Long.MIN_VALUE
.public String getLabel()
public int getMode()
This method returns the field's current mode, inferred from the format of its contained value.
DateFormat
,
DateField.DateField(String,long,DateFormat)
public int getPreferredWidth()
Field.getPreferredWidth()
for more information.
Managers make use of this value during layout.
getPreferredWidth
in class Field
public int getPreferredHeight()
Field.getPreferredHeight()
for more information.
getPreferredHeight
in class Field
public TimeZone getTimeZone()
public boolean isSelectionCopyable()
isSelectionCopyable
in class Field
protected boolean keyChar(char key, int status, int time)
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.
keyChar
in class Field
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.
protected boolean keyControl(char key, int status, int time)
keyControl
in class Field
key
- Character generated by the event.status
- State of the modifier keys.time
- Number of milliseconds since the device was turned on.
protected boolean keyStatus(int keycode, int time)
This method traps ALT-key events; other status key events are not consumed.
keyStatus
in class Field
keycode
- Code of status key.time
- Number of milliseconds since the device was turned on.
protected boolean invokeAction(int action)
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.
invokeAction
in class Field
action
- the action to be performed on this field.
true
if the action was consumed; false
if the action was not consumed.protected void layout(int width, int height)
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.
layout
in class Field
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.
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.
makeContextMenu
in class Field
contextMenu
- Context menu to build.ContextMenu
protected int moveFocus(int amount, int status, int time)
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).
moveFocus
in class Field
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.
public void getFocusRect(XYRect rect)
getFocusRect
in class Field
rect
- Object to contain the focus rect for this field in local
coordinates.protected void onFocus(int direction)
This field's manager invokes this method when this field newly receives the focus.
onFocus
in class Field
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).protected void paint(Graphics graphics)
This field's manager invokes this method during the repainting process to instruct this field to repaint itself.
paint
in class Field
graphics
- Graphics context for repainting this field.public void selectionCopy(Clipboard cb)
selectionCopy
in class Field
cb
- Clipboard object to contain the clipped value from this field.public void setDate(long date)
If your parameter is equal to Long.MIN_VALUE
, this method
removes the date value from this field (sets it to null).
date
- New date value for this field.protected void setDate(long date, int context)
If your parameter is equal to Long.MIN_VALUE
, this method
removes the date value from this field (sets it to null).
date
- New date value for this field.context
- Information specifying the origin of the change.public void setDate(Date date)
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).
date
- Reference date object from which to set this field's value.protected void setDate(Date date, int context)
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).
date
- Reference date object from which to set this field's value.context
- Information specifying the origin of the change.public void setEditable(boolean editable)
setEditable
in class Field
editable
- If true, this field becomes editable; otherwise, this
field becomes read only.public void setFormat(DateFormat format)
format
- Date format to use for this field.public void setLabel(String label)
label
- Label for this field.public void setMinuteIncrements(long minuteIncrements)
minuteIncrements
- Minute increments in milliseconds.public void setTimeZone(TimeZone tz)
tz
- New timezone for this field.
NullPointerException
- If timezone parameter is null.public String toString()
toString
in class Object
public AccessibleContext getAccessibleContext()
getAccessibleContext
in class Field
|
|||||||||
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.