date(3)

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 (only with installed Tk::NumEntryPlain widget).
� Selecting up and down arrow buttons will increment or
decrement the value of the active field (only with
installed Tk::FireButton widget).

The Date/Time Format

Unlike Java, Perl does not have a date/time object. How ever, 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

Some options are only available if the prerequisite mod
ules from the Tk-GBARR distribution are installed too.

-allarrows: If true then all entry fields will obtain arrows. Oth
erwise only one arrow pair for each date and time will
be drawn. This option can be set only while creating
the widget. This option needs the Tk::NumEntry widget
to be installed.
-bell: Specifies a boolean value. If true then a bell will
ring if the user attempts to enter an illegal charac
ter (e.g. a non-digit).
-check: If set to a true value, Tk::Date makes sure that the
user can't input incorrect dates. This option can be
set only while creating the widget.
-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. This option can be set only
while creating the widget.; Examples:

-choices => 'now'
-choices => ['today', 'yesterday', 'tomorrow']
It is possible to specify user-defined values. Userdefined 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 following arguments: reference of date
widget, field specifier, increment value. The field
specifier is either "date" or "time" or one of "H",
"M", "S", "d", "m", "y" for the possible time and date
fields.
-datefmt: This is a sprintf/printf-like format string for set
ting the order and format of the date entries. By
default, the format string is "%2d.%2m.%4y" meaning a
two-character wide day entry, followed by a dot, fol
lowed by a two-character wide month entry, another
dot, and finally a four-character wide year entry. The
characters are the same as in the strftime function
(see POSIX). It is also possible to use the 'A' letter
for displaying the (localized) weekday name. See below
in the EXAMPLES section for a more US-like date
format. This option can be set only while creating the
widget.
-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). This option can be set only while creating
the widget.
-fields: Specifies which fields are constructed: date, time or
both. Defaults to both. This option can be set only
while creating the widget.
-incbitmap: Sets the bitmap for the increase button. Defaults to
FireButton's default increase bitmap.
-monthmenu: Use an optionmenu for input of the month.
-monthnames: Replace the standard month names (either English or as
supplied by the locale system) with a user-defined
array. The argument should be a reference to a hash
with 12 elements.
-precommand: Specifies a callback which is executed every time when
an arrow button is selected and before actually exe
cute 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.
-readonly: If set to a true value, then it is only possible to
change the values by pressing the increment/decrement
buttons. This option is only useful if "-allarrows" is
also set and if the user has "Tk::NumEntry" installed
on his system.
-repeatinterval: Specifies the amount of time between invokations of
the increment or decrement. Defaults to 50 millisec
onds.
-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.
-state: Specifies one of two states for the date widget: "nor
mal" or "disabled". If the date widget is disabled
then the value may not be changed using the user
interface (that is, by typing in the entry subwidgets
or pressing on the increment/decrement buttons).
-timefmt: This is a sprintf/printf-like format string for set
ting the order and format of the time entries. By
default, the format string is "%2H.%2M.%2S" meaning a
two-character wide hour entry, followed by a dot, fol
lowed by a two-character wide minute entry, another
dot, and finally a two-character wide seconds entry.
The characters are the same as in the strftime func
tion (see POSIX). This option can be set only while
creating the widget.
-selectlabel: Change label text for choice menu. Defaults to
'Select:'. This option can be set only while creating
the widget.
-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 argu ment. May be unixtime (default) or datehash. This option can be set only while creating the widget.
-variable: Ties the specified variable to the widget. (See Bugs)
-weekdays: Replace the standard weekday names (either English or
as supplied by the locale system) with a user-defined
array. The argument should be a reference to a hash
with seven elements. The names have to start with Sun
day.

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 for mat 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;

NOTES

Please note that the full set of features only available,
if the Tk-GBARR distribution is also installed. However,
the widget also works without this distribution, only
lacking the arrow buttons.

If the POSIX module is available, localised weekday and
month names will be used instead of English names. Other
wise you have to use the -weekday and -monthnames options.
The POSIX strftime function does not work correctly before
version 1.03 (that is, before 5.6.0), so this feature is
disabled for older perl versions.

BUGS/TODO

- The -orient option can be only set while creating the
widget. Also: other options are only settable at create time.
- 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, otherwise tiey
ing does no work: at all
- -from/-to is missing (limit) (or -minvalue, -maxvalue?) - range check (in DateNumEntryPlain::incdec) - am/pm - more interactive examples are needed for some design
issues (how strong: signal errors? ...)
- check date-Function - optionally use Tk::DateEntry for the date part - -command is not fully implemented

AUTHOR

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

docs.sk

komplexný repozitár dokumentácie

Najnavštevovanejšie