/ 
Gtk2-Ex-Clock-3
River stage zero No dependents
/ Gtk2::Ex::Clock

NAME

Gtk2::Ex::Clock -- simple digital clock widget

SYNOPSIS

use Gtk2::Ex::Clock;

my $clock = Gtk2::Ex::Clock->new ();

# or a specified format, or a different timezone
my $clock = Gtk2::Ex::Clock->new (format => '%I:%M<sup>%P</sup>',
                                  timezone => 'America/New_York');

# or a DateTime::TimeZone object for the timezone
use DateTime::TimeZone;
my $timezone = DateTime::TimeZone->new (name => 'America/New_York');
my $clock = Gtk2::Ex::Clock->new (timezone => $timezone);

WIDGET HIERARCHY

Gtk2::Ex::Clock is a subclass of Gtk2::Label.

Gtk2::Widget
   Gtk2::Misc
      Gtk2::Label
         Gtk2::Ex::Clock

DESCRIPTION

Gtk2::Ex::Clock displays a digital clock. The default is 24-hour format "%H:%M" local time, like "14:59". The properties below allow other formats and/or a specified timezone. Pango markup like "<bold>" can be included for font effects.

Gtk2::Ex::Clock is designed to be light weight and suitable for use somewhere unobtrusive in a realtime or semi-realtime application. The right-hand end of a menubar is a good place for instance, depending on user preferences. In the default minutes display all it costs the program is a timer waking once a minute to change a Gtk2::Label.

FUNCTIONS

Gtk2::Ex::Clock->new (key=>value,...)

Create and return a new clock widget. Optional key/value pairs can set initial properties as per Glib::Object->new. For example,

my $clock = Gtk2::Ex::Clock->new (format => '%a %H:%M',
                                  timezone => 'Asia/Tokyo');

PROPERTIES

format (string, default "%H:%M")

An strftime format string for the date/time display. See the strftime man page or the GNU C Library manual for possible % conversions.

Date conversions can be included to show a day or date as well as the time. This is good for a remote timezone where you might not be sure if it's today or tomorrow there yet.

my $clock = Gtk2::Ex::Clock->new (format => 'London %d%m %H:%M',
                                  timezone => 'Europe/London');

Pango markup can be used for bold, etc. For example "am/pm" as superscript.

my $clock = Gtk2::Ex::Clock->new(format=>'%I:%M<sup>%P</sup>');

Newlines can be included for multi-line display, for instance date on one line and the time below it. The various Gtk2::Label and Gtk2::Misc properties can be used to control centring. For example,

my $clock = Gtk2::Ex::Clock->new (format  => "%d %b\n%H:%M",
                                  justify => 'center',
                                  xalign  => 0.5);
timezone (string or DateTime::TimeZone, default local time)

The timezone to use in the display. An empty string or undef (undef is the default) means local time.

For a string, the TZ environment variable ($ENV{'TZ'}) is set to format the time (and restored so other parts of the program are not affected). See the tzset man page or the GNU C Library manual under "TZ Variable" for possible settings.

For a DateTime::TimeZone object the time display uses its information and a DateTime object strftime method. That method may have some extra conversions in the format string over what the C library offers.

resolution (integer, default from format)

The resolution, in seconds, of the clock. The default 0 means look at the format to decide whether seconds is needed or minutes is enough. Formats using %S and various other mostly-standard forms like %T and %X are recognised as seconds, and anything else is minutes. If that comes out wrong you can force it by setting this property.

Incidentally, if you're only displaying hours then you probably don't want hour resolution, since a system time change won't be recognised until the requested resolution worth of real time has elapsed.

The properties of Gtk2::Label and Gtk2::Misc can be used to variously control padding, alignment, etc. See the examples directory in the sources for some complete programs displaying clocks in various forms.

LOCALE

For a plain string timezone the POSIX strftime function gets localized day names etc from LC_TIME in the usual way. Generally Perl does a suitable setlocale(LC_TIME) at startup so your environment settings take effect automatically.

For a DateTime::TimeZone object the DateTime strftime gets localizations from the DateTime->DefaultLocale (see DateTime). Generally you must call to set DefaultLocale yourself at some point early in the program.

The format string can include unicode in Perl's usual wide-char fashion. But for POSIX strftime the format string is converted to the locale charset and then back to unicode, so you'll be limited to what's representable in the locale charset.

IMPLEMENATION

The clock is implemented by updating a Gtk2::Label under a timer. This is simple, and makes good use of the label widget's text drawing code, but it does mean that with a variable width font the size of the widget can change as the time changes. For minutes display any resizes are hardly noticable, but for seconds it may be best to use a fixed-width font, or to set_size_request for a fixed size (initial size plus a few pixels say), or even try a NoShrink (see Gtk2::Ex::NoShrink).

The way TZ is temporarily changed to implement a non-local timezone could be slightly on the slow side. The GNU C Library (as of version 2.7) for instance opens and re-reads a zoneinfo file on each change. Doing that (twice) each minute is fine, but for seconds you may prefer DateTime::TimeZone. Changing TZ probably isn't thread safe either, though rumour has it you have to be very careful with threads and Gtk2-Perl anyway, so you probably won't be using threads. Again you can use a DateTime::TimeZone object if you're nervous.

HOME PAGE

http://www.geocities.com/user42_kevin/gtk2-ex-clock/index.html

LICENSE

Gtk2-Ex-Clock is Copyright 2007, 2008 Kevin Ryde

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

SEE ALSO

strftime(3), tzset(3), Gtk2, Gtk2::Label, Gtk2::Misc, DateTime::TimeZone, DateTime