|
|||||||||
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
time zone.
Behavior
This class displays a label followed by a date.
If created with the DateField.DATE
mode, this field displays only the date
component of the currently set value.
If created with the DateField.DATE_TIME
mode, this field displays the date
and time of the currently set value.
If created with the DateField.TIME
mode, this field displays only the time
component of the currently set value.
If created in Field.EDITABLE
mode, each supported component of this
field acts as a focus position and can be edited. A text component,
such as the month or day of the week, behaves like a ChoiceField
. A
numeric component behaves like a combination of a choice field and an edit
field. If a BlackBerry device user holds the ALT key and rolls the trackwheel
or trackball, the value increases or decreases, similar to a choice field. If
the user types a number, the new digit is appended to the current value and
digits at the start of the value are removed to make the number valid. On
devices with a touch screen, pressing the ALT key opens a dialog box to
change the value of the field, as described below.
If the user rolls over the bounds of the range of allowed values for a component, the excess carries over to the other fields. For example, if the current date is Jan 31, 2001, increasing the day by one results in a date of Feb 1, 2001.
This field also adds a menu item to change its value. When invoked, a dialog box appears in which the user can use the trackwheel or trackball, or swipe a finger vertically on the screen on devices with a touch screen, 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 box supports the same carryover effect as the base field. Pressing the ENTER key or clicking OK dismisses the dialog box and accepts the changes. Pressing the ESCAPE key or clicking CANCEL dismisses the dialog box and cancels the changes. Other keys work as defined above.
If created in Field.READONLY
mode, this field supports only one focus
position and the entire field becomes highlighted.
DateTimePicker
Field Summary | ||
---|---|---|
static int |
DATE
Specifies the input mode for date (year, month, day). |
|
static int |
DATE_TIME
Specifies the input mode for date and time (year, month, day, hour, minute, second). |
|
static int |
FOCUS_MOVE_ON_HORIZONTAL_SCROLL
Specifies that horizontal scrolling at the extents of the field moves the focus to the next or previous field by the amount scrolled. |
|
static int |
TIME
Specifies the 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 the specified
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 the specified
label, initial value, and format. |
||
DateField(String label,
long date,
DateFormat format,
long style)
Constructs a new DateField instance with the specified
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 an accessible representation of the field for a screen reader. |
|
protected int |
getCurrentSubfield()
Gets the current subfield that has the focus within the date field. |
|
long |
getDate()
Retrieves the absolute value of this field (in milliseconds). |
|
void |
getFocusRect(XYRect rect)
Retrieves this field's current focus region. |
|
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 the time zone that is set for this field. |
|
protected boolean |
invokeAction(int action)
Invokes an action on this field. |
|
boolean |
isSelectionCopyable()
Indicates whether 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)
Performs 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 using a Date object. |
|
protected void |
setDate(Date date,
int context)
Sets the date for this field using a Date object. |
|
void |
setDate(long date)
Sets the date for this field using a long integer value. |
|
protected void |
setDate(long date,
int context)
Sets the date for this field using a long integer value. |
|
void |
setEditable(boolean editable)
Sets the 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 or decrements the minute field. |
|
void |
setTimeZone(TimeZone tz)
Sets the time zone 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 FOCUS_MOVE_ON_HORIZONTAL_SCROLL
public static final int DATE_TIME
Constructor Detail |
---|
public DateField()
DateField
instance.
This builds a date field with no label and no initial value, using the default style.
public DateField(String label, long date, long style)
DateField
instance with the specified
label, initial value, and style.
This builds a date field, inferring the required date format for this
field from the style
parameter that you provide. Thus, at
the very least, style
must include one of DateField.DATE
,
DateField.TIME
, or DateField.DATE_TIME
.
label
- The label for this field.date
- The initial date value for this field. This is the number of
milliseconds since midnight on January 1, 1970. To create an empty date
field, set this parameter to Long.MIN_VALUE
. This method
will then remove the date value from this field, setting it to
null
.style
- The input mode and date format for this field.
IllegalArgumentException
- if style
specifies an
unknown style, or a style from which a date format cannot be inferred
(see description).public DateField(String label, long date, DateFormat format)
DateField
instance with the specified
label, initial value, and format.
This builds a date field, inferring the required style for this field
from the format
parameter that you provide. If the date
format that you provide specifies only a date value, then this method
builds a field in DateField.DATE
mode. If the date format specifies only a
time value, then this method builds a field in DateField.TIME
mode. If
the date format specifies both date and time values, then this method
builds a field in DateField.DATE_TIME
mode.
label
- The label for this field.date
- The initial date value for this field. This is the number of
milliseconds since midnight on January 1, 1970. To create an empty date
field, set this parameter to Long.MIN_VALUE
. This method
will then remove the date value from this field, setting it to
null
.format
- The date format that specifies how this field's value
appears.public DateField(String label, long date, long style, DateFormat format)
DateField
instance with the specified
label, initial value, style, and format.
This builds a date field, inferring the required style for this field
from the format
parameter that you provide. If the date
format that you provide specifies only a date value, then this method
builds a field in DateField.DATE
mode. If the date format specifies only a
time value, then this method builds a field in DateField.TIME
mode. If the
date format specifies both date and time values, then this method builds
a field in DateField.DATE_TIME
mode.
label
- The label for this field.date
- The initial date value for this field. This is the number of
milliseconds since midnight on January 1, 1970. To create an empty date
field, set this parameter to Long.MIN_VALUE
. This method
will then remove the date value from this field, setting it to
null
.style
- The input mode for this field.format
- The date format that specifies how this field's value
appears.
IllegalArgumentException
- if style
specifies an
unknown style (see description).public DateField(String label, long date, int style, DateFormat format)
DateField
instance with the specified
label, initial value, style, and format.
This builds a date field, inferring the required style for this field
from the format
parameter that you provide. If the date
format that you provide specifies only a date value, then this method
builds a field in DateField.DATE
mode. If the date format specifies only a
time value, then this method builds a field in DateField.TIME
mode. If the
date format specifies both date and time values, then this method builds
a field in DateField.DATE_TIME
mode.
label
- The label for this field.date
- The initial date value for this field. This is the number of
milliseconds since midnight on January 1, 1970. To create an empty date
field, set this parameter to Long.MIN_VALUE
. This method
will then remove the date value from this field, setting it to
null
.style
- The input mode for this field.format
- The date format that specifies how this field's value
appears.
IllegalArgumentException
- if style
specifies an
unknown style (see description).public DateField(String label, long date, DateFormat format, long style)
DateField
instance with the specified
label, initial value, style, and format.
This builds a date field, inferring the required style for this field
from the format
parameter that you provide. If the date
format that you provide specifies only a date value, then this method
builds a field in DateField.DATE
mode. If the date format specifies only a
time value, then this method builds a field in DateField.TIME
mode. If the
date format specifies both date and time values, then this method builds
a field in DateField.DATE_TIME
mode.
label
- The label for this field.date
- The initial date value for this field. This is the number of
milliseconds since midnight on January 1, 1970. To create an empty date
field, set this parameter to Long.MIN_VALUE
. This method
will then remove the date value from this field, setting it to
null
.format
- The date format that specifies how this field's value
appears.style
- The input mode for this field.
IllegalArgumentException
- if style
specifies 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 of the pixels under the current cursor become inverted. If the cursor is not positioned over a character, the pixels appear as a rectangular caret.
drawFocus
in class Field
graphics
- The graphics context for the paint operation.on
- This parameter is 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 value would be
Calendar.HOUR_OF_DAY
. Note that
DateFormat.XX_FIELD == Calendar.XX
, where XX
is
YEAR
, MONTH
, DATE
,
HOUR
, HOUR_OF_DAY
, and so on.
A different value is returned every time the focus changes. 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 BlackBerry devices with a touch screen, this method works on the
sub-block level of the date field. This change is motivated by the low
precision of finger touches that may cover several date components
simultaneously. Several neighboring date components are collected into
two sub-blocks: date and time. These sub-blocks are large enough to
guarantee precise selection. Clicking on a sub-block displays a dialog
box with a larger view of the date components within the selected
sub-block. Only within this dialog box is it reasonable to invoke
getCurrentSubfield()
to get the current date component that
has the focus within the date field.
public long getDate()
This method returns the number of milliseconds since the epoch (midnight on January 1, 1970) represented by this field's date.
DateField.TIME
mode, any long
value
outside the range specified can be set and returned afterwards by
getDate()
. If this field's value is unspecified, returns
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()
Managers make use of this value during layout. See
Field.getPreferredWidth()
for more
information.
getPreferredWidth
in class Field
public int getPreferredHeight()
Managers make use of this value during layout. See
Field.getPreferredHeight()
for more
information.
getPreferredHeight
in class Field
public TimeZone getTimeZone()
public boolean isSelectionCopyable()
isSelectionCopyable
in class Field
true
because date fields can always
be copied.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 BlackBerry devices with SureType technology, 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 the key generated was an alpha letter key, 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 the focus from this field, accepting the currently changed value. If the key generated was ESCAPE, this method leaves the field unchanged and passes the escape event on.
The keyChar
method has two implementation differences
with regards to BlackBerry devices with a touch screen and virtual
keyboard:
keyChar
.Note: This method does not modify the time zone field.
keyChar
in class Field
key
- The character that was generated by the event.status
- The state of the modifier keys. This parameter is ignored.time
- The number of milliseconds since the device was turned on.
true
if this event was consumed, false
otherwise.protected boolean keyControl(char key, int status, int time)
keyControl
in class Field
key
- The character that was generated by the event.status
- The state of the modifier keys.time
- The number of milliseconds since the device was turned on.
true
if this event was consumed, false
otherwise.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
- The code of the status key.time
- The number of milliseconds since the device was turned on.
true
if the event was consumed, false
otherwise.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: 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
- The amount of available horizontal space.height
- The 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 and adds a menu item for changing this field's
value.
makeContextMenu
in class Field
contextMenu
- The context menu for this field.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 holds the ALT key and 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
that is passed in to this method).
If the user is not holding the ALT key and 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
- The number of positions to move. Positive values mean
downwards (or forwards through this field's components), and negative
values mean upwards (or backwards through this field's components).status
- The 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
- The number of milliseconds since the device was turned on.
public void getFocusRect(XYRect rect)
Field.getFocusRect(net.rim.device.api.ui.XYRect)
.
getFocusRect
in class Field
rect
- The rect to populate with this field's current focus region.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
- The graphics context for repainting this field.public void selectionCopy(Clipboard cb)
selectionCopy
in class Field
cb
- The Clipboard
object to contain the clipped value
from this field.public void setDate(long date)
long
integer value.
If the specified parameter is equal to Long.MIN_VALUE
, then
this method removes the date value from this field (sets it to
null
).
date
- The new date value for this field.protected void setDate(long date, int context)
long
integer value.
If the specified parameter is equal to Long.MIN_VALUE
, then
this method removes the date value from this field (sets it to
null
).
date
- The new date value for this field.context
- Information specifying the origin of the change.public void setDate(Date date)
Date
object.
Given a Date
object, this method sets this field's date
value to the date that is contained in the Date
object. If
the specified Date
object is null
, this method
removes the date value from this field (sets it to null
).
date
- The Date
object from which to set this field's
value.protected void setDate(Date date, int context)
Date
object.
Given a Date
object, this method sets this field's date
value to the date that is contained in the Date
object. If
the specified Date
object is null
, this method
removes the date value from this field (sets it to null
).
date
- The 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, if
false
this field becomes read-only.public void setFormat(DateFormat format)
format
- The date format to use for this field.public void setLabel(String label)
label
- The label for this field.public void setMinuteIncrements(long minuteIncrements)
minuteIncrements
- The minute increments (in milliseconds).public void setTimeZone(TimeZone tz)
tz
- The new time zone for this field.
NullPointerException
- if tz
is null
.public String toString()
toString
in class Object
public AccessibleContext getAccessibleContext()
getAccessibleContext
in class Field
AccessibleContext
object that represents the
field.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal