NAME

Gtk2::Ex::DateSpinner -- year/month/day date entry using SpinButtons

SYNOPSIS

use Gtk2::Ex::DateSpinner;
my $ds = Gtk2::Ex::DateSpinner->new (value => '2008-06-14');

WIDGET HIERARCHY

Gtk2::Ex::DateSpinner is (currently) a subclass of Gtk2::HBox, though it's probably not a good idea to rely on that.

Gtk2::Widget
  Gtk2::Container
    Gtk2::Box
      Gtk2::HBox
        Gtk2::Ex::DateSpinner

DESCRIPTION

Gtk2::Ex::DateSpinner displays and changes a year, month, day date using three Gtk2::SpinButton fields. The day of the week is shown to the right.

+------+   +----+   +----+
| 2008 |^  |  6 |^  | 14 |^   Sat
+------+v  +----+v  +----+v

There's many ways to enter or display a date. This style is good for clicking to a nearby date but also allows a date to be typed in if a long way away.

If a click or entered value takes the day outside the days in the month then it wraps around to the next or previous month. Likewise the month wraps around to the next or previous year. When typing in a number the day of the week display updates when you press enter.

A paste of an ISO format YYYY-MM-DD date into any of the day, month or year fields sets the three fields to that value. Whitespace at the start or end of a paste is ignored.

Day of the week and date normalization calculations use Date::Calc so they're not limited to the system time_t (which may be as little as 1970 to 2038 on a 32-bit system). Day of the week display uses strftime() (via POSIX::Wide to allow non-ASCII) so gets the usual LC_TIME localizations which are established by setlocale() at Perl startup or Gtk initialization. The year/month/day tooltips (identifying the fields as year/month/day) use Gtk message translations.

See examples/simple.pl for a complete program creating a DateSpinner. See examples/builder.pl for similar using Gtk2::Builder.

FUNCTIONS

$ds = Gtk2::Ex::DateSpinner->new (key=>value,...)

Create and return a new DateSpinner widget. Optional key/value pairs set initial properties per Glib::Object->new. Eg.

my $ds = Gtk2::Ex::DateSpinner->new (value => '2008-06-14');

$ds->set_today

Set the value in $ds to today's date (today in the local timezone).

PROPERTIES

value (string, default "2000-01-01")

The current date value, as an ISO format "YYYY-MM-DD" string. When you read this the day and month are always "normalized", so MM is 01 to 12 and DD is 01 to 28,29,30 or 31 (according to how many days in the particular month).

The default 1 January 2000 is meant to be fairly useless and you should set it to something that makes sense for the particular application.

There's very limited validation on the value string, so don't set garbage.

SEE ALSO

Gtk2::Ex::DateSpinner::CellRenderer, Date::Calc, POSIX::Wide

Gtk2::SpinButton, Gtk2::Calendar, Gtk2::Ex::CalendarButton, Gtk2::Ex::DateRange

HOME PAGE

http://user42.tuxfamily.org/gtk2-ex-datespinner/index.html

LICENSE

Gtk2-Ex-DateSpinner is Copyright 2008, 2009, 2010, 2013, 2019 Kevin Ryde

Gtk2-Ex-DateSpinner is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Gtk2-Ex-DateSpinner is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Gtk2-Ex-DateSpinner. If not, see http://www.gnu.org/licenses/.