Tk::MiniCalendar - simple calendar widget for date selection


 use Tk;
 use Tk::MiniCalendar;

 my $minical = <PARENT>->MiniCalendar(-day   => $dd, 
                                      -month => $mm, 
                                      -year  => $yyyy,
                                      -day_names   => \@DAYNAMES,
                                      -month_names => \@MONTHNAMES);

 # or:
 $minical->grid( ... );

 my ($yyyy, $mm, $dd) = $minical->date; # --> (2004, 09, 16)


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.


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.


 $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>


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.


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

 use Tk;
 use Tk::MiniCalendar;

 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";


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.


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.


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


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.


Lorenz Domke, <>


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.