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

java.lang.Object
  extended by 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





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