#define CODE_END;=========================================================================== #define EG_COLOUR (12) #define EG_SPACES (19) #define EG_BACK_SLASH (38) ;=========================================================================== #switch !MAKECLEAN ;=========================================================================== #file INDEXhtml tt.htm #file TUTORhtml tttut.htm #file VERSIONShtml ttver.htm #file FAQhtml ttfaq.htm #file REFhtml ttref.htm #source VersionSrc Version.ini #includ VersionSrc #define TITLE TELLTALE %PVERSION% ;=========================================================================== #margin 0 ; Don't require use of switch "expressions". #empty 1 ; Want white space passed through so the HTML is readable. ;=========================================================================== #send *html ; #close * ;=========================================================================== #say Generating index HTML file. #send INDEXhtml
Welcome to TELLTALE, a ChAoS Utility. This program allows the user to display a small indicator (that is, a "tale-tell") that can be of a fixed or changing colour depending upon the command-line options selected. It can be used for a broad range of tasks and, in particular, has in-built PINGing facilities.
The main benefit of using TELLTALE is that it can be used to monitor, for example, the results of a program "build" and allows the success or failure of the process to be easily and plainly apparent when, perhaps, the output of the build process produces so much "clutter" that the results may not be otherwise easily discernable.
TELLTALE is a command-line utility and operates by interpreting the options provided upon its command-line.
<%HEADB%> RequirementsIn order to work, TELLTALE merely requires that you have the executable file and that you are running a 32-bit Windows operating system or compatible.
<%HEADB%> Package ContentsYou should have the following:
| telltale .exe | The TELLTALE executable file. |
|---|---|
| %VERSIONSHTML% | Change history of the TELLTALE program. |
| %TUTORHTML% | TELLTALE's Tutorial. |
| %INDEXHTML% | This introduction to TELLTALE. |
| %FAQHTML% | A file of Frequently Asked Questions. |
| %REFHTML% | A TELLTALE Reference Manual. |
To actually run TELLTALE, only the executable is required.
If you are a first-time user of TELLTALE, We suggest that you read the tutorial.
<%HEADB%> LicenceTELLTALE is a public domain program. You are free to re-distribute TELLTALE to third parties if:
"The authors disclaim all warranties as to this software, whether express or implied, including without limitation any implied warranties of merchantability, fitness for a particular purpose, functionality or data integrity or protection."<%HEADB%> Copyright
TELLTALE was written by Mark ("Captain ChAoS") Davis with a small contribution from Stephen ("Harry") Coul. By virtue of the fact that ChAoS had a hand in writing this program:
We're not sure that the terms "public domain" and "copyright" aren't mutually exclusive. Even so, this software is:
If you have any bug reports or suggestions, you can contact the authors at the TELLTALE email address.
If you like TELLTALE, perhaps you'll like the rest of the ChAoS Utilities - please visit the web site. #close * ;=========================================================================== #define QLowr My %%%%D And \N Special Text Sequences Don't Work. Why Not? #say Generating FAQ HTML file. #send FAQhtml
TELLTALE is written in ANSI "C" and, as a convenient programming short-cut, uses the the "C" library text facilities in order to do some of the processing of the users' command-line options. This means that the user has to conform to some of the library's requirements. The major requirement is that all "escape" sequences must be in lower-case. So for example, while "%%d" and "\n" are acceptable, "%%D" and "\N" are not. #close * ;=========================================================================== #say Generating Change Log HTML file. #send VERSIONShtml
| 1.4.068 | Improve the mouse handling. The program now only commits suicide when a mouse button is released and it has already seen the button depressed. (It ain't perfect but it's better than what I had before. Previously, TELLTALE bailed out upon button press but the release of the button was sometimes "seen" by whatever application happened to be underneath the late TELLTALE window.) |
|---|---|
| 1.4.067 | The -D text can now be formatted over more than one line. Use the "C" notation of "\r" or "\n" (or both) to force the text to break to a new line. See example %EG_BACK_SLASH% in the tutorial. |
| 1.4.042 | Corrected a problem whereby created brushes were not deleted after use. This appeared to run fine under Win95 but caused interesting flickering screen affects if TELLTALE was run for a long enough period under WinNT. |
| 1.4.041 | Corrected the calls to KILLTIMER(). |
| 1.4.040 | Fixed bug whereby "stacking" via a -O option worked if the "base" tell-tale was against one edge of the screen but not if the base box was in the middle of the screen. |
| 1.4.036 | Added the self-positioning of tell-tales when an offset direction was supplied but no offset number. In this instance, TELLTALE will place the new box in the first un-used "slot". |
| 1.4.010 | Added Harry's Wonderful PING. See the list of examples in the tutorial for information on how to invoke it. TELLTALE now has it's very own icon! (Though not, it has to be said, a very good one...) |
| 1.2.114 | Added capability to display text in the tell-tales and also to specify the colour of that text. |
| 1.2.103 | Added the removal from the taskbar by default. The old behaviour (of having a visible taskbar button) can be invoked by using the -V option. |
| 1.2.098 | Added the "group numbering" facility. This is an integer, specified using the -W parameter. This integer is used to fabricate the program's class name. As a result, the killing of siblings will now only take place on siblings that have the same group number. |
| 1.2.068 | Fixed a little bug whereby siblings were inhumed if they were in the same position as the intended new-born window but the "show state" (that is, whether they were maximised or not) was different. Thus, if you made a default tell-tale box and then made a second identical box except that the latter had the -M option applied so that it was maximised, the latter would kill off the former. |
| 1.2.000 | One can now specify up to twenty colours each having their own period. Specify the period for a colour before you specify the colour itself. (See example %EG_COLOUR% in the tutorial.) Also, TELLTALE now only deletes a previous tell-tale if the new box exactly matches the size and position of a previous box. Hence, it's now much easier to have several tell-tales showing the status of different items. To update one of them, merely issue another TELLTALE command using the same size and position parameters. |
| 1.1.000 | Added the "HIDE" colour that flashes the boxes by making them invisible. (Note that it can be somewhat more difficult to remove these since one can neither type a key into, nor click on, a window that isn't there.) |
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 %EG_SPACES% for such a parameter.
Having put TELLTALE.EXE somewhere on your PATH, open a DOS-box and type this:
%CODE_START% (01) telltale - %CODE_END%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:
%CODE_START% (02) telltale + %CODE_END%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:
%CODE_START% (03) telltale -k %CODE_END%If you want multiple tell-tale boxes, use something like this:
%CODE_START% (04) telltale - telltale -g,200 = %CODE_END%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:
%CODE_START% (05) telltale -p200,400 -s300,50 %CODE_END%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:
%CODE_START% (06) telltale -k %CODE_END%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.)
%CODE_START% (07) telltale -m %CODE_END%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:
%CODE_START% (08) telltale -a %CODE_END%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:
%CODE_START% (09) telltale -i50 - %CODE_END%When you set a period, it will apply to all following colours. Hence, this would not have the desired effect:
%CODE_START% (10) telltale - -i50 %CODE_END%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:
%CODE_START% (11) telltale -cyellow %CODE_END%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:
%CODE_START% (12) telltale -i333 -cyellow -i666 -cblue %CODE_END%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:
%CODE_START% (13) telltale -i333 -c0x00ffff -i666 -c0xff0000 %CODE_END%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:
%CODE_START% (14) telltale -cred -cblack telltale -cred -chide %CODE_END%Let's have a box in each corner of the screen:
%CODE_START% (15) telltale - telltale - -tl telltale - -bl telltale - -br %CODE_END%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:
%CODE_START% (16) telltale - -u1 telltale + -u2 %CODE_END%In order to remove both windows, one must invoke two lots of the -K option citing each group in turn:
%CODE_START% (17) telltale -u1 -k telltale -u2 -k %CODE_END%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:
%CODE_START% (18) telltale telltale -v telltale telltale -k %CODE_END%You can make TELLTALE place descriptive text in the middle of the tell-tale. Use the -D command to do this:
%CODE_START% (19) telltale "-dBuild Error!" %CODE_END%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:
%CODE_START% (20) telltale "-dBuild Error!" -cblack,red -cblue,white %CODE_END%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:
%CODE_START% (21) telltale -m -f150,times -dError! %CODE_END%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:
%CODE_START% (22) telltale -w1000 -nwww.glod.net %CODE_END%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):
%CODE_START% (23) telltale -w1000 -nwww.glod.net,200 %CODE_END%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:
%CODE_START% (24) telltale -w1000 -nwww.glod.net,200 -s200 "-dwww.glod.net: %%dms" %CODE_END%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:
%CODE_START% (25) telltale -w500 -nbitsy.mit.edu -m -f200 -d%%dms %CODE_END%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:
%CODE_START% (26) telltale -br -ou0 telltale -br -ou1 telltale -br -ou2 telltale -br -ou3 %CODE_END%As usual, if you run TELLTALE again, it will over write a tell-tale that's already where the new box has to go:
%CODE_START% (27) telltale -br -ou1 + telltale -k %CODE_END%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:
%CODE_START% (28) telltale -br -ou telltale -br -ou telltale -br -ou telltale -br -ou %CODE_END%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:
%CODE_START% (29) telltale -br -ou + %CODE_END%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:
%CODE_START% (30) @telltale -s200,50 -tr -od%%2 -n%%1 -f20,times "-d%%1: %%%%dms" %CODE_END%Then, one could issue commands like this to create an array of tell-tales that each indicate the status of a different host system:
%CODE_START% (31) tt Hex tt Scraps tt Ratty %CODE_END%Moreover, if we wanted to replace the entry for RATTY with one for OLDRATTY, we could do this:
%CODE_START% (32) tt OldRatty 2 %CODE_END%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:
%CODE_START% (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 %CODE_END%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:
%CODE_START% (34) pnr.exe @hosts@ %CODE_END%It would have a "start in" entry of the above directory. Viz:
%CODE_START% (35) c:\work\c\msvc\telltale\test %CODE_END%The "@HOSTS@" is a reference to the PNR response file, HOSTS.PNR, which contains this text:
%CODE_START% (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@@" %CODE_END%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:
%CODE_START% (37) -cgreen,black -cgreen,black -camber,black -camber,black -cred,white -cblack,white -u1 -s160,28 -br -ol -w2000 %CODE_END%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:
%CODE_START% (38) telltale -daaa\nbbb\nccc %CODE_END%As with the "%%d" sequence, above, the "n" following the back-slash must be in lower-case. Other escaped characters are as follows:
%CODE_START% (39) "\a" 0x07 "\b" 0x08 "\e" 0x1B "\f" 0x0C "\n" 0x0A "\r" 0x0D "\t" 0x09 "\v" 0x0B "\xhh" 0xhh %CODE_END%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.
;----------------------------------------------------------------------------- ; #close * ;=========================================================================== #say Generating Reference HTML file. #send REFhtml ;----------------------------------------------------------------------------- ;The program's command-line grammar is as follows:
TELLTALE [%<%option%>%][%<%option%>%]...[%<%option%>%];----------------------------------------------------------------------------- <%HEADB%> Options
An %<%option%>% can be:
| - | Short form to set "error" (red) parameters. |
|---|---|
| = | Short form to set "mediocre" (amber) parameters. |
| + | Short form to set "good" (green) parameters. |
| -a | Create an active window. |
| -k | Kill all siblings and exit. (No tell-tale is displayed.) |
| -m | Create a maximised window. |
| -v | Make taskbar button visible. (Also affects use of ALT-TAB.) |
| -i%<%number%>% | Set flash period in milliseconds. |
| -w%<%number%>% | Set inter-program (or PING) period in milliseconds. |
| -u%<%number%>% | Set group number. |
| -d%<%text%>% | Set descriptive centred text that appears in the tell-tale. |
| -f%<%number%>%[,%<%name%>%] | Set the description text font size and / or font name. |
| -c%<%colour%>%[,%<%colour%>%] | Specify an additional box and / or text colour. |
| -g%<%xypair%>% | Set x and/or y gap from edge of screen. |
| -p%<%xypair%>% | Set x and/or y window position. |
| -s%<%xypair%>% | Set x and/or y window size. |
| -o%<%dir%>%[%<%number%>%] | Place a tell-tale into the %<%number%>%th position of an array of tell-tales with new items being added in the %<%dir%>% direction. |
| -bl | Put window in bottom, left-hand corner of the screen. |
| -br | Put window in bottom, right-hand corner of the screen. |
| -tl | Put window in top, left-hand corner of the screen. |
| -tr | Put window in top, right-hand corner of the screen. |
| -x%<%command%>% | Execute and use error level to select colour pair. |
| -n%<%host%>%[,%<%number%>%] | PING target host name or number and milli-second timeout. |
The %<%colour%>% grammar is:
| %<%name%>% | AMBER, BLACK, BLUE, CYAN, GRAY, GREEN, HIDE, MAGENTA, RED, WHITE, YELLOW |
|---|---|
| %<%number%>% | A colour number in Windows "BGR" format. For example, 0x0000FF for red, 0x00FF00 for green, 0xFF0000 for blue and so on. |
A direction, %<%dir%>%, can be one of:
| u | Up |
|---|---|
| d | Down |
| l | Left |
| r | Right |
An %<%xypair%>% is one of:
[%<%number%>%],[%<%number%>%] | |
|---|---|
[%<%number%>%];;[%<%number%>%] | |
[%<%number%>%]:[%<%number%>%] |
A %<%number%>% can be one of:
0x%<%hexnumber%>% | |
|---|---|
%<%hexnumber%>%h | |
%<%decimalnumber%>% |
A %<%command%>% is merely a program command-line that returns a sensible error level.
;----------------------------------------------------------------------------- ; #close * ;=========================================================================== #if MAKECLEAN #say #say Making clean - all generated HTML files will be deleted. #delete * #say Making clean - complete. #endif