NAME

Tk::Date - a date/time widget for perl/Tk

SYNOPSIS

    use Tk::Date;
    $date_widget = $top->Date->pack;
    $date_widget->get("%x %X");

DESCRIPTION

Tk::Date implements a date/time widget. There are three ways to input a date:

• Using the keyboard to input the digits and the tab key or the mouse pointer to move focus between fields.

• Using up and down cursor keys to increment/decrement the date.

• Selecting up and down arrow buttons will increment or decrement the value of the active field.

The Date/Time Format

Unlike Java, Perl does not have a date/time object. However, it is possible to use the unix time (seconds since epoch, that is 1st January 1970) as a replacement. This is limited, since on most architectures, the valid range is between 14th December 1901 and 19th January 2038. For other dates, it is possible to use a hash notation:

    { y => year,
      m => month,
      d => day,
      H => hour,
      M => minute,
      S => second }

The abbreviations are derivated from the format letters of strftime. Note that year is the full year (1998 instead of 98) and month is the real month number, as opposed to the output of localtime(), where the month is subtracted by one.

In this document, the first method will be referred as unixtime and the second method as datehash.

STANDARD OPTIONS

Tk::Date descends from Frame and inherits all of its options.

-orient

Specified orientation of the increment and decrements buttons. May be vertical (default) or horizontal.

WIDGET-SPECIFIC OPTIONS

-bell

Specifies a boolean value. If true then a bell will ring if the user attempts to enter an illegal character (e.g. a non-digit).

-check

If set to a true value, Tk::Date makes sure that the user can't input incorrect dates.

-choices

Creates an additional choice button. The argument to -choices must be one of now, today, yesterday or tomorrow, or an array with a combination of those. If only one is used, only a simple button is created, otherwise an optionmenu.

Examples:

        -choices => 'now'
        -choices => ['today', 'yesterday', 'tomorrow']

It is possible to specify user-defined values. User-defined values should be defined as array elements with two elements. The first element is the label for the button or optionmenu entry. The second element specifies the time associated with this value. It may be either a date hash (missing values are set to the current date) or a subroutine which calculates unix seconds.

Here are two examples. The first defines an additional optionmenu entry for this year's christmas and the second defines an entry for the day before yesterday.

        -choices => ['today',
                     ['christmas' => { 'm' => 12, 'd' => 25}]
                    ]
        -choices => ['today',
                     'yesterday',
                     ['the day before yesterday' => sub { time()-86400*2 }]
                    ]

-command

Specifies a callback which is executed every time after an arrow button is selected. The callback is called with the date widget as its argument.

-decbitmap

Sets the bitmap for the decrease button. Defaults to FireButton's default decrease bitmap.

-editable

If set to a false value, disables editing of the date widget. All entries are converted to labels and there are no arrow buttons. Defaults to true (widget is editable).

-fields

Specifies which fields are constructed: date, time or both. Defaults to both.

-incbitmap

Sets the bitmap for the increase button. Defaults to FireButton's default increase bitmap.

-precommand

Specifies a callback which is executed every time when an arrow button is selected and before actually execute the increment or decrement command. The callback is called with following arguments: date widget, type (either date or time) and increment (+1 or -1). If the callback returns with a false value, the increment or decrement command will not be executed.

-repeatinterval

Specifies the amount of time between invokations of the increment or decrement. Defaults to 50 milliseconds.

-repeatdelay

Specifies the amount of time before the increment or decrement is first done after the Button-1 is pressed over the widget. Defaults to 500 milliseconds.

-selectlabel

Change label text for choice menu. Defaults to 'Select:'.

-value

Sets an initial value for the widget. The argument may be unixtime, datehash or now (for the current time).

-varfmt

Specifies the format of the -variable or -value argument. May be unixtime (default) or datehash.

-variable

Ties the specified variable to the widget. (See Bugs)

METHODS

The Date widget supports the following non-standard method:

get([fmt])

Gets the current value of the date widget. If fmt is not given or equal "%s", the returned value is in unix time (seconds since epoch). This should work on all systems.

Otherwise, fmt is a format string which is fed to strftime. strftime needs the POSIX module installed and therefore may not work on all systems.

EXAMPLES

Display a date widget with only the date field in the format dd/mm/yyyy and get the value in the same format:

  $date = $top->Date(-datefmt => '%2d/%2m/%4y',
                     -fields => 'date',
                     -value => 'now')->pack;
  # this "get" only works for systems with POSIX.pm
  $top->Button(-text => 'Get date',
               -command => sub { warn $date->get("%d/%m/%Y") })->pack;

Use the datehash format instead of unixtime:

  $top->Date(-fields  => 'date',
             -value   => {'d' => '13', 'm' => '12', 'y' => '1957'},
             -varfmt => 'datehash',
            )->pack;

BUGS/TODO

 - waiting for a real perl Date/Time object
 - tie interface (-variable) does not work if the date widget gets destroyed
   (see uncommented DESTROY)
 - get and set must use the tied variable, unless tieying does no work
   at all
 - -from/-to (limit) (or -minvalue, -maxvalue?)
 - range check (in DateNumEntryPlain::incdec)
 - am/pm
 - more interactive examples are needed for some design issues (how strong
   signal errors? ...)
 - Wochentag wird beim Hoch-/Runterzaehlen von m und y nicht aktualisiert
 - check date-Funktion

SEE ALSO

Tk, Tk::NumEntryPlain, Tk::FireButton, POSIX

AUTHOR

Slaven Rezic <eserte@cs.tu-berlin.de>

COPYRIGHT

Copyright (c) 1997, 1998, 1999 Slaven Rezic. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Tk::Date

perl -MCPAN -e shell
install Tk::Date