The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Gtk2-Ex-Clock-11
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 it costs the program is a timer waking once a minute to change a Gtk2::Label.

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 (string or DateTime::TimeZone, default local time)

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 its information and a DateTime object strftime is used for the display. The strftime method may have extra conversions 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, 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 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 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 POSIX::strftime and DateTime.

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 in 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 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.7) 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, so you probably won't be using threads. Again you can use a DateTime::TimeZone object if you're nervous.

SEE ALSO

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

HOME PAGE

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

LICENSE

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