XCUCKOO(1)

NAME
xcuckoo - cuckoo clock for X

SYNOPSIS
xcuckoo [-display display]  [-window name]    [-icon]
        [-command command]  [-mode replace|append|prepend]
        [-separator string] [-update seconds] [-wait seconds]
        [-version]

DESCRIPTION
xcuckoo is an X application, which, like its avian cousin, lays its eggs in another's nest. In its basic form xcuckoo is a clock, displaying the time in the form hh:mm. Alternatively, the display may be the 1-line output of an arbitrary command pipeline. The nest that is used is the title bar of some window. xcuckoo runs until terminated via a SIGHUP, SIGINT, SIGQUIT or SIGTERM signal, when the original contents of the title bar are reinstated, or the host window no longer exists at the time an update is due.

OPTIONS

xcuckoo accepts the following command line options:

-display display
    The display to open.

-window name
    The name of the window whose title bar is to be used.

-icon
    If the window's icon name should be updated too.

-command command
    The command whose output is to be displayed.

-mode replace|append|prepend
    How the output should be related to the current title bar contents.

-separator string
    How the output should be separated from the existing title bar contents if the mode is append or prepend.

-update seconds
    The frequency with which to execute the command and update the title bar.

-wait seconds
    How long to wait before abandoning attempts to locate the target window - useful in startup scripts when the target can't be guaranteed to be available immediatley.

-version
    Print the version number on standard output and exit.

Executing xcuckoo with no options is equivalent to executing
xcuckoo -window 'TWM Icon Manager' -command 'date "+%H:%M"'
        -mode replace -update 60 -wait 0
except that date isn't actually executed - localtime is called.

RESOURCES
xcuckoo recognises top level resources stored in the RESOURCE_MANAGER property of the server's root window that have the same names as the option keywords, except for display, since the display has to be opened in order to read the property, and version. They are, with their defaults:
      window:    TWM Icon Manager
      icon:      false
      command:   date "+%H:%M"
      mode:      replace
      separator: <space>
      update:    60
      wait:      0
Any value other than true for the icon resource is equivalent to false.

EXAMPLES
xcuckoo -window mailbox -command date -mode append -wait 30
xcuckoo -command 'echo `who | wc -l` users' -update 3000

ENVIRONMENT

DISPLAY
    the default host and display number.

BUGS
Just like real cuckoos, xcuckoo may lay its eggs in more than one nest. If the host application is terminated and its window ID reallocated before the next update takes place then xcuckoo will be unaware that anything has happened and proceed to impose on the new owner. Of course, you are at liberty to interpret this behaviour as a feature.

AUTHOR
Jim Wight (j.k.wight@newcastle.ac.uk)
Computing Laboratory, The University, Newcastle upon Tyne, UK, NE1 7RU

ACKNOWLEDGEMENTS
Gerry M Tomlinson <gerry.tomlinson@newcastle.ac.uk> for the initial idea; in fact an early version was called xgmt. Simon Marshall <S.Marshall@uk.ac.hull.seq> and Malcolm Strickland <chuck-strickland@orl.mmc.com> for ideas for enhancements.