FileDocCategorySizeDatePackage
DateField.javaAPI DocJ2ME MIDP 2.059147Thu Nov 07 12:02:26 GMT 2002javax.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.

static final Date
EPOCH
Static zero epoch Date - used as a default value for uninitialized DateFields with TIME mode.
static final String[]
MONTH_NAMES
Static array holding the names of the 12 months
static final int[]
TRIG_TABLE
table of trigonometric functions, in 16.16 fixed point
private int
highlight
The highlight of this DateField
private boolean
traversedIn
A flag indicating a prior call to callTraverse()
private boolean
initialized
A flag indicating the initialization state of this DateField
private int
mode
The mode of this DateField
private EditScreen
editor
The editor for this DateField
private Calendar
currentDate
The last saved date. This is used for making the last saved date bold.
private static final boolean
CLOCK_USES_AM_PM
Flag to signal the clock representation uses AM and PM notation
private static final Image
ARROW_UP
The image representing an up arrow
private static final Image
ARROW_DOWN
The image representing an down arrow
private static final Image
ARROW_LEFT
The image representing an left arrow
private static final Image
ARROW_RIGHT
The image representing an right arrow
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);
        } // synchronized
Methods Summary
static java.lang.StringampmString(java.util.Calendar calendar)
Get the am/pm text given a Calandar

param
calendar The Calendar object to retrieve the time from
return
String The am/pm text based on the time in the calendar

        int hour   = calendar.get(Calendar.HOUR_OF_DAY);
        int minute = calendar.get(Calendar.MINUTE);

        if (hour >= 12) {
            return ((minute == 0) && (hour == 12)) ? "noon" : "PM";
        } else {
            return ((minute == 0) && (hour == 00)) ? "mid." : "AM";
        }
voidcallKeyPressed(int keyCode)
Called by the system to signal a key press

param
keyCode the key code of the key that has been pressed

        if (keyCode != Display.KEYCODE_SELECT) {
            return;
        }

        Screen returnScreen = getOwner();

        if (editor == null) {
            editor = new EditScreen(returnScreen, this);
        }

        switch (mode) {
        case DATE:
            if (!initialized) {
                currentDate.set(Calendar.HOUR, 0);
                currentDate.set(Calendar.MINUTE, 0);
                currentDate.set(Calendar.SECOND, 0);
                currentDate.set(Calendar.MILLISECOND, 0);
            }
            editor.setDateTime(currentDate.getTime(), DATE);
            break;

        case TIME:
            editor.setDateTime(initialized ? currentDate.getTime() : EPOCH,
                               TIME);
            break;

        case DATE_TIME:
            editor.setDateTime(currentDate.getTime(),
                               (highlight < 1) ? TIME : DATE);
        }

        returnScreen.resetToTop = false;
        returnScreen.currentDisplay.setCurrent(editor);
intcallMinimumHeight()
Get the minimum height of this Item

return
the minimum height

        return callPreferredHeight(-1);
intcallMinimumWidth()
Get the minimum width of this Item

return
the minimum width

        return Screen.CONTENT_FONT.stringWidth("Www,99 Www 0000") + 2;
voidcallPaint(Graphics g, int width, int height)
Paint this DateField

param
g the Graphics object to be used for rendering the item
param
width current width of the item in pixels
param
height current height of the item in pixels


        // draw label
        int labelHeight = super.paintLabel(g, width) + LABEL_PAD;
        g.translate(0, labelHeight);

        int offset = 0;
        String str;
        switch (mode) {
            case TIME:
            case DATE_TIME:
                str = toString(TIME);
                if (highlight == 0 && hasFocus) {
                    g.fillRect(2, 0, Screen.CONTENT_FONT.stringWidth(str),
                               Screen.CONTENT_HEIGHT);
                    g.setColor(Display.FG_H_COLOR);
                }
                g.drawString(str, 2, 0,
                            Graphics.LEFT | Graphics.TOP);
                g.setColor(Display.FG_COLOR);
                if (mode == TIME) {
                    break;
                }
                offset = Screen.CONTENT_HEIGHT;
            case DATE:
                str = toString(DATE);
                if ((highlight == 0 && mode == DATE && hasFocus) ||
                    (highlight == 1 && mode == DATE_TIME && hasFocus)) {

                    g.fillRect(2, offset, Screen.CONTENT_FONT.stringWidth(str),
                               Screen.CONTENT_HEIGHT);
                    g.setColor(Display.FG_H_COLOR);
                }
                g.drawString(toString(DATE), 2, offset,
                            Graphics.LEFT | Graphics.TOP);
                g.setColor(Display.FG_COLOR);
        }

        g.translate(0, -labelHeight);
intcallPreferredHeight(int w)
Get the preferred height of this Item

param
w the tentative content width in pixels, or -1 if a tentative width has not been computed
return
the preferred height

        if (mode == DATE_TIME) {
            return getLabelHeight(w) +
                (Screen.CONTENT_HEIGHT * 2) + LABEL_PAD;
        } else {
            return getLabelHeight(w) + Screen.CONTENT_HEIGHT;
        }
intcallPreferredWidth(int h)
Get the preferred width of this Item

param
h the tentative content height in pixels, or -1 if a tentative height has not been computed
return
the preferred width

        return callMinimumWidth();
booleancallTraverse(int dir, int viewportWidth, int viewportHeight, int[] visRect)
Called by the system to traverse this DateField

param
dir the direction of traversal
param
viewportWidth the width of the container's viewport
param
viewportHeight the height of the container's viewport
param
visRect passes the visible rectangle into the method, and returns the updated traversal rectangle from the method
return
true if internal traversal had occurred, false if traversal should proceed out


        super.callTraverse(dir, viewportWidth, viewportHeight, visRect);

        int numEls = (mode == DATE_TIME) ? 2 : 1;

        if (!traversedIn) {
            traversedIn = true;

            if (highlight == -1) {
                switch (dir) {
                    case Canvas.UP:
                        highlight = numEls - 1;
                        break;
                    case Canvas.DOWN:
                        highlight = 0;
                        break;
                    case CustomItem.NONE:
                }
            }
        } else {

            if (dir == Canvas.UP) {
                if (highlight > 0) {
                    highlight--;
                } else {
                    return false;
                }
            } else if (dir == Canvas.DOWN) {
                if (highlight < (numEls - 1)) {
                    highlight++;
                } else {
                    return false;
                }
            }
        }

        visRect[Y] = getLabelHeight(visRect[WIDTH]) + LABEL_PAD;
        if (highlight > 0) {
            visRect[Y] += Screen.CONTENT_HEIGHT;
        }
        visRect[HEIGHT] = Screen.CONTENT_HEIGHT;

        repaint();
        return true;
voidcallTraverseOut()
Called by the system to indicate traversal has left this Item

        super.callTraverseOut();

        traversedIn = false;
static intcos(int angle)
Utility method to return the cosine of an angle

param
angle The angle to compute the cosine of
return
int The cosine of the angle


                                  
        
        angle += 360000;
        angle %= 360;

        if (angle >= 270) {
            return TRIG_TABLE[360 - angle];
        } else if (angle >= 180) {
            return -TRIG_TABLE[angle - 180];
        } else if (angle >= 90) {
            return -TRIG_TABLE[180 - angle];
        } else {
            return TRIG_TABLE[angle];
        }
static java.lang.StringdayOfWeekString(java.util.Calendar calendar)
Get the day of the week text given a Calendar

param
calendar The Calendar object to retrieve the date from
return
String The day of the week text based on the date in the calendar

        String str;
        switch (calendar.get(Calendar.DAY_OF_WEEK)) {
        case Calendar.SUNDAY:    str = "Sun"; break;
        case Calendar.MONDAY:    str = "Mon"; break;
        case Calendar.TUESDAY:   str = "Tue"; break;
        case Calendar.WEDNESDAY: str = "Wed"; break;
        case Calendar.THURSDAY:  str = "Thu"; break;
        case Calendar.FRIDAY:    str = "Fri"; break;
        case Calendar.SATURDAY:  str = "Sat"; break;
        default: 
            str = Integer.toString(calendar.get(Calendar.DAY_OF_WEEK));
        }
        return str;
booleanequateNLA()
Determine if this Item should have a newline after it

return
true if it should have a newline after

        if (super.equateNLA()) {
            return true;
        }

        return ((layout & Item.LAYOUT_2) != Item.LAYOUT_2);
booleanequateNLB()
Determine if this Item should have a newline before it

return
true if it should have a newline before

        if (super.equateNLB()) {
            return true;
        }

        return ((layout & Item.LAYOUT_2) != Item.LAYOUT_2);
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.
            return (initialized ? 
                new java.util.Date(currentDate.getTime().getTime()) : 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;
voidsaveDate(java.util.Date date)
Called from the Date Editor to save the selected Date.

param
date The Date object to which current date should be set.

        initialized = true;
        
        currentDate.setTime(date);
        invalidate();
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) {
            if (date == null) {
                initialized = false;
            } else {
                currentDate.setTime(date);

                if (mode == TIME) {
                    // NOTE:
                    // It is unclear from the spec what should happen 
                    // when DateField with TIME mode is set to
                    // a value that is on a day other than 1/1/1970.
                    //
                    // Two possible interpretations of the spec are:
                    // 1. DateField is put into the "uninitialized" state; or
                    // 2. The time portion of the DateField is set to the 
                    //    time-of-day portion of the Date object passed in, 
                    //    and the date portion of the DateField is set 
                    //    to 1/1/1970.
                    //
                    // Currently we are using the first approach.
                    initialized =
                        (currentDate.get(Calendar.YEAR)  == 1970) &&
                        (currentDate.get(Calendar.MONTH) == Calendar.JANUARY)
                        && (currentDate.get(Calendar.DATE)   == 1);
                } 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.MINUTE, 0);
                    }
                    initialized = true;
                }

                // always ignore seconds and milliseconds
                currentDate.set(Calendar.SECOND, 0);
                currentDate.set(Calendar.MILLISECOND, 0);
            }
            invalidate();
        } // synchronized
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) {
                int oldMode = this.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.MINUTE, 0);
                }
                invalidate();
            }
        } // synchronized
static intsin(int angle)
Utility method to return the sin of an angle

param
angle The angle to compute the sin of
return
int The sin of the angle

        return cos(angle - 90);
java.lang.StringtoString(int mode)
Translate the mode of a DateField into a readable string

param
mode The mode to translate
return
String A human readable string representing the mode of the DateField

        if (mode == DATE) {
            if (!initialized) {
                    return Resource.getString("<date>");
            }

            return Resource.getDateString(
                dayOfWeekString(currentDate),
                twoDigits(currentDate.get(Calendar.DATE)),
                MONTH_NAMES[currentDate.get(Calendar.MONTH)].substring(0, 3),
                Integer.toString(currentDate.get(Calendar.YEAR)));

        } else if (mode == TIME) {
            if (!initialized) {
                    return Resource.getString("<time>");
            }

            if (CLOCK_USES_AM_PM) {
                return Resource.getTimeString(
                    twoDigits(currentDate.get(Calendar.HOUR)),
                    twoDigits(currentDate.get(Calendar.MINUTE)),
                    twoDigits(currentDate.get(Calendar.SECOND)),
                    ampmString(currentDate));
            } else {
                return Resource.getTimeString(
                    twoDigits(currentDate.get(Calendar.HOUR_OF_DAY)),
                    twoDigits(currentDate.get(Calendar.MINUTE)),
                    twoDigits(currentDate.get(Calendar.SECOND)),
                    null);
            }
        } else {
            if (!initialized) {
                    return Resource.getString("<date/time>");
            }

            return Resource.getDateTimeString(
                dayOfWeekString(currentDate),
                twoDigits(currentDate.get(Calendar.DATE)),
                MONTH_NAMES[currentDate.get(Calendar.MONTH)].substring(0, 3),
                Integer.toString(currentDate.get(Calendar.YEAR)),
                twoDigits(currentDate.get(Calendar.HOUR_OF_DAY)),
                twoDigits(currentDate.get(Calendar.MINUTE)),
                twoDigits(currentDate.get(Calendar.SECOND)),
                ampmString(currentDate));
        }
private static java.lang.StringtwoDigits(int n)
A utility method to return a numerical digit as two digits if it is less than 10

param
n The number to convert
return
String The String representing the number in two digits

        if (n == 0) {
            return "00";
        } else if (n < 10) {
            return "0" + n;
        } else {
            return "" + n;
        }