FileDocCategorySizeDatePackage
DateField.javaAPI DocphoneME MR2 API (J2ME)12542Wed May 02 18:00:22 BST 2007javax.microedition.lcdui

DateField

public class DateField extends Item
A DateField is an editable component for presenting date and time (calendar) information that may be placed into a Form. Value for this field can be initially set or left unset. If value is not set then the UI for the field shows this clearly. The field value for "not initialized state" is not valid value and getDate() for this state returns null.

Instance of a DateField can be configured to accept date or time information or both of them. This input mode configuration is done by DATE, TIME or DATE_TIME static fields of this class. DATE input mode allows to set only date information and TIME only time information (hours, minutes). DATE_TIME allows to set both clock time and date values.

In TIME input mode the date components of Date object must be set to the "zero epoch" value of January 1, 1970.

Calendar calculations in this field are based on default locale and defined time zone. Because of the calculations and different input modes date object may not contain same millisecond value when set to this field and get back from this field.

since
MIDP 1.0

Fields Summary
public static final int
DATE
Input mode for date information (day, month, year). With this mode this DateField presents and allows only to modify date value. The time information of date object is ignored.

Value 1 is assigned to DATE.

public static final int
TIME
Input mode for time information (hours and minutes). With this mode this DateField presents and allows only to modify time. The date components should be set to the "zero epoch" value of January 1, 1970 and should not be accessed.

Value 2 is assigned to TIME.

public static final int
DATE_TIME
Input mode for date (day, month, year) and time (minutes, hours) information. With this mode this DateField presents and allows to modify both time and date information.

Value 3 is assigned to DATE_TIME.

DateFieldLF
dateFieldLF
The look&feel associated with this DateField. Set in the constructor.
boolean
initialized
A flag indicating the initialization state of this DateField
int
mode
The mode of this DateField
Calendar
currentDate
The last saved date. This is used for making the last saved date bold.
Constructors Summary
public DateField(String label, int mode)
Creates a DateField object with the specified label and mode. This call is identical to DateField(label, mode, null).

param
label item label
param
mode the input mode, one of DATE, TIME or DATE_TIME
throws
IllegalArgumentException if the input mode's value is invalid


                                                   
         
        this(label, mode, null);
public DateField(String label, int mode, TimeZone timeZone)
Creates a date field in which calendar calculations are based on specific TimeZone object and the default calendaring system for the current locale. The value of the DateField is initially in the "uninitialized" state. If timeZone is null, the system's default time zone is used.

param
label item label
param
mode the input mode, one of DATE, TIME or DATE_TIME
param
timeZone a specific time zone, or null for the default time zone
throws
IllegalArgumentException if the input mode's value is invalid

        super(label);

        synchronized (Display.LCDUILock) {
            if ((mode != DATE) && (mode != TIME) && (mode != DATE_TIME)) {
                throw new IllegalArgumentException("Invalid input mode");
            }

            this.mode = mode;

            if (timeZone == null) {
                timeZone = TimeZone.getDefault();
            }

            this.currentDate = Calendar.getInstance(timeZone);

            itemLF = dateFieldLF = LFFactory.getFactory().getDateFieldLF(this);

        } // synchronized
Methods Summary
booleanacceptFocus()
Return whether the Item takes user input focus.

return
Always return true

	return true;
public java.util.DategetDate()
Returns date value of this field. Returned value is null if field value is not initialized. The date object is constructed according the rules of locale specific calendaring system and defined time zone. In TIME mode field the date components are set to the "zero epoch" value of January 1, 1970. If a date object that presents time beyond one day from this "zero epoch" then this field is in "not initialized" state and this method returns null. In DATE mode field the time component of the calendar is set to zero when constructing the date object.

return
date object representing time or date depending on input mode
see
#setDate

        synchronized (Display.LCDUILock) {
            // NOTE: 
            // defensive copy of the Date object is necessary 
            // because CLDC's Calendar returns a reference to an internal, 
            // shared Date object.  See bugID: 4479408.

// 	       original:
//             return (initialized ? 
//                 new java.util.Date(currentDate.getTime().getTime()) : null);

	    if (initialized) {
		java.util.Date retDate = dateFieldLF.lGetDate();
		if (retDate == null) {
		    return new java.util.Date(currentDate.getTime().getTime());
		} else {
		    return retDate;
		}
	    } 

	    return null;

        } // synchronized
public intgetInputMode()
Gets input mode for this date field. Valid input modes are DATE, TIME and DATE_TIME.

return
input mode of this field
see
#setInputMode

        // SYNC NOTE: return of atomic value, no locking necessary
        return mode;
public voidsetDate(java.util.Date date)
Sets a new value for this field. null can be passed to set the field state to "not initialized" state. The input mode of this field defines what components of passed Date object is used.

In TIME input mode the date components must be set to the "zero epoch" value of January 1, 1970. If a date object that presents time beyond one day then this field is in "not initialized" state. In TIME input mode the date component of Date object is ignored and time component is used to precision of minutes.

In DATE input mode the time component of Date object is ignored.

In DATE_TIME input mode the date and time component of Date are used but only to precision of minutes.

param
date new value for this field
see
#getDate

        synchronized (Display.LCDUILock) {
            setDateImpl(date);
            dateFieldLF.lSetDate(date);
        } // synchronized
voidsetDateImpl(java.util.Date date)
Sets the date.

param
date the date value to set to.


        if (date == null) {
            initialized = false;
        } else {
            currentDate.setTime(date);
            
            if (mode == TIME) {

                if (currentDate.getTime().getTime() >= 24*60*60*1000) {
                    initialized = false;
                } else {
                    currentDate.set(Calendar.YEAR, 1970);
                    currentDate.set(Calendar.MONTH, Calendar.JANUARY);
                    currentDate.set(Calendar.DATE, 1);
                    initialized = true;
                }
            } else {
                // Currently spec does not prohibit from losing
                // irrelevant for that mode information
                // so we always zero out hours and minutes
                
                // NOTE: the specification doesn't prohibit 
                // the loss of information irrelevant to 
                // the current input mode, so we always zero out the
                // hours and minutes.
                if (mode == DATE) {
                    currentDate.set(Calendar.HOUR, 0);
		            currentDate.set(Calendar.HOUR_OF_DAY, 0);
                    currentDate.set(Calendar.MINUTE, 0);
                }
                initialized = true;
            }

            // always ignore seconds and milliseconds
            currentDate.set(Calendar.SECOND, 0);
            currentDate.set(Calendar.MILLISECOND, 0);
        }
public voidsetInputMode(int mode)
Set input mode for this date field. Valid input modes are DATE, TIME and DATE_TIME.

param
mode the input mode, must be one of DATE, TIME or DATE_TIME
throws
IllegalArgumentException if an invalid value is specified
see
#getInputMode


        if ((mode != DATE) && (mode != TIME) && (mode != DATE_TIME)) {
            throw new IllegalArgumentException("Invalid input mode");
        }

        synchronized (Display.LCDUILock) {
            if (this.mode != mode) {
                this.mode = mode;

                // While the input mode is changed
                // some irrelevant values for new mode could be lost. 
                // Currently that is allowed by the spec.

                // So for TIME mode we make sure that time is set
                // on a zero epoch date
                // and for DATE mode we zero out hours and minutes
                if (mode == TIME) {
                    currentDate.set(Calendar.YEAR, 1970);
                    currentDate.set(Calendar.MONTH, Calendar.JANUARY);
                    currentDate.set(Calendar.DATE, 1);
                } else if (mode == DATE) {
                    currentDate.set(Calendar.HOUR, 0);
		    currentDate.set(Calendar.HOUR_OF_DAY, 0);
                    currentDate.set(Calendar.MINUTE, 0);
                }
                dateFieldLF.lSetInputMode(mode);
            }
        } // synchronized