DatePicker applet
The DatePicker is a small calendar control that lets users pick dates from a calendar rather than having to type them in. It can be used throughout your user interface for selecting dates. DatePicker also provides a convenient way for your application to determine today's date.
This document describes the following topics:
For general information about DevPack applets, see the following topics:
The DatePicker applet can provide the date selection function in your user interface. DatePicker allows
users to pick a date from a calendar display, which is far easier and more effective than requiring them to type the date into an edit control. You can also use the DatePicker to get today's date.
Both the selected date and today's date are available either in the form of a Java Date object or as strings of date components such as the day, month, and year. Events are raised whenever either date changes. (See Event table for more information.) The selected date can also be set from the program. The available date properties are:
The DatePicker API consists of properties that can be programmatically set and read by your application. All the API properties belong to the DatePicker class. In many cases, the properties can also be set using PARAM tags within the HTML <APPLET> tag. The properties and PARAM tags are described below.
You can use the DatePicker as a simple date selection control that takes up a minimum of screen space, or you can selectively display various controls to give the user access to additional features. Among DatePicker's additional features are multi-month displays, support for traditional and national calendar systems used throughout the world, and user controls for setting calendar options. These are described below.
|
The standard one-calendar display, with all controls enabled. |
 |
Calendar controls
The DatePicker has a number of controls. Most are hidden by default but can be displayed at the discretion of the application. The controls and their related properties and PARAM tags are shown in the table below.
- Date selection: The user selects the date by using the year and month selection buttons to display the desired month and then clicks on the desired date. The selected date is outlined by a small rectangle. The year and month selection controls are always enabled. The date can also be selected programmatically by setting theSelectedDate property.
- Day menu: The user can select the starting day of the week and which days of the week are displayed as weekend days from the day menu. The day menu is displayed by clicking on the days of the week heading in the calendar. By default the day menu is disabled.
- View selector: The user can select the one, two, or three by clicking the view selector button.
- Calendar system selector: The user can select the calendar system by clicking the globe icon.
The view and calendar system selectors in the user interface are disabled by default. When both are disabled, the buttons are not displayed, reducing the screen space required for the calendar.
DatePicker display modes
The DatePicker has three display modes, controlled by the View property or view PARAM tag.
- Single-month display: Displays a single month. This is the most compact mode and the default.
- Three-month display: Displays three consecutive months, to give the user a larger context for selecting a date or determining date intervals. All months are displayed using the same calendar system.
- Two-calendar-system display: Displays the calendar in two systems, such as Gregorian and Julian for instance, so that the same date can be seen in the context of each system. In the two system display, the top calendar is called the primary calendar; the bottom calendar is called the reference calendar.
| One-month display |
Three-month display |
Two-calendar system display |
 |
 |
 |
Hiding the calendar
You can also hide the entire calendar. You can use this feature to pop up the calendar only when your interface requires the user to select a date. You can also hide the calendar if you only want to use its today's date feature.
Summary of DatePicker display option properties
You allocate screen space to the DatePicker by setting width and height parameyers in the <APPLET> tag when inserting the DatePicker on your Web page. The width of the calendar display is always 185 pixels. However, the height depends on the display options chosen. The table below shows the required height, in pixels, when various display elements are enabled or disabled.
| Display mode |
No control
No banner |
With banner |
With controls |
With both |
| One month |
122 |
154 |
142 |
172 |
| Three month |
310 |
347 |
335 |
365 |
Two calendar
system |
310 |
347 |
335 |
365 |
The display colors of many components of the UI can be controlled by properties or parameters, as shown below.
Color properties
Color PARAM tags
The DatePicker allows the user to work and select dates in any one of fifteen calendar systems. The default system is Gregorian -- the standard western calendar. And though the user can select dates in terms of the chosen calendar system, most calendar properties translate dates to their Gregorian equivalents. (The exceptions are the LocalSelectedDateAsString property and LocalTodayDateAsString property. These properties report dates in the current calendar system of the primary calendar.)
The supported calendar systems are:
- Gregorian: The standard Western system, introduced by Pope Gregory in 1582. It is based on the solar year. Most years are 365 days long with leap years of 366 days every four years except on century years not evenly divisible by 400. Months are not synchronized with the lunar cycle.
- Julian: A solar calendar which was the standard western calendar before the Gregorian. It evolved from a calendar promulgated by Julius Caesar. It is the same as the Gregorian, with the difference that leap years occur every four years without exception. It is currently 13 days behind the Gregorian calendar.
- Japanese Emperor, Taiwanese Min Guo, Thai, and Korean Dangi: These are solar calendars and calculate the length of months and years in the same way. These calendars differ in the way years are counted, using different significant events to mark the starting points of their eras.
- Chinese, Japanese, Korean, Taiwanese, Hebrew, and Hindi: These are lunar/solar calendars in which months are either 29 or 30 days long, synchronized with the lunar cycle. Normal years have 12 months and are about 352 days long; leap years have 13 months, are about 385 days long, and occur every second or third year to bring the calendar into synchrony with the solar cycle. The calendars differ in how leap years are determined, the starting times of the years, how years are counted, and other specifics. For example, in the Hini calendar days are occassionally repeated, so that consecutive days are assigned the same number.
- Japanese Six Day Cycle: A variation of the Japanese calendar in which days are represented by a cycle of six symbols.
- Hijri: The Moslem calendar. A lunar calendar of twelve months of 29 or 30 days, beginning on the sighting of the new moon. The Hijri year is thus about 11 days shorter than the solar year.
- Coptic: A solar calendar. Years have twelve 30-day months plus a 5-day period not assigned to any month. Leap years add an extra day are every fourth years.
Note: The calendar calculation algorithms used in the DatePicker applet have been supplied under license from Ed Reingold / Nachum Dershowitz. For further information refer to Calendrical Calculations (Paperback ISBN: 0-521-56474-3, Hardback ISBN: 0-521-56413-1) or visit their Web site at http://emr.cs.uiuc.edu/home/reingold/calendar-book/index.shtml.
The DatePicker applet represents today's date and the selected date using the Java Date object. The Date object is designed to work together with the Java Calendar object to provide date arithmetic and other related functions. Both of these objects are available to your JavaScript application. Hints for using them are given below.
Creating Date and Calendar objects
You can create a Java Date, Calendar, and other objects using the ScriptHelper applet. Here is the procedure:
- Embed the ScriptHelper applet in your Web page.
- To create a Java Date, call the ScriptHelper.createDate method. You can initialize the date using a string or integer values.
- To create a Java Calendar, call the ScriptHelper.createJavaCalendar() method. You can set the date of the Calendar object to the date of a Date object by calling Calendar.setTime(Date). (setTime() sets all fields, including the year, month, and day.)
Changing the date or time of a Date object
A common requirement is to calculate the interval between two Date objects or to change the date or time of an existing Date object. For instance, you may want to increment a date by a constant amount. To do so, use a Calendar object as an intermediary. Here is the general procedure:
- Create a Java Calendar object.
- Call Calendar.setTime( Date ) to set the Calendar object to the same date and time as the Date object.
- Use Calendar get and set methods to change the value of the date or time.
- Create a new Date object based on the new Calendar value by calling Calendar.getTime(). This method returns a Date object.
The example illustrates this procedure. It accepts a Java date and the number of days by which the date is to be incremented. It calculates the new date, incrementing the month and year as needed. It then creates a new Java date with this value and returns it. You can use the same technique for your own date arithmetic.
IncrementDateByDays Example
///////////////////////
// java.util.Calendar field constants
// use these constants with the java.util.Calendar.get( fieldConstant ) method.
// the java.util.Calendar.set( fieldConstant ) method cannot be used in a Javascript application.
var JCAL_YEAR = 1;
var JCAL_MONTH = 2;
var JCAL_DAY = 5;
var JCAL_AMPM = 9;
var JCAL_HOUR = 10;
var JCAL_24HOUR = 11;
var JCAL_MINUTE = 12;
var JCAL_SECOND = 13;
function IncrementDateByDays(javaDate, noOfDays)
{
var javaCal, lengthOfMonth;
// create a new Calendar object and initialize it to the date
javaCal = ScriptHelper.createJavaCalendar();
javaCal.setTime(javaDate);
// get the time and date
// use java.util.Calendar.get() with corresponding field constants
var minute = javaCal.get(JCAL_MINUTE);
var hour = javaCal.get(JCAL_24HOUR);
var day = javaCal.get(JCAL_DAY);
var month = javaCal.get(JCAL_MONTH);
var year = javaCal.get(JCAL_YEAR);
// increment date and adjust month and year, if required
day += noOfDays;
while(1) { // we return when date becomes less than length of month
switch(month) {
case 1: case 3: case 5: case 7: case 8: case 10: case 12: // 31 day months
lengthOfMonth = 31;
break;
case 4: case 6: case 9: case 11: // 30 day months
lengthOfMonth = 30;
break;
case 2: // February
if (year % 4 == 0) // leap year -- calculation valid until 2099
else
break;
} // end switch
if (day > lengthOfMonth) {
day -= lengthOfMonth;
if (month < 12) {
}
else {
}
}
else {
// we are done. Create Date object and return
javaCal.Set(year,month,day,hour,minute);
return javaCal.getTime(); // getTime() returns a java.util.Date
}
} // end while
} // end incrementDateByDays()
The following example demonstrates how to embed the DatePicker applet in a Web page and use it to insert dates into another applet.
DatePicker example