/ 
Tk-MiniCalendar-0.14
River stage zero No dependents
/ Tk::MiniCalendar

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.