TELLTALE is a Windows program that places a (optionally flashing) box on the screen. It is created as a "top most" window. The idea is to be able to see, easily, whether a process has been successful or not.
For example, let's say that you're working on a project where the "make" system has been configured such that it's not easy to see if the build procedure has failed or not. You could place invocations of TELLTALE at strategic points throughout the build batch or make file so that it creates, say, a green box for "all OK" and a red box for "something's wrong"..
NOTE: If a parameter must contain one or more spaces, enclose the whole parameter string in double quotes. See example (19) for such a parameter.
Having put TELLTALE.EXE somewhere on your PATH, open a DOS-box and type this:
(01) telltale -
This should make a red flashing box appear in the top, right-hand corner of the screen. (Note that it defaults to creating a non-active tell-tale box. That is, control returns to the DOS-box after the tell-tale is created.)
In order to get rid of tell-tale box, you can do one of several things. The first method is to merely replace it with something else, such an "all OK" tell-tale box:
(02) telltale +
Alternatively, you can zap all instances of TELLTALE that are running with the following command. Note that this command will destroy all its clones and exit without displaying a box:
(03) telltale -k
If you want multiple tell-tale boxes, use something like this:
(04) telltale -
telltale -g,200 =
This will create an additional tell-tale box slightly lower than the previous ones. The -G option makes TELLTALE alter the gap between the edge of the screen and the box it creates. In this instance, the "X" gap was left at the default of "zero pixels". The "Y" gap was made big enough that it didn't cover the previously made box. Hence, you should now have a red, flashing box at the top, right-hand corner of the screen and, below it, a solid, orange box.
One can alter the position and size of the boxes:
(05) telltale -p200,400 -s300,50
TELLTALE doesn't remove a previous box unless the new box is exactly the same size and in the same place as one or more previous boxes, so this will have left the previous boxes and placed an additional box 300 by 50 pixels at position (200,400) on the screen. Remove all the boxes using another:
(06) telltale -k
Note that in addition to removing tell-tale boxes by making new ones or using the -K option, you can also dismiss them by type any key when the box has the focus or by clicking the mouse over one of them.
If you really must, you can maximise a tell-tale box, so you can see it right across the car-park! (When you've done the following, a single key-press should dismiss the box.)
(07) telltale -m
If you only ever want to display a box and dismiss it straight away before doing anything else, then make the created box active by using the -A option:
(08) telltale -a
You should be able to dismiss the box with a single key-press.
The speed at which the boxes flash is variable. Specify the period that you want each colour to remain in milliseconds:
(09) telltale -i50 -
When you set a period, it will apply to all following colours. Hence, this would not have the desired effect:
(10) telltale - -i50
The boxes can be flashing or solid. Solid boxes are specified by merely supplying a single colour. Hence, this will produce a simple, solid yellow box:
(11) telltale -cyellow
For flashing boxes, you need two colours. Let's say we want a box, flashing yellow and blue, that has a total period of one second. Further more, let's assume that we want the blue period to be twice as long as the yellow period. We'd use this:
(12) telltale -i333 -cyellow -i666 -cblue
Note that only a few colour names are defined. For the others, you'll have to use the Windows hexadecimal 0xBBGGRR (blue-green-red) format. For example, the previous command could also have been issued like this:
(13) telltale -i333 -c0x00ffff -i666 -c0xff0000
Choosing a black as one of your colours will have the effect of producing a flashing tell-tale box. However, TELLTALE has one more trick up its sleeve - choosing the special colour "HIDE" will, when it's time to display the box in that colour, hide the window completely. To see the difference between choosing BLACK and choosing HIDE, try these two command-lines:
(14) telltale -cred -cblack
telltale -cred -chide
Let's have a box in each corner of the screen:
(15) telltale -
telltale - -tl
telltale - -bl
telltale - -br
You may want to have a more-or-less "permanent" set of tell-tales on the screen but, at the same time, be able to remove all "transient" tell-tales by firing off a command from an icon, or whatever. Well, you can assign a "group number" using the -W parameter.
All tell-tales belong to a group. The default group is zero. When TELLTALE kills off siblings, it will only kill siblings in the same group.
Hence, after executing the following commands one after the other, both tell-tales will still be on the screen, though they will be placed one on top of the other:
(16) telltale - -u1
telltale + -u2
In order to remove both windows, one must invoke two lots of the -K option citing each group in turn:
(17) telltale -u1 -k
telltale -u2 -k
TELLTALE attempts to "hide" its taskbar button and appearance on the ALT-TAB list. The old default Windows application behaviour of having the taskbar button visible and of being selectable via the ALT-TAB application list can be invoked via the -V option:
(18) telltale
telltale -v
telltale
telltale -k
You can make TELLTALE place descriptive text in the middle of the tell-tale. Use the -D command to do this:
(19) telltale "-dBuild Error!"
The colour of the text can be specified on a per-colour basis. For each additional colour, adding the optional text colour will specify the background / text colour pair used for each box's "decor scheme". For example, perhaps we want to have red text on a black box alternating with white text on a blue box:
(20) telltale "-dBuild Error!" -cblack,red -cblue,white
You can specifiy the font used for the error message by using the -F option. This also allows you to specify the font size. Note that, at present, no fancy formatting is done - it's pretty crude...
For a tell-tale that makes an impact, try this:
(21) telltale -m -f150,times -dError!
Instead of invoking an external program, TELLTALE has in-built pinging facilities. When displaying the results of a ping, TELLTALE uses colour pairs. The default colour set is to display green if the host replies quickly, amber if it replies in a reasonable period of time and red if it times-out.
Let's assume that you want to ping www.glod.net every second:
(22) telltale -w1000 -nwww.glod.net
If you wanted to have the pinging process timeout after a spcific number of milli-seconds, you could do this (which would make the ping time-out after 200 milli-seconds):
(23) telltale -w1000 -nwww.glod.net,200
Note that if you are pinging a host, you can use the "C" PRINTF() syntax to display the number of milli-seconds that the host took to reply. If the host doesn't reply, the number of seconds is displayed as "-1".
For example, we could modify our previous example thusly:
(24) telltale -w1000 -nwww.glod.net,200 -s200 "-dwww.glod.net: %dms"
The -S200 was added to make the tell-tale box a little wider to accomodate the length of the text message.
Note that, in that last example, the "%d" that indicates the place where you want the milli-second time to appear must be in lower-case.
One final ping example. Let's try pinging the time server at MIT:
(25) telltale -w500 -nbitsy.mit.edu -m -f200 -d%dms
You can arrange for tell-tales to be arranged in an "array" across the screen. The way to do this is to use the -O parameter. First, let's see an example where the user specifies the position. We assume that the user wants four tell-tales arranged from the bottom, right-hand corner of the screen and to have them "piled up" on top of one another:
(26) telltale -br -ou0
telltale -br -ou1
telltale -br -ou2
telltale -br -ou3
As usual, if you run TELLTALE again, it will over write a tell-tale that's already where the new box has to go:
(27) telltale -br -ou1 +
telltale -k
There is one other way of using the "offset" array feature - you can get TELLTALE itself to work our where the next tell-tale should go. If it comes across an un-used "slot", it puts the new box there. If not, the new box goes on the "end" of the array of tell-tales:
(28) telltale -br -ou
telltale -br -ou
telltale -br -ou
telltale -br -ou
Having placed the above four tell-tales, try deleting one of the boxes and running an instance of the above command again but, perhaps, having selected a different colour:
(29) telltale -br -ou +
By the way, the auto-placement of tell-tales in an array is very useful when, for example, the position of a tell-tale is not important. For example, consider this as the contents of an MSdos batch file:
(30) @telltale -s200,50 -tr -od%2 -n%1 -f20,times "-d%1: %%dms"
Then, one could issue commands like this to create an array of tell-tales that each indicate the status of a different host system:
(31) tt Hex
tt Scraps
tt Ratty
Moreover, if we wanted to replace the entry for RATTY with one for OLDRATTY, we could do this:
(32) tt OldRatty 2
One can specify "reponse" files on a TELLTALE command-line. These are indicated by placing a file name between a pair of commercial "at" signs. (You can "escape" this behaviour by using two at-signs together.)
For example, let's assume that we want to pick a host name from a directory containing files named after hosts. When we've picked our file(s), we want to start TELLTALE with either just the host name of the host name and the reply time as the text of a tell-tale box.
We could do it like this: we make a TEST directory that contains files that have names consist of host names with an extension of a single under-score character. For example, a directory listing might look like this:
(33) Volume in drive C is HEX
Volume Serial Number is 2477-A6E6
Directory of C:\Work\C\MSVC\TellTale\Test
. <DIR> 29/04/01 10:30 .
.. <DIR> 29/04/01 10:30 ..
HOSTS LNK 395 10/05/01 20:26 Hosts.lnk
HOSTS PNR 223 10/05/01 20:26 hosts.pnr
HOSTS TT 125 10/05/01 19:58 hosts.tt
HEX _ 0 28/04/01 15:17 hex._
NINO _ 0 28/04/01 15:17 nino._
OLDRATTY _ 0 28/04/01 15:17 oldratty._
OLLIE _ 0 28/04/01 15:17 ollie._
RATTY _ 0 28/04/01 15:17 ratty._
SCRAPS _ 0 28/04/01 15:17 scraps._
BITSYM~1 _ 0 28/04/01 15:17 bitsy.mit.edu._
WWWGLO~1 _ 0 28/04/01 15:17 www.glod.net._
187203~1 _ 0 28/04/01 15:17 18.72.0.3._
12 file(s) 743 bytes
2 dir(s) 15,400,960 bytes free
Thus, if I want to ping the computer called "ratty", I'd use PNR to select the "RATTY._" file.
The HOSTS.LNK file would have a command-line like this:
(34) pnr.exe @hosts@
It would have a "start in" entry of the above directory. Viz:
(35) c:\work\c\msvc\telltale\test
The "@HOSTS@" is a reference to the PNR response file, HOSTS.PNR, which contains this text:
(36) -dc -dw1000 -du -cn "-dfHost Node!*._"
"-mnTellTale Host Only"
"-mcstart /MIN telltale '-d%4' -n%4,1000 @@hosts@@"
"-mnTellTale Host Plus MilliSeconds"
"-mcstart /MIN telltale '-d%4 %%dms' -n%4,1000 @@hosts@@"
Notice that since TELLTALE also handles response files, the majority of the TELLTALE parameters are contained in the HOSTS.TT file that are included by use of "@@HOSTS@@". (Note the escaping of the response file characters because we want TELLTALE to see this inclusion - we don't want PNR to expand it.)
Finally, the HOSTS.TT file contains this:
(37) -cgreen,black
-cgreen,black
-camber,black
-camber,black
-cred,white
-cblack,white
-u1
-s160,28
-br
-ol
-w2000
This file holds the parameters that are common to both command-lines of the PNR-generated menu.
One can split the text presented to a -D option over more than one line by using the "C" notation of a back-slash. For example:
(38) telltale -daaa\nbbb\nccc
As with the "%d" sequence, above, the "n" following the back-slash must be in lower-case. Other escaped characters are as follows:
(39) "\a" 0x07
"\b" 0x08
"\e" 0x1B
"\f" 0x0C
"\n" 0x0A
"\r" 0x0D
"\t" 0x09
"\v" 0x0B
"\xhh" 0xhh
Note that the Windows DRAWTEXT() function treats "\n", "\r" and "\r\n" the same - viz, it breaks the text and will display it over two lines.