DCLOCK(1)

📦
version 2.2.2 · 5 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

🕐 dclock(1) — General Commands Manual 🕐

okay so this is the page for dclock from the General Commands Manual, and bestie, it's a whole vibe — let's get into it 💖

✨ NAME ✨

dclock — digital clock for X 🌸

✨ SYNOPSIS ✨

dclock [-toolkitoption ...] [-option ...]

✨ DESCRIPTION ✨

So like, the dclock program displays the time in digital format only. No hands, no ticking face, just digits, iconic behavior 👑. The time gets updated either on a per-second basis or on a per-minute basis, depending on what you want.

And here's the thing: this program is literally nothing more than a wrapper around the dclock widget, and it's not associated with any particular widget set. That's it. That's the whole program. Simple, chic, slay 💅.

When the clock is running, you can change attributes by just typing — no menus, no mouse required, just keys, we love a keyboard moment:

  • r — Toggles Reverse Video.
  • s — Toggles the seconds display.
  • b — Toggles the bell attribute.
  • j — Toggles the jump/scroll attribute.
  • f — Toggles the fade attribute.
  • d — Toggles the date format.
  • u — Toggles the location of date (top/bottom).
  • m — Toggles the military time format.
  • a — Toggles the alarm clock.
  • t — Toggles the tails attribute.
  • : — Toggles the blinking colon.
  • / — Increases the tilt of the numbers.
  • \ — Decreases the tilt of the numbers.
  • + — Increases the thickness of the numbers.
  • - — Decreases the thickness of the numbers.
  • > — Increases the spacing between numbers.
  • < — Decreases the spacing between numbers.
  • q — quits the program.

mouse girlies, this part is for you 🖱️✨ The third mouse button puts the clock in the mode where the alarm clock can be set. And listen — the alarm must be set in 24-hour format to distinguish between am and pm time. No 12-hour chaos allowed, periodt.

Digits can be changed by selecting the digit with the left or middle mouse button. The Left button advances the time, while the Middle button moves the time backwards. And if you use the left or middle button over the text at the bottom of the clock, that toggles the alarm from actually being set (or, you can just use the a key instead, lowkey easier).

✨ OPTIONS ✨

Dclock accepts all of the standard X Toolkit command line options along with the additional options listed below, and yes, we're going through every single one, no skipping 🫶:

  • -help — This option indicates that a brief summary of the allowed options should be printed on the standard error.
  • -bell, -nobell — This option, if enabled, indicates that the bell will beep once on the half hour and twice on the hour. notification sound but make it punctual 🔔
  • -bellFile filename — This specifies a sound file to use to play the dclock hourly chime. If unspecified, or the string "NULL" is used, the system beep is used instead. The sound file format must be understood by the executable specified by option audioPlay. The "NULL" value is a means to override a system-level setting to disable external sound playing.
  • -miltime, -nomiltime — This option, if enabled, causes the clock to display the time in 24 hour (military) time format.
  • -utc, -noutc — This option causes the clock to display the UTC (GMT) time rather than the default local time. 🌍
  • -tails, -notails — This option places [or removes] "tails" on the digits 6 and 9. (iykyk, it's a whole typography thing)
  • -scroll, -noscroll — When the time changes, the digits scroll from the previous digit to the next digit. The -noscroll option turns the behavior off.
  • -blink, -noblink — The colon separating hours from minutes blinks on and off once per second. With the -noblink option, it remains on permanently.
  • -persist, -nopersist — This option determines whether or not the clock display remains in the reverse video state after the alarm goes off.
  • -fade, -nofade — This option, when enabled, causes the display to fade from one digit to the next instead of jumping or scrolling. If fade is specified, the scroll attribute will be automatically disabled. the way that fade just takes over… obsessed ✨
  • -fadeRate n — The fadeRate attribute takes an integer value which specifies the number of milliseconds to wait between iterations when fading from one digit to the next. A larger value will make the fade slower and more pronounced. The default is 50.
  • -audioPlay filename — Specifies an executable to use to play audio files for the bell and alarm. The default is none, which falls back to using the system bell for both the dclock bell and alarm.
  • -date "format" — The date is printed under the time in the specified font. The string displayed is in the "format" argument. The format corresponds to the system call strftime() (see strftime(3)).
dclock -date "Today is %A"

Useful examples of strftime() formatting:

  • %A — Full weekday name
  • %a — Three-char weekday name (Sun, Mon, Tue...)
  • %B — Full month name
  • %b — Three-char month name (Jan, Feb, Mar...)
  • %d — The date (numerical day number of the month)
  • %Y — Full year (4 digits)
  • %y — 2-digit year number
  • -dateup — By default, the date string is at the bottom of the display. This option starts it at the top, instead. flip it, reverse it, top-tier placement 🎀
  • -alarm, -noalarm — The alarm is turned on or off. Alarm rings bell and toggles reverse video.
  • -alarmTime HH:MM — If alarm is set, it goes off at time specified in 24-hour format. ⏰
  • -alarmFile filename — This specifies a sound file to use to play the dclock alarm. If unspecified, or the string "NULL" is used, the system beep is used instead. The sound file format must be understood by the executable specified by option audioPlay. The "NULL" string is a means to override a system-level setting to disable external sound playing.
  • -seconds — This option will update the clock every second and display the time including the seconds.
  • -slope value — Sets the angle of the digits according to the (floating-point) slope value value.
  • -thickness width_factor — Sets the segment thickness as a (floating-point) ratio to digit width.
  • -spacing space_factor — Sets the digit spacing as a (floating-point) ratio to digit width.
  • -smallsize space_factor — Sets the seconds digit size as a (floating-point) ratio to the digit size of the minutes and hours digits.
  • -second_gap space_factor — Sets the spacing of the seconds digits from the other digits as a (floating-point) ratio to digit width.
  • -bg color — This option specifies the color to use for the background of the window. The default is darkslategray.
  • -bd color — This option specifies the color to use for the border of the window. The default is black.
  • -bw number — This option specifies the width in pixels of the border surrounding the window.
  • -fg color — This option specifies the color to use for displaying text and digit segments. The default is chartreuse. 💚
  • -led_off color — This option specifies the color to use for displaying digit segments when turned off. The default is darkgreen.
  • -fn font — This option specifies the font to be used for displaying normal text. The default is Fixed.
  • -geometry geometry — This option specifies the preferred size and position of the clock window.
  • -display host:display — This option specifies the X server to contact.
  • -xrm resourcestring — This option specifies a resource string to be used. This is especially useful for setting resources that do not have separate command line options. secret menu energy 🌈

💖 X DEFAULTS 💖

okay so bestie, dclock gets the whole X resource system — it speaks every core resource name and class, and then it's got its own lil extended menu on top. here's the tea:

  • geometry (class Geometry) — sets the width and height, and if you wanna get fancy, the preferred position of the clock too. ✨
  • foreground (class Foreground) — the color for the digits. and if you set the class instead? it recolors literally everything that would normally be drawn in the foreground color. default is `chartreuse` 💚 (iconic choice, no notes).
  • background (class Background) — the background color, and by default it's `DarkSlateGray`.
  • led_off (class Foreground) — the color of the digit segments when they're "off". you can set it to match the background, or you can set it to something just a teensy bit different from the background — matching the segment colors — so you get just a lil hint of color peeking through. default `DarkGreen` plays so nicely with the default segment color of `chartreuse`. match made in heaven fr fr 🫶
  • bell (class Boolean) — whether a bell gets rung on the hour and the half hour. 🔔
  • font (class Font) — the font used for the date.
  • militaryTime (class Boolean) — whether to use military (24hr) time format.
  • utcTime (class Boolean) — whether to use UTC (GMT) time instead of local time.
  • reverseVideo (class ReverseVideo) — flips the foreground and background colors. 💅
  • scroll (class Boolean) — whether the digits should scroll or not.
  • fade (class Boolean) — whether the digits should fade or not.
  • fadeRate (class Time) — how many milliseconds of delay sit between each iteration of fading.
  • seconds (class Boolean) — whether the seconds get displayed or not.
  • tails (class Boolean) — whether tails get put on the digits 6 and 9. 🎀
  • date (class String) — the date format to use. this format corresponds to the system call strftime() (peep strftime(3)).
  • dateUp (class Boolean) — whether the date shows up at the top or at the bottom.
  • blink (class Boolean) — whether the colon separating hours from minutes blinks on and off once per second, or just stays on permanently. ✨
  • alarm (class Boolean) — whether the alarm should go off at the specified time (alarmTime).
  • alarmTime (class String) — the time the alarm goes off, if alarm is set. ⏰
  • alarmPersist (class Boolean) — whether the alarm stays in reverse video after it goes off, or goes back to normal video.
  • angle (class Float) — defines the slope of the digits (default 6).
  • smallRatio (class Float) — defines the size of the seconds digits compared to the minutes digits (default 2/3).
  • secondGap (class Float) — defines how much space sits between the minutes digits and the seconds digits (default 0.3).
  • widthFactor (class Float) — determines the width of segments as a ratio to digit width (default 0.13).
  • spaceFactor (class Float) — determines the spacing between digits as a ratio to digit width (default 0.09).
  • bellFile (class String) — an audio file to play for the hourly bell (no default). 🔔
  • alarmFile (class String) — an audio file to play for the alarm (no default). ⏰
  • audioPlay (class String) — an executable used to play the bell and alarm audio files, if they're specified. otherwise, the system bell is used. default is `/usr/bin/play`.

🌈 ENVIRONMENT 🌈

  • DISPLAY — used to get the default host and display number. 🖥️
  • XENVIRONMENT — used to get the name of a resource file that overrides the global resources stored in the RESOURCE_MANAGER property.

👀 SEE ALSO 👀

xrdb(1), strftime(3), X(7).

💀 BUGS 💀

Dclock believes the system clock. (trusting, bestie. too trusting.)
Scrolling from 9 to 10 O'Clock seems weird, but chances are you won't notice it.
Scrolling can take so long that dclock may lag behind system time by a fraction of a second and eventually skip a second to catch up. In modern times, it should be dealing with this by tracking seconds with a separate thread. 😭

Copyright (c) 1988, Dan Heller. Revisions copyright (c) 1993 and 1999, Tim Edwards.

💜 AUTHOR 💜

  • Original dclock by Dan Heller (1988) <argv@sun.com> or <dheller@cory.berkeley.edu>
  • Fade & tails by Steve Reinhardt, <steven@fts.webo.dg.com>
  • Derived geometry by Tim Edwards (1993) <tim@stravinsky.jhuapl.edu>
  • Antialiasing, color fades, and audio play by Tim Edwards (1999) <tim@stravinsky.jhuapl.edu>
  • Manual page in POD format by Ricardo Mones (2023) <mones@debian.org>

aaaand that's the whole page bestie!! 🦋 this one's from X Version 11, dated 1 March 1988, and it's DCLOCK(1) — the manual page that's been serving clock looks since before either of us existed, periodt. go forth and make your desktop clock gorgeous 💅✨

📦 where this page comes from