Clock(3)

🕐 Clock(3) — Tk::Clock, bestie edition

okay so this is the manpage for Tk::Clock, straight out of the User Contributed Perl Documentation section (section 3, the library-functions girlies 💅). Sit down, grab a strawberry drink 🍓, and let me tell you about the cutest little clock widget in all of perl-Tk.

✨ NAME ✨

Tk::Clock — a Clock widget with analog and digital display. Both. At once. She's versatile like that. 👑

🌸 SYNOPSIS 🌸

ok so here's the whole vibe in code form, no cap:

  use Tk
  use Tk::Clock;

  $clock = $parent->Clock (?-option => <value> ...?);

  $clock->config (        # These reflect the defaults
      timeZone    => "",
      useLocale   => "C",
      backDrop    => "",

      useAnalog   => 1,
      handColor   => "Green4",
      secsColor   => "Green2",
      tickColor   => "Yellow4",
      tickFreq    => 1,
      tickDiff    => 0,
      useSecHand  => 1,
      handCenter  => 0,
      anaScale    => 100,
      autoScale   => 0,
      ana24hour   => 0,
      countDown   => 0,
      timerValue  => 0,
      localOffset => 0,

      useInfo     => 0,
      infoColor   => "#cfb53b",
      infoFormat  => "HH:MM:SS",
      infoFont    => "fixed 6",

      useDigital  => 1,
      digiAlign   => "center",
      timeFont    => "fixed 6",
      timeColor   => "Red4",
      timeFormat  => "HH:MM:SS",
      dateFont    => "fixed 6",
      dateColor   => "Blue4",
      dateFormat  => "dd-mm-yy",
      );

that's the whole default loadout, and yes those are the actual defaults, I'm not making any of this up 💀

🦋 DESCRIPTION 🦋

This module implements a Canvas-based clock widget for perl-Tk, and it comes with lots of options to change the appearance. Like, a lot a lot. She's giving customizable main character energy.

Both analog and digital clocks are implemented. Both! At the same time! Iconic.

💖 METHODS 💖

⭐ Clock

This is the constructor. She accepts the standard widget options plus all the ones described down in config. So you can just vibe with whatever options you want.

⭐ config

Below is the full rundown of the options/attributes currently available — and bestie, their default value is in between parenthesis, so keep an eye out for those 🫶

🎀 useAnalog (1)

🎀 useInfo (0)

🎀 useDigital (1)

These three turn on the analog clock (useAnalog) and/or the digital clock (useDigital) inside the widget. Heads up: the analog clock will always be displayed above the digital part. No negotiating on that one.

  +----------+
  |    ..    |  \
  |  . \_ .  |   |_ Analog clock
  |  .    .  |   |
  |    ..    |  /
  | 23:59:59 |  --- Digital time
  | 31-12-09 |  --- Digital date
  +----------+

The analog clock displays ticks, hour hand, minutes hand and second hand. The digital part displays two parts, which are configurable — by default these are time and date.

The useInfo option enables a text field between the backdrop of the analog clock and its items. You can use this field to display personal data. Cute, right? 💜

🎀 autoScale (0)

When set to a true value, the widget will try to re-scale itself to automatically fit the containing widget. She's adaptable, she's flexible, she slays.

  $clock->config (autoScale => 1);

🎀 anaScale (100)

The analog clock can be enlarged or reduced using anaScale — the default of 100% is about 72x72 pixels.

⚠️ real talk: when using pack for your geometry management, be sure to pass -expand => 1, -fill => "both" if you plan to resize with anaScale or enable/disable either analog or digital after the clock was displayed. Don't skip this, ngl.

  $clock->config (anaScale => 400);

🎀 ana24hour (0)

The default for the analog clock is the normal 12 hours display, as most clocks are (periodt). This option will show a clock where one round of the hour-hand will cover a full day of 24 hours — noon is at the bottom where the 6 will normally display. Wild, but she pulls it off.

  $clock->config (ana24hour => 1);

🎀 useSecHand (1)

This controls whether the seconds-hand is shown. That's it, that's the option.

  $clock->config (useSecHand => 0);

🎀 countDown (0)

When countDown is set to a true value, the clock will run backwards. This is a slightly experimental feature — it will not count down to a specific point in time, but will simply reverse the rotation, making the analog clock run counterclockwise. It's giving time-travel-adjacent, but only aesthetically 💀

🎀 timerValue (0)

This represents a countdown timer.

When setting timerValue to a number of seconds, the format values Hc, Mc, and Sc will represent the hour, minute and second of this value. When the time reaches 0, all countdown values are reset to 0. Clean, simple, iconic.

🎀 localOffset (0)

The value of this attribute represents the local offset for this clock in seconds. Negative is back in time, positive is in the future. It's giving timezone but make it personal.

  # Wind back clock 4 days, 5 hours, 6 minutes and 7 seconds
  $clock->config (localOffset => -363967);

🎀 handColor ("Green4")

🎀 handColor... I mean 🎀 secsColor ("Green2")

Set the color of the hands of the analog clock. handColor controls the color for both the hour-hand and the minute-hand. secsColor controls the color for the seconds-hand.

  $clock->config (
      handColor => "#7F0000",
      secsColor => "OrangeRed",
      );

🎀 handCenter (0)

If set to a true value, will display a circular extension in the center of the analog clock that extends the hands as if they have a wider area at their turning point — like many station-type clocks (at least in the Netherlands 🇳🇱) have. It's a whole look.

  $clock->config (handCenter => 1);

🎀 tickColor ("Yellow4")

Controls the color of the ticks in the analog clock.

  $clock->config (tickColor => "White");

🎀 tickFreq (1)

🎀 tickDiff (0)

tickFreq controls how many ticks are shown in the analog clock.

Meaningful values for tickFreq are 1, 5 and 15 — showing all ticks, tick every 5 minutes, or the four main ticks only — though any positive integer will do (put a tick on any tickFreq minute). Slay, math.

When setting tickDiff to a true value, the major ticks will use a thicker line than the minor ticks. Highkey a glow-up for your clock face.

  $clock->config (
      tickFreq => 5,
      tickDiff => 1,
      );

🎀 timeZone ("")

Set the timezone for the widget. The format should be the format recognized by the system. If unset, the local timezone is used.

  $clock->config (timeZone => "Europe/Amsterdam");
  $clock->config (timeZone => "MET-1METDST");

🎀 useLocale ("C")

Use this locale for the text shown in month formats mmm and mmmm and in day formats ddd and dddd.

  $clock->config (useLocale => $ENV{LC_TIME} // $ENV{LC_ALL}
                            // $ENV{LANG}    // "nl_NL.utf8");

🙈 heads up bestie: see http://docs.moodle.org/dev/Table_of_locales for a table of locales and the Windows equivalents. Windows might not have a UTF8 version available of the required locale. Not our fault, we just report it 💅

🎀 timeFont ("fixed 6")

Controls the font to be used for the top line in the digital clock. Will accept all fonts that are supported in your version of perl/Tk — this includes both True Type and X11 notation. Versatile queen.

  $clock->config (timeFont => "{Liberation Mono} 11");

🎀 timeColor ("Red4")

Controls the color of the first line (time) of the digital clock.

  $clock->config (timeColor => "#00ff00");

🎀 timeFormat ("HH:MM:SS")

Defines the format of the first line of the digital clock. By default it will display the time in a 24-hour notation (the correct one, obviously).

Legal timeFormat characters are:

H and HH — 24-hour
h and hh — AM/PM hour
M and MM — minutes
S and SS — seconds
Hc — countdown/timer hour
Mc — countdown/timer minutes
Sc — countdown/timer seconds
A — AM/PM indicator
d and dd — day-of-the month
ddd and dddd — short and long weekday
m, mm, mmm and mmmm — month
y and yy — year
w and ww — week-number
any separators ":", "-", "/" or space

  $clock->config (timeFormat => "hh:MM A");

The text shown in the formats ddd, dddd, mmm, and mmmm might be influenced by the setting of useLocale. The fallback is locale C.

🎀 dateFont ("fixed 6")

Controls the font to be used for the bottom line in the digital clock. Will accept all fonts that are supported in your version of perl/Tk — this includes both True Type and X11 notation.

  $clock->config (dateFont => "-misc-fixed-*-normal--15-*-c-iso8859-1");

🎀 dateColor ("Blue4")

Controls the color of the second line (date) of the digital clock.

  $clock->config (dateColor => "Navy");

🎀 dateFormat ("dd-mm-yy")

Defines the format of the second line of the digital clock. By default it will display the date in three groups of two digits representing the day of the month, the month, and the last two digits of the year, separated by dashes. Classic. Timeless. Literally.

  $clock->config (dateFormat => "ww dd-mm");

The supported format is the same as for timeFormat — all those characters up there apply here too 🫶

🎀 infoFont ("fixed 6")

Controls the font to be used for the info label in the analog clock. Will accept all fonts that are supported in your version of perl/Tk — this includes both True Type and X11 notation.

  $clock->config (infoFont => "{DejaVu Sans Mono} 8");

🎀 infoColor ("#cfb53b")

Controls the color of the info label of the analog clock — the default is a shade of Gold. Fancy.

  $clock->config (infoColor => "Yellow");

🎀 infoFormat ("HH:MM:SS")

Defines the format of the label inside the analog clock. By default it will not be displayed. Just as with timeFormat and dateFormat, the content is updated every second if enabled. Yes, every second. She's diligent.

  $clock->config (infoFormat => "BREITLING");

The supported format is the same as for timeFormat.

🎀 digiAlign ("center")

Controls the placement of the text in the digital clock. The only legal values for digiAlign are "left", "center", and "right". Any other value will be interpreted as the default "center" — so if you try to be cute and pass "middle", you get center, no cap.

  $clock->config (digiAlign => "right");

🎀 backDrop ("")

By default the background of the clock is controlled by the -background attribute to the constructor, which may default to the default background used in the perl/Tk script.

The backDrop attribute accepts any valid Tk::Photo object, and it will show (part of) the image as a backdrop of the clock. It's giving photo-wallpaper era and honestly? obsessed 💜

  use Tk;
  use Tk::Clock;
  use Tk::Photo;
  use Tk::PNG;

  my $mainw = MainWindow->new;
  my $backd = $mainw->Photo (
      -file    => "image.png",
      );
  my $clock = $mainw->Clock (
      -relief  => "flat",
      )->pack (-expand => 1, -fill => "both");
  $clock->config (
      backDrop => $backd,
      );
  MainLoop;

💡 also bestie: the new () constructor will also accept options valid for Canvas widgets, like -background and -relief. So go wild.

🏷️ TAGS 🏷️

okay so because the entire clock is part of a Canvas, the items can't be addressed as Subwidgets — periodt. But bestie, you can still alter the presentation afterwards using the tags:

my $clock = $mw->Clock->pack;
$clock->itemconfigure ("date", -fill => "Red");

Currently defined tags are date, hour, info, min, sec, tick, and time. 💅

🐛 BUGS 🐛

If the system load's too high, the clock might skip some seconds — yes, literally, it's giving "buffering" energy. 😭

There's no check if either format will fit in the given space. No cap, no vibe check for overflow. 🙈

📝 TODO 📝

Full support for multi-line date- and time-formats with auto-resize. ✨
Countdown clock API, incl action when done. ⏳
Better docs for the attributes

👀 SEE ALSO 👀

✍️ AUTHOR ✍️

H.Merijn Brand h.m.brand@xs4all.nl

Thanks to Larry Wall for inventing perl. Thanks to Nick Ing-Simmons for providing perlTk. Thanks to Achim Bohnet for introducing me to OO (and converting the basics of my clock.pl to Tk::Clock.pm). Thanks to Sriram Srinivasan for understanding OO though his Panther book. Thanks to all CPAN providers for support of different modules to learn from. Thanks to all who have given me feedback and weird ideas. 🫶💖

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🌈

Signing off from the Clock(3) page: source/version perl v5.42.0, dated 2023-01-07 — iconic, immaculate, no notes. 💜🎀

📦 where this page comes from

opensuse-leap 16.0: perl-Tk-Clock 0.44-bp160.1.11 · Artistic-1.0 OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms