Unlike Java, Perl does not have a date/time object. However, it is possible to use the unix time (seconds since epoch, that is 1st January 1970) as a replacement. This is limited, since on most architectures, the valid range is between 14th December 1901 and 19th January 2038. For other dates, it is possible to use a hash notation:

The abbreviations are derivated from the format letters of strftime. Note that year is the full year (1998 instead of 98) and month is the real month number, as opposed to the output of localtime(), where the month is subtracted by one.

In this document, the first method will be referred as unixtime and the second method as datehash.

If true then all entry fields will obtain arrows. Otherwise only one arrow pair for each date and time will be drawn. This option can be set only while creating the widget. This option needs the Tk::NumEntry widget to be installed.

Creates an additional choice button. The argument to -choices must be one of now, today, yesterday or tomorrow, or an array with a combination of those. If only one is used, only a simple button is created, otherwise an optionmenu. This option can be set only while creating the widget.

Examples:

-choices => 'now'
-choices => ['today', 'yesterday', 'tomorrow']

It is possible to specify user-defined values. User-defined values should be defined as array elements with two elements. The first element is the label for the button or optionmenu entry. The second element specifies the time associated with this value. It may be either a date hash (missing values are set to the current date) or a subroutine which calculates unix seconds.

Here are two examples. The first defines an additional optionmenu entry for this year's christmas and the second defines an entry for the day before yesterday.

Specifies a callback which is executed every time after an arrow button is selected. The callback is called with the following arguments: reference of date widget, field specifier, increment value. The field specifier is either "date" or "time" or one of "H", "M", "S", "d", "m", "y" for the possible time and date fields.

This is a sprintf/printf-like format string for setting the order and format of the date entries. By default, the format string is "%2d.%2m.%4y" meaning a two-character wide day entry, followed by a dot, followed by a two-character wide month entry, another dot, and finally a four-character wide year entry. The characters are the same as in the strftime function (see POSIX). It is also possible to use the 'A' letter for displaying the (localized) weekday name. See below in the EXAMPLES section for a more US-like date format. This option can be set only while creating the widget.

If set to a false value, disables editing of the date widget. All entries are converted to labels and there are no arrow buttons. Defaults to true (widget is editable). This option can be set only while creating the widget.

Specifies a callback which is executed every time when an arrow button is selected and before actually execute the increment or decrement command. The callback is called with following arguments: date widget, type (either date or time) and increment (+1 or -1). If the callback returns with a false value, the increment or decrement command will not be executed.

"readonly" means only that the entry fields are readonly. However, the user is still able to use the increment/decrement buttons to change the date value. Use -state => "disabled" to make a date widget completely unchangable by the user.

Specifies one of two states for the date widget: normal or disabled. If the date widget is disabled then the value may not be changed using the user interface (that is, by typing in the entry subwidgets or pressing on the increment/decrement buttons).

This is a sprintf/printf-like format string for setting the order and format of the time entries. By default, the format string is "%2H.%2M.%2S" meaning a two-character wide hour entry, followed by a dot, followed by a two-character wide minute entry, another dot, and finally a two-character wide seconds entry. The characters are the same as in the strftime function (see POSIX). This option can be set only while creating the widget.

Replace the standard weekday names (either English or as supplied by the locale system) with a user-defined array. The argument should be a reference to a hash with seven elements. The names have to start with Sunday.

Please note that the full set of features only available, if the Tk-GBARR distribution is also installed. However, the widget also works without this distribution, only lacking the arrow buttons.

If the POSIX module is available, localised weekday and month names will be used instead of English names. Otherwise you have to use the -weekday and -monthnames options. The POSIX strftime function does not work correctly before version 1.03 (that is, before 5.6.0), so this feature is disabled for older perl versions.

- The -orient option can be only set while creating the widget. Also
other options are only settable at create time.
- waiting for a real perl Date/Time object
- tie interface (-variable) does not work if the date widget gets destroyed
(see uncommented DESTROY)
- get and set must use the tied variable, otherwise tieying does no work
at all
- -from/-to is missing (limit) (or -minvalue, -maxvalue?)
- range check (in DateNumEntryPlain::incdec)
- am/pm
- more interactive examples are needed for some design issues (how strong
signal errors? ...)
- check date-Function
- optionally use Tk::DateEntry for the date part
- -command is not fully implemented