NAME

Gtk2::Ex::DateEntry -- Widget for entering dates

SYNOPSIS

 use Gtk2::Ex::DateEntry;
 $de = Gtk2::Ex::DateEntry->new;
 $de->set_value('10132009');
 $de->get_value;

WIDGET HIERARCHY

    Gtk2::Widget
      Gtk2::Entry
        Gtk2::Ex::DateEntry

DESCRIPTION

Gtk2::Ex::DateEntry displays and edits a date in MM/DD/YYYY format with some convienence functions.

Use the up and down keys to modify the invidual components of the value, and the left and right keys to navigate between them. Pressing up or down while the entire contents of the entry is selected (such as when you focus-in) modifies the value in 7 day increments.

The date is displayed in the widget in MM/DD/YYYY format, but the results from get_value are in the format YYYY-MM-DD. The reason being that dates are most commonly (in the west) displayed as MM/DD/YYYY, however when programming it is much more common to encounter dates in the format YYYY-MM-DD.

You can also type a date into the entry into various formats, which will be parsed and then displayed in the entry in MM/DD/YYYY format. Below are some examples of things you can enter into the widget and the resulting internal and display values. Also note that whitespace is ignored during parsing.

  INPUT         VALUE         DISPLAY
  08/11/1986    1986-08-11    08/11/1986
  08-11-1986    1986-08-11    08/11/1986
  08.11.1986    1986-08-11    08/11/1986
  08111986      1986-08-11    08/11/1986
  081186        1986-08-11    08/11/1986

Entering a partial date (just year, month, day) will result in the remaining components being filled in for you. If the widget is currently set to a date, the current values will be used. If the widget is not set to a date, the current system date will be used to fill in the missing values.

  STARTING       INPUT     RESULT
  1986-08-11     10        1986-08-10  # 1-2 digits, setsday of month
  1986-08-11     1231      1986-12-31  # 3-4 digits sets month, day
  1986-08-11     2009      2009-12-31  # 4 digits (> 1231) sets year

This may all seem confusing, just try playing around with the widget. It should generally just do what you would expect.

FUNCTIONS

$te = Gtk2::Ex::DateEntry->new ()

Create and return a new DateEntry widget.

$te->get_selected_component

Returns the currently selected component - any of 'month', 'day', 'year'. An emptry string will be returned if the selection bounds contains more or less than 1 individual component, and will return 'all' if all componentes are selected.

$te->set_selected_component($component)

Highlights the given component, which can then be edited by typing over it or pressing the arrow keys up or down. You can pass the values 'month', 'day', 'year', 'all', 'none', undef, or an emptry string;

$te->set_today

Set the widget to the current date.

$te->get_value

Return the current date in YYYY-MM-DD format.

$te->set_value ($value)

Parses the content of $value then sets the widget to the resulting date.

SIGNALS

value-changed

Emitted after a succesful value change.

SEE ALSO

Gtk2::Ex::DateEntry::CellRenderer, Gtk2::Ex::FormFactory::DateEntry

AUTHOR

Jeffrey Hallock <jeffrey.ray at ragingpony com>

BUGS

None known. Please send bugs to <jeffrey.ray at ragingpony dot com>. Patches and suggestions welcome.

LICENSE

Gtk2-Ex-DateEntry is Copyright 2009 Jeffrey Ray Hallock

Gtk2-Ex-DateEntry 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-DateEntry 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-DateEntry. If not, see http://www.gnu.org/licenses/.