|
|
| |
Date(3) |
User Contributed Perl Documentation |
Date(3) |
Tk::Date - a date/time widget for perl/Tk
use Tk::Date;
$date_widget = $top->Date->pack;
$date_widget->get("%x %X");
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).
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.
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.
Some options are only available if the prerequisite modules from the Tk-GBARR
distribution are installed too.
- -allarrows
- If true then all entry fields will obtain arrows. Otherwise 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 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. 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. 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 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 setting 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, followed 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 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.
- -readonly
- "readonly" means only that the entry fields are readonly.
However, the user is still able to use the increment/decrement buttons to
change the date value. Use "-state =>
"disabled"" to make a date widget completely
unchangable by the user.
- -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.
- -state
- Specifies one of two states for the date widget:
"normal" 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 setting 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, followed 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 function (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 argument.
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
Sunday.
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.
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;
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. Otherwise 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.
- 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 tieying 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
Tk, Tk::NumEntryPlain, Tk::FireButton, POSIX
Slaven Rezic <eserte@cs.tu-berlin.de>
Copyright (C) 1997, 1998, 1999, 2000, 2001, 2005, 2007, 2008, 2010 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.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |