net.rim.device.api.ui.picker
Class DateTimePicker

java.lang.Object
  net.rim.device.api.ui.picker.DateTimePicker

public abstract class DateTimePicker
extends Object

A user interface component for picking a date only, time only, and date and time together.

This API can support various options for capturing dates and times. This includes capturing partial dates such as credit card expiry dates which include only a month and a year. This class handles insufficient information for dates in the same way Calendar does. The developer specifies which parts of the date are mutable by specifying a format. Likewise, the developer is responsible for retrieving the particular data she is interested in. For example, selecting credit card expiry dates, the developer would retrieve only the month and the year from DateTimePicker.getDateTime().

It is important to note that certain formatting may not fit or look appropriate on the screen. For example, using DateFormat.DATE_FULL may not display properly on all devices because of the width of the date. It is the API user's responsibility to provide a format suitable for the device's display.

To display the date and time picker, invoke DateTimePicker.doModal() from the event thread.

Sample Usage

Getting the default date time picker

 final DateTimePicker datePicker = DateTimePicker.createInstance();
 datePicker.doModal();
 

Specifying a date format

 final DateTimePicker datePicker = DateTimePicker.createInstance( Calendar.getInstance(), "yyyy-MM-dd", null);
 datePicker.doModal();
 

Specifying a time format

 final DateTimePicker datePicker = DateTimePicker.createInstance( Calendar.getInstance(), null, "hh:mm:ss aa");
 datePicker.doModal();
 

Specifying a preset date format

 final DateTimePicker datePicker = DateTimePicker.createInstance( Calendar.getInstance(), DateFormat.DATE_FULL, -1);
 datePicker.doModal();
 

Obtaining a credit card expiry date

 final DateTimePicker datePicker = DateTimePicker.createInstance( Calendar.getInstance(), "MM/yyyy", null);
 datePicker.doModal();
 final java.util.Calendar cal = datePicker.getDateTime();
 final int month = cal.get(Calendar.MONTH);
 final int year  = cal.get(Calendar.YEAR);
 

See Also:

Calendar, DateFormat

Since:

BlackBerry API 5.0.0

Method Summary
static Calendar	cloneCalendar(Calendar source) Clones a Calendar.
static void	cloneCalendar(Calendar source, Calendar destination) Clone a Calendar object.
static DateTimePicker	createInstance() Returns a date picker with the cuurent date using the default style.
static DateTimePicker	createInstance(Calendar calendar) Returns a date picker with an initial date to display, and default format.
static DateTimePicker	createInstance(Calendar calendar, int dateStyle, int timeStyle) Returns a date picker with an initial date to display, and the format for the date and time.
static DateTimePicker	createInstance(Calendar calendar, String datePattern, String timePattern) Returns a date picker with an initial date to display, and the format for the date and time.
boolean	doModal() Show the DatePicker in a modal screen centered on the display.
boolean	doModal(int initialFocusField) Show the DatePicker in a modal screen and also set the field which has the initial focus.
abstract boolean	doModal(int initialFocusField, XYRect preferredPosition) Show the DatePicker in a modal screen on a specific position with an initial field to focus.
abstract Calendar	getDateTime() Returns the calendar's current date and time as a Calendar object.
abstract void	reset() Resets the picker to the initial date.
abstract void	setDateTime(Calendar calendar) Sets the date of the picker to the specified date.
void	setIncrement(int calendarField, int incrementAmount) Sets the increment for a specific date/time field.
abstract void	setMaximumDate(Calendar maxCalendar) Sets the maximum date that can be selected by this picker.
abstract void	setMinimumDate(Calendar minCalendar) Sets the minimum date that can be selected by this picker.

Methods inherited from class java.lang.Object

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

Method Detail

createInstance

public static DateTimePicker createInstance()

Returns a date picker with the cuurent date using the default style. Date format set to DateFormat.DATE_DEFAULT Time format set to DateFormat.TIME_DEFAULT

Returns:

New DateTimePicker with the current date and default style

Since:

BlackBerry API 5.0.0

createInstance

public static DateTimePicker createInstance(Calendar calendar)

Returns a date picker with an initial date to display, and default format. Date format set to DateFormat.DATE_DEFAULT Time format set to DateFormat.TIME_DEFAULT

Parameters:

calendar - initial date to display

Returns:

New DateTimePicker with the initial date set and default style

Since:

BlackBerry API 5.0.0

createInstance

public static DateTimePicker createInstance(Calendar calendar,
                                            int dateStyle,
                                            int timeStyle)

Returns a date picker with an initial date to display, and the format for the date and time.

It is important to note that certain formatting may not fit or look appropriate on the screen. For example, using DateFormat.DATE_FULL may not display properly on all devices because of the width of the date. It is the API user's responsibility to provide a format suitable for the device's display.

Parameters:

calendar - initial date to display

dateStyle - one of DateFormat.DATE_FULL, DateFormat.DATE_LONG, DateFormat.DATE_MEDIUM, DateFormat.DATE_SHORT, DateFormat.DATE_DEFAULT. If an invalid dateStyle, then DateFormat.DATE_DEFAULT is used.

timeStyle - one of DateFormat.TIME_FULL, DateFormat.TIME_LONG, DateFormat.TIME_MEDIUM, DateFormat.TIME_SHORT, DateFormat.TIME_DEFAULT. If an invalid timeStyle, then DateFormat.TIME_DEFAULT is used.

Returns:

New DateTimePicker with the initial date and style set

Since:

BlackBerry API 5.0.0

createInstance

public static DateTimePicker createInstance(Calendar calendar,
                                            String datePattern,
                                            String timePattern)

Returns a date picker with an initial date to display, and the format for the date and time. If both datePattern and timePattern are null, then the default date and time formats will be used.

It is important to note that certain formatting may not fit or look appropriate on the screen. For example, using DateFormat.DATE_FULL may not display properly on all devices because of the width of the date. It is the API user's responsibility to provide a format suitable for the device's display.

Parameters:

calendar - initial date to display

datePattern - the SimpleDateFormat for the date. If datePattern is null and timePattern is not null, then a date will not be shown. The pattern must only include text patterns (e.g. '/',':') and date patterns i.e. DateFormat.YEAR_FIELD, DateFormat.MONTH_FIELD, DateFormat.DATE_FIELD, DateFormat.DAY_OF_WEEK_FIELD. Other format symbols will be ignored.

timePattern - the SimpleDateFormat for the time. Passing null will not show a time If timePattern is null and datePattern is not null, then a time will not be shown. The pattern must only include text patterns (e.g. '/',':') and any of the following time patterns: DateFormat.HOUR_FIELD, DateFormat.HOUR_OF_DAY_FIELD, DateFormat.MINUTE_FIELD, DateFormat.SECOND_FIELD, DateFormat.AM_PM_FIELD. Other format symbols will be ignored.

Returns:

New DateTimePicker with the initial date and style set

Since:

BlackBerry API 5.0.0

getDateTime

public abstract Calendar getDateTime()

Returns the calendar's current date and time as a Calendar object.

Returns:

the calendar's current date and time as a Calendar object.

Since:

BlackBerry API 5.0.0

reset

public abstract void reset()

Resets the picker to the initial date.

Since:

BlackBerry API 5.0.0

setMinimumDate

public abstract void setMinimumDate(Calendar minCalendar)

Sets the minimum date that can be selected by this picker. Note: If the mininum date is greater than the current maximum date the maximum date will be set to the mininum date. Also note that this method specifies the date only, not the time.

Parameters:

minCalendar - the minimum date

Throws:

NullPointerException - if minCalendar is null

Since:

BlackBerry API 5.0.0

setMaximumDate

public abstract void setMaximumDate(Calendar maxCalendar)

Sets the maximum date that can be selected by this picker. Note: If the maximum date is less than the current mininum date the mininum date will be set to the maximum date. Also note that this method specifies the date only, not the time.

Parameters:

maxCalendar - the maximum date

Throws:

NullPointerException - if maxCalendar is null.

Since:

BlackBerry API 5.0.0

setDateTime

public abstract void setDateTime(Calendar calendar)

Sets the date of the picker to the specified date.

Parameters:

calendar - the date to set the picker to.

Since:

BlackBerry API 5.0.0

setIncrement

public void setIncrement(int calendarField,
                         int incrementAmount)

Sets the increment for a specific date/time field. This may not be applicable for all subclasses, so an empty implementation is provided. Subclasses that will support this method can override this empty implementation.

Parameters:

calendarField - supported fields include Calendar.MINUTE and Calendar.SECOND.

incrementAmount - the amount to increment e.g. if the increment is 5 for Calendar.MINUTE, then the available numbers will be 0, 5, 10, 15, ...

Since:

BlackBerry API 5.0.0

doModal

public boolean doModal()

Show the DatePicker in a modal screen centered on the display. This must only be called from the event thread.

Returns:

true if and only if the changes were confirmed i.e. not cancelled.

Since:

BlackBerry API 5.0.0

doModal

public abstract boolean doModal(int initialFocusField,
                                XYRect preferredPosition)

Show the DatePicker in a modal screen on a specific position with an initial field to focus. The screen may not be displayed exactly on the preferred position since the dimensions may be different. This must only be called from the event thread. This must only be called from the event thread.

Parameters:

initialFocusField - One of the integers from DateFormat e.g. YEAR_FIELD. Use -1 to use the default focus.

preferredPosition - the preferred position of the modal screen.

Returns:

true if and only if the changes were confirmed i.e. not cancelled.

Since:

BlackBerry API 5.0.0

doModal

public boolean doModal(int initialFocusField)

Show the DatePicker in a modal screen and also set the field which has the initial focus. This must only be called from the event thread.

Parameters:

initialFocusField - One of the integers from DateFormat e.g. YEAR_FIELD. Use -1 to use the default focus.

Returns:

true if and only if the changes were confirmed i.e. not cancelled.

Since:

BlackBerry API 5.0.0

cloneCalendar

public static void cloneCalendar(Calendar source,
                                 Calendar destination)

Clone a Calendar object.

Parameters:

source - Calendar to clone. If null, nothing is copied over to destination.

destination - clone of source Calendar; If null, nothing is done.

Since:

BlackBerry API 5.0.0

cloneCalendar

public static Calendar cloneCalendar(Calendar source)

Clones a Calendar.

Parameters:

source - the source celendar

Returns:

a separate instance of a Calendar with the same data as source

Since:

BlackBerry API 5.0.0