The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Gtk2-Ex-Clock-15
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;  # local time

 # 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 a Clock costs in the program is a timer waking once a minute to change a Gtk2::Label.

If you've got a 7-segment LED style font you can display alarm clock style by selecting that font in the usual ways from an RC file setting or Pango markup. examples/7seg.pl in the sources does it with Pango markup and Harvey Twyman's font. (Unzip into your ~/.fonts directory.)

FUNCTIONS

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

Create and return a new clock widget. Optional key/value pairs 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 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 control centring. For example,

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

The timezone to use in the display. An empty string or undef (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 offsets in it and a DateTime object's $dt->strftime are used for the display. That strftime method may have more conversions than what the C library offers.

The timezone and timezone-string properties act on the same underlying setting. timezone-string is a plain string type and allows TZ strings to be set from Gtk2::Builder.

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, as are DateTime methods like %{iso8601}. 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 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 will variously control padding, alignment, etc. See the examples directory in the sources for some complete programs displaying clocks in various forms.

LOCALIZATIONS

For a string timezone property 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 the usual settings take effect automatically.

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

The format string can include wide-char unicode in Perl's usual fashion, for both plain strftime and DateTime. The plain strftime uses POSIX::Wide::strftime() so characters in the format are not limited to what's available in the locale charset.

IMPLEMENTATION

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 in a variable-width font the size of the widget can change as the time changes. For minutes display any resizes are hardly noticeable, but for seconds it may be best to have a fixed-width font, or to set_size_request 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.10) for instance opens and re-reads a zoneinfo file on each change. Doing that twice (to the new and back to the old) 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 extremely careful with threads and Gtk2-Perl anyway. Again you can use a DateTime::TimeZone object if nervous.

Any code making localized changes to TZ should be careful not to run the main loop with the change in force. Doing so is probably a bad idea for many reasons, but in particular if a clock widget showing the default local time could update to the different TZ. Things like $dialog->run iterate the main loop.

The display is designed for a resolution no faster than 1 second, so the DateTime %N format format for nanoseconds is fairly useless. It ends up displaying a value some 20 to 30 milliseconds past the 1 second boundary because that's when the clock updates. A faster time display is of course possible, capped by some frame rate and the speed of the X server, but would more likely be something more like a stopwatch than time of day. Incidentally Gtk2::Label as used in the Clock here isn't a particularly efficient base for rapid updates.

SEE ALSO

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

HOME PAGE

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

LICENSE

Gtk2-Ex-Clock is Copyright 2007, 2008, 2009, 2010, 2011 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/.