NAME

Tk::MiniCalendar - simple calendar widget for date selection

SYNOPSIS

 use Tk;
 use Tk::MiniCalendar;

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

cpanm Tk::MiniCalendar

perl -MCPAN -e shell
install Tk::MiniCalendar