/ 
Tk-DateEntry-1.43
River stage zero No dependents
/ Tk::DateEntry

NAME

Tk::DateEntry - Drop down calendar widget for selecting dates.

SYNOPSIS

$dateentry = $parent->DateEntry (<options>);

DESCRIPTION

Tk::DateEntry is a drop down widget for selecting dates. It looks like the BrowseEntry widget with an Entry followed by an arrow button, but instead of displaying a Listbox the DateEntry displays a calendar with buttons for each date. The calendar contains buttons for browsing through the months.

When the drop down is opened, the widget will try to read the current content of the widget (the -textvariable), and display the month/year specified. If the variable is empty, or contains invalid data, then the current month is displayed. If one or two digit year is specified, the widget tries to guess the correct century by using a "100 year window".

The Entry widget has the following keyboard shortcuts:

<Up>, <Down>

Increase or decrease the date by one day.

<Shift-Up>, <Shift-Down>

Increase or decrease the date by one week.

<Control-Up> or <Prior>, <Control-Down> or <Next>

Increase or decrease the date by one month. This would not work if the next or previous month has less days then the day currently selected.

<Shift-Control-Up>, <Shift-Control-Down>

Increase or decrease the date by one year. This would not work if the same month in the next or previous year has less days then the day currently selected.

REQUIREMENTS

Tk::DateEntry requires Time::Local and POSIX (strftime) (and basic Perl/Tk of course....). For using dates before 1970-01-01 either Date::Calc or Date::Pcalc is required.

For faster scanning between months the optional requirement Tk::FireButton is needed. For localized day and month names the following modules are needed:

Encode (for non-ASCII encodings)
I18N::Langinfo (Unix-like systems only, for detection of current locale)
Win32::OLE::NLS (Windows only, for detection of current locale)
Text::Bidi (only if support for right-to-left scripts (Hebrew, Arabic) is needed)

OPTIONS

-arrowimage => image

Use alternative image for the arrow button.

-dateformat => integer

Specify dateformat to use:

  • 1 = MM/DD/YYYY - default.

  • 2 = YYYY/MM/DD

  • 3 = DD/MM/YYYY

  • 4 = YYYY-MM-DD

See also "DATE FORMATS" below.

-parsecmd => \&callback

Instead of using one of the builtin dateformats, you can specify your own by supplying a subroutine for parsing (-parsecmd) and formatting (-formatcmd) of the date string. These options overrides -dateformat. See "DATE FORMATS" below.

-formatcmd => \&callback

See -parsecmd above and "DATE FORMATS" below.

-background => color

Sets the background color for the Entry subwidget. Note that the dropdown calendar is not affected by this option. See also -boxbackground, -buttonbackground and -todaybackground.

-buttonbackground => color

Sets the background color for all button in the dropdown calendar.

-boxbackground => color

Sets the background color for the dropdown widget (not including the buttons).

-todaybackground => color

Sets the background color for the button representing the current date.

-font => font

Sets the font for all subwidgets.

-configcmd => \&callback

Called for every day button in the calendar while month configuration. A hash with the keys -date, -widget, and -datewidget is passed to the callback. The -date parameter is an array reference containing day, month, and year. For empty buttons this parameter is undefined. The -widget parameter is a reference to the current Tk::DateEntry widget, and the -datewidget parameter is a reference to the current day button. A sample callback:

sub configcmd {
   my(%args) = @_;
   my($day,$month,$year) = @{$args->{-date}};
   my $widget            =   $args->{-widget};
   my $datewidget        =   $args->{-datewidget};
   $datewidget->configure(...);
   ...
}

The callback is called after initial configuration of a day widget, that is, i.e. the label and the background color is already set. Note that day buttons keep their configuration while switching between months.

-daynames => [qw/Sun Mon Tue Wed Thu Fri Sat/]

Specifies the daynames which is used in the calendar heading. The default is [qw/S M Tu W Th F S/]. Note that the array MUST begin with the name of Sunday, even if -weekstart specifies something else than 0 (which is Sunday). See also "WEEKS" below.

It is also possible to use the special value locale to use the daynames from the current locale.

-weekstart => number

Use this if you don't want the weeks to start on Sundays. Specify a number between 0 (Sunday) and 6 (Saturday). See "WEEKS" below.

-headingfmt => string

Format for the month name heading. The month name heading is created by calling strftime(format,0,0,0,1,month,year). Default format is '%B %Y'. Note that only month and year will have sensible values, including day and/or time in the heading is possible, but it makes no sense.

If POSIX is not available then this option has no effect and the month name heading format will just be "%m/%Y".

-state => string

'normal', 'disabled' or 'readonly'. The latter forces the user to use the drop down, editing in the Entry subwidget is disabled.

-width => number

Width of the Entry subwidget, default is 10 (which fits the default date format MM/DD/YYYY).

All other options are handled by the Entry subwidget.

DATE FORMATS

The default date format is MM/DD/YYYY. Since Tk::DateEntry has to parse the date to decide which month to display, you can't specify strftime formats directly (like "-dateformat => 'Date: %D. %B'").

The "builtin" date formats are:

  • -dateformat => 1 - MM/DD/YYYY (default)

  • -dateformat => 2 - YYYY/MM/DD

  • -dateformat => 3 - DD/MM/YYYY

  • -dateformat => 4 - YYYY-MM-DD

Trailing fields that are missing will be replaced by the current date, if the year is specified by one or two digits, the widget will guess the century by using a "100 year window".

If you're not satisified with any of these formats, you might specify your own parse and format routine by using the -parsecmd and -formatcmd options.

The -parsecmd subroutine will be called whenever the pulldown is opened. The subroutine will be called with the current content of -textvariable as the only argument. It should return a three element list: (year, month, day). Any undefined elements will be replaced by default values.

The -formatcmd subroutine will be called whenever the user selects a date. It will be called with three arguments: (year, month, day). It should return a single string which will be assigned to the -textvariable.

See "EXAMPLES" below.

WEEKS

The default is to display the calendar the same way as the unix cal(1) command does: Weeks begin on Sunday, and the daynames are S, M, Tu, W, Th, F, and S.

However, some people prefer to start the weeks at Monday (saving both Saturday and Sunday to the weekEND...) This can be achived by specifying -weekstart=>1. -weekstart=>0 causes the week to start at Sunday, which is the default. If you have a very odd schedule, you could also start the week at Wednesday by specifying -weekstart=>3.....

If you don't like the "cal" headings, you might specify something else by using the -daynames option.

See "EXAMPLES" below.

EXAMPLES

The simplest way:

$parent->DateEntry->pack;

Other daynames:

If you want the "locale's abbreviated weekday name" you do it like this:

$parent->DateEntry(-daynames=>'locale')->pack;

which is short for:

use POSIX qw/strftime/;
my @daynames=();
foreach (0..6) {
	push @daynames,strftime("%a",0,0,0,1,1,1,$_);
}
$parent->DateEntry(-daynames=>\@daynames)->pack;

Other date formats:

A Norwegian would probably do something like this:

my $dateentry=$parent->DateEntry
	(-weekstart=>1,
	 -daynames=>[qw/Son Man Tir Ons Tor Fre Lor/],
	 -parsecmd=>sub {
		my ($d,$m,$y) = ($_[0] =~ m/(\d*)\/(\d*)-(\d*)/);
		return ($y,$m,$d);
	 },
	 -formatcmd=>sub {
		sprintf ("%d/%d-%d",$_[2],$_[1],$_[0]);
	 }
	)->pack;

Note that this -parsecmd will return (undef,undef,undef) even if one or two of the fields are present. A more sophisticated regex might be needed....

CAVEATS

If neither Date::Calc nor Date::Pcalc are available, then Tk::DateEntry uses timelocal(), localtime() and strftime(). These functions are based on the standard unix time representation, which is the number of seconds since 1970-01-01. This means that in this case Tk::DateEntry doesn't support dates prior to 1970, and on a 32 bit computer it doesn't support dates after 2037-12-31.

Future perl versions (possibly beginning with 5.10.1) will have support for 64 bit times.

TODO

Use DateTime::Locale instead of POSIX for localized day and month names.

SEE ALSO

Tk::Entry, Tk::Button, Tk::ChooseDate.

AUTHOR

Hans J. Helgesen <hans.helgesen@novit.no>, October 1999.

Current maintainer is Slaven Rezic <slaven@rezic.de>.