NAME

Tk::MiniCalendar - simple calendar widget for date selection

SYNOPSIS

use Tk;
my $minical = <PARENT>->MiniCalendar(-day => $dd,
-month => $mm,
-year => $yyyy,
-day_names => \@DAYNAMES,
-month_names => \@MONTHNAMES);
$minical->pack;
# or:
$minical->grid( ... );
my ($yyyy, $mm, $dd) = $minical->date; # --> (2004, 09, 16)

DESCRIPTION

Tk::MiniCalendar provides a tiny calendar widget which can be used to select valid dates.

Graphical Representation

The widget looks like:

+------------------------------+
|<< < September 2004 > >>|
| |
| Mo Di Mi Do Fr Sa So |
| 1 2 3 4 5 |
| 6 7 8 9 10 11 12 |
| 13 14 15 [16] 17 18 19 |
| 20 21 22 23 24 25 26 |
| 27 28 29 30 |
+------------------------------+

The year can be entered directly into the corresponding entry field. The "<<" and ">>" buttons allow the user to scroll one year back or forth and the "<" and ">" buttons can be used for scrolling through the months of a year. The month can also be selected directly from a pulldown menu which can be invoked by clicking the month name.

Clicking with mouse button one on a day selects that day. The selected day can be retrieved with the $minical->date() method.

Handlers

It is possible to register user provided handlers for the MiniCalendar widget. You may for example register a "double-button-1" handler which is invoked by doubleclicking one of the days.

Example:

$minical->register('<Double-1>', \&double_1_handler);
$minical->register('<Button-3>', \&button_3_handler);

Only the following event specifications are recognized:

<Button-1> <Double-1>
<Button-2> <Double-2>
<Button-3> <Double-3>
<Display-Month>

If one of those events occurs on one of the displayed days, the registered callback is invoked with the following parameters:

$yyyy, $mm, $dd (year, month and day)

NOTE: If there are two handlers for <Button-n> and <Double-n> then both handlers are invoked in case of a double-button-n event because a double-button-n event is also a button-n event.

A callback routine for the special "event" <Display-Month> will be called each time the minicalendar is updated i.e. when a month has been displayed. This can be used to hilight certain days with different colors. See also hilight method below. Note that in this case the $dd parameter is always set to 1.

EXAMPLE

Here is a fullblown example for the usage of Tk::MiniCalendar

use Tk;
use strict;
my $top = MainWindow->new;
my $frm1 = $top->Frame->pack; # Frame to place MiniCalendar in
my $minical = $frm1->MiniCalendar->pack;
my $frm2 = $top->Frame->pack; # Frame for Ok Button
my $b_ok = $frm2->Button(-text => "Ok",
-command => sub {
my ($year, $month, $day) = $minical->date;
print "Selected date: $year/$month/$day\n";
exit;
},
)->pack;
MainLoop;

OPTIONS

The following options can be specified for Tk::MiniCalendar:

  • -day => <day>

    Sepcify first selected day.

  • -month => <month>

    Sepcify first selected month.

  • -year => <year>

    Sepcify first selected year.

  • -day_names => <array_ref>

    Reference to an array which holds the labels for the day names. This can be used to define labels for another language.

  • -month_names => <array_ref>

    Reference to an array which holds the labels for the month names.

  • -bg => <color>

    Background color. Note that this changes only the outer part of the widget. Day name labels and the main area of the calendar are not affected.

  • -bg_color => <color>

    Background color for the area which contains the day numbers.

  • -fg_color => <color>

    Foreground color for the day numbers.

  • -bg_label_color => <color>

    Background color for the day name labels. Should be the same as -bg.

  • -fg_label_color => <color>

    Foreground color for the day name labels.

  • -bg_sel_color => <color>

    Background color for the selected day.

  • -fg_sel_color => <color>

    Foreground color for the selected day.

METHODS

The following methods are provided by Tk::MiniCalendar:

my ($year, $month, $day) = $minical->date()

Returns the selected date from Tk::MiniCalendar. Day and month numbers are always two digits (with leading zeroes).

$minical->select_date($year, $month, $day)

Selects a date and positions the MiniCalendar to the corresponding year and month. The selected date is hilighted.

$minical->prev_day()

Sets the calendar to the previous day. The selected date is hilighted.

$minical->next_day()

Sets the calendar to the next day. The selected date is hilighted.

$minical->display_month($year, $month)

Displays the specified month. When a callback for the <Display-Month> event has been registered it will be called with ($year, $month, 1) as parameters.

$minical->hilight($year, $month, $day, $background, $foreground)

This method can be used to hilight the specified day with different background/foreground colors. May be used in a callback for the <Display-Month> event.

AUTHOR

Lorenz Domke, <lorenz.domke@gmx.de>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Lorenz Domke

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.