NAME

Tk::ChooseDate - Popup Calendar with support for dates prior to 1970

SYNOPSIS

$chooseDate = $parent->ChooseDate(?options?);

EXAMPLE

    use Tk;
    use Tk::ChooseDate;

    my $mw=tkinit;
    $mw->ChooseDate(
        -textvariable=>\$date,
        -command=>sub{print "$date\n"},
    )->pack(-fill=>'x', -expand=>1);
    MainLoop;

SUPER-CLASS

ChooseDate is derived from the Frame class. This megawidget is comprised of an Label and Button allowing a popup Toplevel with an embedded Canvas.

DESCRIPTION

ChooseDate is yet-another-date-choosing widget via a popup calendar. It was created because Tk::DateEntry and Tk::DatePick do not allow support for dates prior to 1970. Besides this major item, I personally think that this is a nicer-looking widget with similar functionality of the others - but much more user friendly as dates can be chosen quickly and easily.

Although the widget looks much like an Entry - it is not. It is a sunken label. This means that the date is not directly editable by the user; yes - this is by design. That said however, the programmer can get and set the date using the mehods described herein.

WIDGET-SPECIFIC OPTIONS

All options not specified below are delegated to the label widget.

Name: activeLabel

Class: ActiveLabel

Switch: -activelabel

Specifies if the label offers the same binding functionality as the calendar button. This is a boolean value. Setting this to 1 means that clicking on the label will toggle the popup window just as if the user clicked on the button. Setting this to 0 will disable this functionality and force the user to click on the button to get the popup.

Name: arrowColor

Class: ArrowColor

Switch: -arrowcolor

Specifies the color of the text for the increment/decrement arrows.

Name: arrowActiveColor

Class: ArrowActiveColor

Switch: -arrowactivecolor

Specifies the color of the text for the increment/decrement arrows when mouse hovers over them.

Name: command

Class: Command

Switch: -command

Specifies a function to call when a selection is made in the popped up calendar. It is passed the widget and date string. This function is called after the variable has been assigned the value.

Name: dateColor

Class: DateColor

Switch: -datecolor

Specifies the color of the text for the date numbers within the calendar.

Name: dateFormat

Class: DateFormat

Switch: -dateformat/-datefmt

Specifies the format of the date. Must be an integer between 1 and 3. Where:

-dateformat => 1

MM/DD/YYYY

-dateformat => 2

YYYY/MM/DD (default)

-dateformat => 3

DD/MM/YYYY

Name: dateOfWeekColor

Class: DaysOfWeekColor

Switch: -daysofweekcolor

Specifies the color of the text for the days of the week headings.

Name: highlightColor

Class: HighlightColor

Switch: -highlightcolor

Specifies the color to highlight the chosen date.

Name: language

Class: Language

Switch: -language

Specifies the language of the calendar. Please see Date::Calc for more documentation on how languages are handled.

You must specify one of the following exactly:

English

French

German

Spanish

Portuguese

Dutch

Italian

Norwegian

Swedish

Danish

Finnish

Hungarian

Polish

Romanian

Name: lineColor

Class: LineColor

Switch: -linecolor

Specifies the color of the lines on the calendar. If set to undef then no lines will show.

Name: monthColor

Class: MonthColor

Switch: -monthcolor

Specifies the color of text for the month name.

Name: orthodox

Class: Orthodox

Switch: -orthodox

Specifies the order of the days of the week in the calendar header. This is a boolean value with a default of 1.

-orthodox => 0

Mon Tue Wed Thu Fri Sat Sun

-orthodox => 1

Sun Mon Tue Wed Thu Fri Sat

Name: repeatDelay

Class: RepeatDelay

Switch: -repeatdelay

Specifies the amount of time (in ms) before the firebutton callback is first invoked after the Button-1 is pressed over the increment/decrement arrows.

Name: repeatInterval

Class: RepeatInterval

Switch: -repeatinterval

Specifies the amount of time between updates to the date changes if Button-1 is pressed and held over the increment/ decrement arrows.

Switch: -state

Specifies the state of the widget. Choose between normal or disabled.

Switch: -textvariable

Specifies a reference to a scalar variable. The value of the variable is a text string date to be displayed inside the widget. If the variable value changes then the widget will automatically update itself to reflect the new value.

Name: yearColor

Class: YearColor

Switch: -yearcolor

Specifies the color of text for the year name.

WIDGET METHODS

If you wish to use the Tk::Label or Tk::Button methods then you will have to use the Subwidget method to get the advertised objects. Otherwise currently only two public methods exist.

$choosedate->get

Gets the chosen date. The returned value depends context of the request. If being stored to a scalar then the entire string will be returned as set by the -dateformat option. If being stored to an array then the year, month and day are returned in an array format in that particular order - (Y,M,D)

$choosedate->set(datehash)

Sets any or all of the portions of the date. The hash keys must be be:

y,m,d

Example

$choosedate->set( y=>2005, m=>5, d=>5) will set the date to May 5, 2005.

Alternatively

You can just change one of the date parameters $choosedate->set( m=>11) change the month to November

MANIPULATING THE DATES

In order to allow quick access to choosing the date, arrows have been provided to increment or decrement the year and month. Firebutton-like functionality exists with these arrows. So if you hold down the mouse button, the dates will continuously increment or decrement. Of course you can feel free to just click numerous times for the same, albeit slower result.

When using the firebutton-like feature on the YEAR, the program will track the X position of your mouse. If your mouse remains over the arrows then the years will increment or decrement by 1. If however your mouse moves at least 40 pixels in the direction of the arrow then the years will increment or decrement by 10. This feature cannot be shut-off in this version.

ADVERTISED WIDGETS

The following widgets are advertised:

label

The label widget (which really looks like an entry).

button

The button widget to the right of the label.

canvas

The canvas widget which houses the actual calendar.

toplevel

The toplevel popup widget which houses the canvas.

KNOWN BUGS

Fonts

Fonts cannot be adjusted.

Language

Ths module has now been tested using the varying language options of Date::Calc. All disclaimers for that module apply here as well. i.e. the following quote may be relevant:

"Note that in the current implementation of this package, the selected language is a global setting valid for ALL functions that use the names of months, days of week or languages internally, valid for ALL PROCESSES using the same copy of the Date::Calc shared library in memory!"

To avoid this potential pitfall, Tk::ChooseDate stores the current language at startup and resets it on-the-fly. Before the call to Calendar is made, the language is changed to the one specified in the user options. After the call returns the language is immediately set back to the original. This likely has some speed implications on slower computers - but I do not note much of a difference and I was not intending on benchmarking it.

PREREQUISITES

Tk

Date::Calc

AUTHOR

Jack Dunnigan dunniganj<at>cpan<dot>org

Copyright (c) 2005 Jack Dunnigan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Portions of this code were based on Tk::DateEntry and Tk::DatePick so my thanks go out to the authors of those modules.

Thanks also to Ala Qumsieh and Rob Seegal for providing feedback.

cpanm Tk::ChooseDate

perl -MCPAN -e shell
install Tk::ChooseDate