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 in stead 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 entry, or contains invalid data, 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.
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
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.
-
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.
- -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.pm 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
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" 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:
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 1/1/1970. 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 12/31/2037.
SEE ALSO
AUTHOR
Hans J. Helgesen <hans.helgesen@novit.no>, October 1999.
Current maintainer is Slaven Rezic <slaven@rezic.de>.