Personal tools

XUL:Specs:DateTimePickers

From MozillaWiki

Jump to: navigation, search

Contents

Requirements

  • Need widgets for selecting or entering dates and times
  • Should support 12 or 24 hour clocks
  • Should display times and dates in a localized manner

Time Picker

A widget for selecting times. It contains a textbox with a spinbuttons next to it. The textbox is actually three textboxes inside of a box styled to look like a textbox. The three textboxes allow entry of an hour, minute and second. The spinbuttons adjusts the value of the currently focused textbox. A fourth textbox appears for 12 hour clocks which allows selection of AM or PM.


<timepicker value="13:15"
            increment="10"
            hideseconds="false"/>

Attributes

hideseconds 
set to true to hide the seconds entry field.
increment 
the granularity of minutes that may be selected. For instance, 5 means that only minutes divisible by 5 may be selected. Pressing the spinbuttons while the minute field is focused will increment or decrement the minutes by this value.
value 
the default time to be set for the timepicker. The syntax is 'hh:mm:ss'.

Constants

amIndicator
the label for AM
hourLeadingZero
true if hours are displayed with a leading zero
is24HourClock
boolean value indicating if a 24 hour clock is being used
minuteLeadingZero
true if mintes are displayed with a leading zero
pmIndicator
the label for PM
secondLeadingZero
true if seconds are displayed with a leading zero

Properties

dateValue 
the current value selected in the timepicker as a Date object.
disabled 
the timepicker is disabled.
hideSeconds 
set to true to hide the seconds entry field.
hour 
the currently selected hour from 0 to 23.
isPM 
true if the hour is between 12 and 23.
increment 
gets and sets the value of the increment attribute.
minute 
the currently selected minute from 0 to 59.
readOnly 
the timepicker is read only and the user cannot modify the currently selected time.
second 
the currently selected second from 0 to 59.
tabIndex 
the tab order of the timepicker.
value 
the currently selected time in the form HH:MM:SS.

All of the properties above may be modified to change the current time.

Events

The change event is fired whenever the time is changed.

Date Picker

A widget for selecting dates. There are three varieties, chosen by setting the type attribute. The default datepicker, if no type attribute is present, is an entry datepicker. Other types are grid and popup.

  • entry - contains a textbox with a spinbuttons next to it and works like the timepicker but for entering the year, month and date.
  • grid - a calendar grid for selecting a date. The mouse may be used to click on a date or the keyboard may be used to navigate to a date.
  • popup - a combination entry field with a dropdown button. Pressing the dropdrop button opens a popup with the grid in it.
<datepicker type="grid"
            firstdayofweek="0"
            value="Jul 20, 2005"
            hideyear="false"/>

Attributes

firstdayofweek 
which day of the week to display as the first day in the grid. The values range from 0 to 6, where 0 is Sunday. The default value is determined by the locale.
hideyear 
set to true to hide the year entry field. This would be used, for example, for birthday fields where the year is not always relevant.
type 
either grid or popup
value 
the default date to be set for the datepicker.

Constants

dateLeadingZero
true if dates are displayed with a leading zero
monthLeadingZero
true if months are displayed with a leading zero
yearLeadingZero
true if years are displayed with leading zeroes

Properties

date 
the currently selected date from 1 to 31.
dateValue 
the current value selected in the datepicker as a Date object.
disabled 
the datepicker is disabled.
month 
the currently selected month from 0 to 11.
open 
true if the popup in a popup datepicker is open, or false otherwise. This property may be changed to open or close the popup. The open property is always false for entry and grid datepickers, and changing the value has no effect.
readOnly 
the datepicker is read only and the user cannot modify the currently selected date. However, in a grid or popup datepicker, the user may still navigate between the months.
tabIndex 
the tab order of the datepicker.
value 
the currently selected date in the form YYYY/MM/DD. Unlike, the month property, months in this value range from 01 to 12.
year 
the currently selected year from 1 to 9999.

All of the properties above may be modified to change the current date.

Events

The change event is fired whenever the date is changed.

The monthchange event is fired for the grid and popup datepickers whenever a new month is navigated to or displayed.