OSD plugin for Take Command / TCC / TCC/LE

Version 1.0.7     2021-11-23

Charles Dye

Purpose:

This plugin implements an enhanced version of the OSD command. It’s intended to be backwards-compatible with the built-in OSD, while providing nicer syntax and many more features. Of course, using any of the new features or syntax will break TCC compatibility.

Installation:

To use this plugin, copy OSD.dll to some known location on your hard drive. (If you are using the 32-bit version of Take Command, take OSD-x86.dll instead of OSD.dll.) Load it with a PLUGIN /L command, for example:

plugin /l c:\bin\tcmd\test\osd.dll

If you copy this file to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically when TCC starts.

Plugin Features:

New commands: OSD, OSDIMG, PCTBAR

New variables: _OSD, _OSDVER

New function: @OSD

Syntax Note:

The syntax definitions in the following text use these conventions for clarity:

BOLD CODEindicates text which must be typed exactly as shown.
CODEindicates optional text, which may be typed as shown or omitted.
Bold italicnames a required argument; a value must be supplied.
Regular italicnames an optional argument.
ellipsis…after an argument means that more than one may be given.

New Commands:

OSD — Display text on the screen.

Syntax:
OSD /C=n /FONT=n /ID=n /N /POS=y,x /RGB=r,g,b /TIME=n /V text

Compatible features:
/Cclose any OSD windows with ID #0
/C=nclose any OSD windows with ID #n
/FONT=ntext height in pixels; the default is 18
/ID=nspecify an ID number; defaults to 0
/Ndon’t wait for the OSD window to time out
/POS=y,xset OSD window position; defaults to 0,0
/RGB=r,g,btext color; the default is 0,255,0 (bright green)
/TIME=nin seconds; the default is 10
/Vvertical text
/LEFT, /RIGHT, /HCENTERoverride any /POS= x value
/TOP, /BOTTOM, /VCENTERoverride any /POS= y value
textany leading or trailing whitespace will be stripped
New features — incompatible with TCC:
/FONT=n/H=nmay be abbreviated
/TIME=n/T=nmay be abbreviated
/LEFT/Lmay be abbreviated
/RIGHT/Rmay be abbreviated
/TOP/Tmay be abbreviated
/BOTTOM/Bmay be abbreviated
/HCENTER/HCmay be abbreviated
/VCENTER/VCmay be abbreviated
/CENTER/CTRcombines /HCENTER and /VCENTER
/MONITOR=n/M=nmonitor number
/CAclose all OSD windows, regardless of ID
/FADENOWfade out and close any OSD windows with ID #0
/FADENOW=nfade out and close any OSD windows with ID #n
/CJcenter-justify text; useful with multiline text and @files
/RJright-justify text; useful with multiline text and @files
/LJleft-justify text; useful with multiline text and @files (default)
/UCuppercase text
/FACE=name/F=nametypeface name; quote it if it contains spaces
/ITALIC/Iitalic typeface
/UNDERLINE/Uunderline text
/BOLD=n/B=ntext weight, 0 - 9; 0 don’t care, 1 thin, 4 normal, 7 bold, 9 heavy
/MS=nspecify time in milliseconds rather than seconds
/COLOR=n/K=nspecify color as a TCC color number, 0 - 15
/HUE=namespecify color as a W3C color name
/SHADOW/DSadd a drop shadow
/ALPHA=n/A=ntransparency; n is 48 (ghostly) to 255 (opaque)
/FADE/Ffade the window out when the time expires
/BLINKflash the text obnoxiously
/UProtate the window 90° left
/DOWNrotate the window 90° right
/Qwith /C, suppress window-not-found error messages
/Xexpand escape sequences in the text string
/MAXLINES=nmaximum lines to read from an @file, 1 to 64; default 5; 0 disables @files
/CP=nspecify the code page for an @file
/SAVE=nsave a style for use in later OSD calls
/STYLE=n/nrecall a style saved by /SAVE
 
•  text may instead be an @file; up to five lines (or per /MAXLINES) will be read.
•  Option-argument separator: You can use a colon instead of an equals sign.
•  Integer arguments: You can give these in hexadecimal with a leading 0x.
•  Window ID: May be 0 - 1024 (the internal command’s range is 0 - 9)
•  /C=n or /CA may be combined with text.
•  Exit code: OSD returns 3 if it was interrupted by Ctrl-Break or Ctrl-C.

Using any of the options listed under “New features” will break compatibility with TCC.


Leading and trailing spaces will be stripped from the text. If you really want leading (or trailing) spaces, you can protect them with a leading (or trailing) %@CHAR[0x200B]. This is the Unicode “Zero Width Space”, which iswspace() doesn’t recognize as whitespace. (This trick also works in TCC’s native OSD.)


The /MONITOR=n option allows you to specify the monitor used by the /LEFT, /RIGHT, /HCENTER, /TOP, /BOTTOM, /VCENTER, and /CENTER options. (It does not affect absolute screen coordinates specified via /POS=y,x.) n is 0 to the number of monitors. If n is 0 or greater than the number of monitors present, the default monitor (the one with the taskbar) will be used instead. You can also type /MONITOR=-1 to use the entire virtual desktop area spanning all monitors. Obviously this option is only useful in a multiple-monitor system.


The /FACE=name option allows you to specify the typeface used for the text. If you don’t use this option, the default is Verdana. If the typeface name contains spaces, double-quote it. Instead of a typeface name, you can give a family name in parentheses, and OSD will use the first TrueType font of that type that it finds. These are the supported families; note that the parentheses are required:

familydescriptionexample
(Roman)a serif typefaceTimes New Roman
(Swiss)a sans-serif typefaceArial
(Modern)an unstressed typeface; most are fixed-pitchCourier New
(Script)a handwriting typefaceComic Sans MS
(Decorative)decorative, fantasy, wingdings, etc.Bauhaus 93

The /FADE option causes the OSD window to fade away smoothly when the timeout expires. This fadeout only happens at the timeout. If the OSD window is closed for any other reason — Ctrl-Break was pressed (without /N) or a later OSD /C closes a window opened with /N, or if the plugin is unloaded — the fade will not be performed. /FADE will not work in 256-color mode.


If /N is used, you may specify a timeout of zero, and the OSD window will hang around indefinitely. Use OSD /C to close it. If /N is not specified, the timeout must be nonzero.


/HUE=name lets you specify the color as a W3C color name. Case is not significant, and color names containing ‘gray’ may be spelled using ‘grey’ if you prefer. You can also use hexadecimal color values like /HUE=#E6E6FA or /HUE=#6CF (the value must be either three or six hex digits).


/SAVE=n saves the current text style for use in later OSD commands. The valid range for n is 1 to 4096. Only text appearance settings will be saved; /SAVE does not record behavior settings like the timeout, screen position, fading, and so on. The settings that are saved include:

•  the typeface/FACE
•  the text height/FONT
•  the text weight/BOLD
•  italics and underlining/I and /U
•  the color/RGB, /COLOR, or /HUE
•  drop shadows/SHADOW
•  the alpha value/ALPHA

Use this option to simplify batch files with many OSD commands by eliminating repeated /FACE, /FONT, /COLOR, etc. options. If n is in the range 1 to 100, the text appearance will be saved as a global style: it will affect other instances of TCC, and it will be remembered after you unload the plugin or exit the shell. If n is greater than 100, the new style will only affect the current shell, and it will be lost when you unload the plugin or exit the shell. In most cases you should use private styles, i.e. values greater than 100.

/STYLE=n reloads a style saved by a previous /SAVE=n. N is 1 to 4096. /STYLE=n can be abbreviated to just /n. For example, /101 is equivalent to /STYLE=101.


/C and its variants only close OSD windows created by this plugin in the current instance of TCC; it will not close OSD windows created by TCC’s internal OSD, or by other shells.

You may combine /C, /C=n, /CA, or /FADENOW with text to close old OSD windows while creating a new one. For example, you could use:

osd /n /time=0 /c=5 This is a test.

... to close all OSD windows with ID #5 while creating a new one, also with ID #5. You can use this feature to smoothly replace one OSD with another. Note that this syntax is not compatible with TCC’s internal OSD command.


When displaying an OEM text file with @file, you can use /CP:n to specify the code page. Supported values for /CP include:

437United States (OEM)1250Central Europe
720Arabic (OEM)1251Cyrillic
737Greek (OEM)1252Latin I
775Baltic (OEM)1253Greek
850Multilingual Latin I (OEM)1254Turkish
852Latin II (OEM)1255Hebrew
855Cyrillic (OEM)1256Arabic
857Turkish (OEM)1257Baltic
858Latin I with Euro sign (OEM)1258Vietnam
862Hebrew (OEM)10000Mac OS Roman
866Russian (OEM)20866KOI8-R (Russia)
874Thai (OEM)21866KOI8-U (Ukraine)
A or ANSIthe current Windows code page
O or OEMthe current OEM code page

This option does not affect Unicode text files, including UTF-8. If you do not use /CP:n, the default is the current Windows code page.


Examples:

rem  Using TCC-compatible syntax:
osd /time=3 /hcenter /top /font=54 This is only a test!

rem  This does the same thing, but is shorter:
osd /t:3 /hc /t /h:54 This is only a test!

rem  Add some fancy options:
osd /t:3 /hc /t /h:54 /face:Georgia /k:11 /ds /fade This is only a test!

rem  Create a style #201 ...
osd /face:"Century Gothic" /h:36 /hue:NavajoWhite /shadow /save:201

rem  ... and use it in later calls to OSD:
for /l %i in ( 0, 50, 300 ) osd /n /pos:%i,%i /t:5 /201 This is a test.



OSDIMG — Display a graphical image on-screen.

Syntax:
OSDIMG /N /POS=y,x /TIME=n /SIZE=w,h /ID=n /C /I=n /BG filename

/Ndon’t wait for the OSD window to time out
/POS=y,xset OSD window position; defaults to 0,0
/TIME=nin seconds; the default is 4
/SIZE=w,hset the window size, in pixels (200,0)
/ID=nspecify an ID number; defaults to 998
/Calso close any OSD windows with the same ID
/ALPHA=ntransparency; n is 48 (ghostly) to 255 (opaque)
/FADEfade the window out when the time expires
/LEFT, /RIGHT, /HCENTERoverride any /POS= x value
/TOP, /BOTTOM, /VCENTERoverride any /POS= y value
/I=nicon index
/BGmake the color at the top left corner transparent
filenamethe file containing the image to display

This command displays a graphic in an OSD window. OSDIMG suports many of the same options and abbreviations as OSD, including some not listed in the table above.

The filename may be a BMP, GIF, JPEG, PNG, or TIFF file. You can also extract an icon from an .exe or .dll file; use /I=n if the file contains more then one icon.

/SIZE=w,h sets the size of the OSD window, in pixels. At present, these can range from 16 to 1024, or 0 for ‘unspecified’. If one dimension is unspecified, OSDIMG will scale the image to fit the other, while preventing either dimension from exceeding 1024.

The /C option works differently than in the OSD command. You use it together with a num argument, to display a new graphic and simultaneously close any open OSD windows with the same ID number (998 by default). If you want to close an open OSDIMG window without creating a new one, use OSD /C=998. Note that any old windows are closed after the new one is created — this is to reduce flicker. If for some reason the new window cannot be created, then the /C close operation will not be performed.


Examples:

rem  Show a little enterprise:
osdimg /ctr /size=500 /fade NCC-1701.jpg

ren  How about an icon?
osdimg /size=128 /bg /i=12 "%windir\system32\shell32.dll"


•  Note: This command does not exist in TCC.



PCTBAR — Display an on-screen percentage bar.

Syntax:
PCTBAR /N /POS=y,x /RGB=r,g,b /TIME=n /SIZE=w,h /ID=n /C /COLOR=n /ALPHA=n /FADE num/denum

/Ndon’t wait for the OSD window to time out
/POS=y,xset OSD window position; defaults to 0,0
/RGB=r,g,btext color; the default is 0,255,0 (bright green)
/TIME=nin seconds; the default is 4
/SIZE=w,hset the window size, in pixels (200,40)
/ID=nspecify an ID number; defaults to 999
/Calso close any OSD windows with the same ID
/Valso show the value as a percentage
/COLOR=nspecify color as a TCC color number, 0 - 15
/ALPHA=ntransparency; n is 48 (ghostly) to 255 (opaque)
/FADEfade the window out when the time expires
/LEFT, /RIGHT, /HCENTERoverride any /POS= x value
/TOP, /BOTTOM, /VCENTERoverride any /POS= y value
numthe numerator; required
/denomthe denominator; defaults to 100

This command displays a simple percentage bar on the screen. It might be useful for a sound-volume indicator or a progress bar. PCTBAR supports many of the same options and abbreviations as OSD, including many not listed here. You may use a colon instead of an equals sign as the option-argument separator.

The /C option works differently than in the OSD command. You use it together with a num argument, to display a new percentage bar and simultaneously close any open OSD windows with the same ID number (999 by default). You can use this to create the illusion of animation, replacing an old window with a new one. If you want to close an open PCTBAR window without creating a new one, use OSD /C=999. Note that any old windows are closed after the new one is created — this is to reduce flicker. If for some reason the new window cannot be created, then the /C close operation will not be performed.

/V causes the value to also be shown as a numeric percentage. This option will be ignored if the window is less than 40×16 pixels.


Example:

rem  Display a progress bar at 42% :
pctbar /top /hcenter 42

rem  Animate it:
for /l %i in ( 0, 4, 100 ) do ( pctbar /n /c /t /hc /fade %i & delay /m 100 )


•  Note: This command does not exist in TCC.



New Variables:

_OSD — Returns the number of OSD windows currently open.

Syntax:
%_OSD

If you have opened OSD windows with OSD /N, OSDIMG /N, or PCTBAR /N, you can use this variable to check whether any are still present. Only OSD windows opened by this plugin, in the current shell, will be counted.


•  Note: This variable does not exist in TCC.



_OSDVER — Returns the version of OSD in this plugin.

Syntax:
%_OSDVER


•  Note: This variable does not exist in TCC.



New Function:

@OSD — Returns the number of OSD windows with the given ID currently open.

Syntax:
%@OSD[id]

If you have opened OSD windows with OSD /N, OSDIMG /N, or PCTBAR /N, you can use this function to check whether any are still open. Only OSD windows with the specified ID, opened by this plugin in the current shell, will be counted. If you do not specify an id, the default is zero.


•  Note: This function does not exist in TCC.



Character Escapes:

These may be used in OSD’s text string when you specify /X.

Escape:Expands to:Example:
\bbackspace
\kgrave accent
\nnewline
\ppercent sign
\qdouble quote
\uxxxxUnicode character, up to U+FFFF\u03a3 → Σ
\UxxxxxxxxUnicode character, up to U+10FFFF\U1f63a → 😺
\nnnoctal value, up to 777\101 → A
\xnnnnhexadecimal value, up to FFFF\x41 → A
\#nnnnndecimal value, up to 65535\#65 → A
\\backslash

Startup Message:

This plugin displays an informational line when it initializes. The message will be suppressed in transient or pipe shells. You can disable it for all shells by defining an environment variable named NOLOADMSG, for example:

set /e /u noloadmsg=1

Changes:


VersionDateChanges
1.0.7.22021-11-23Updated mmfiles.cpp to version 1.4.4.0. Tweaks to error messages, and other minor code cleanup.
1.0.7.12021-11-01Help text is now displayed via ShowCmdHelp(). \p now expands to a percent sign.
1.0.72021-10-11Minor improvements to escape expansion: added \k for grave accent, \q for double quote, \# for decimal character values. Also tweaked the handling of malformed escape sequences.
1.0.62021-07-28Changes to drop shadows. Tweaked the version info resource to include the platform (x64 or x86).
1.0.52021-06-19Added /RJ, /LJ, and /X to OSD.
1.0.42021-06-18Increased the drop shadow distance for larger font sizes.
1.0.32021-05-15Made the fade slower and smoother. Reduced the minimum alpha value to 48. Moved the multiline/TextAngle test into MakeOsdWindow().
1.0.22020-12-24Restored the WS_EX_NOACTIVATE style bit to prevent OSD from deactivating the TCC window, as it occasionally does.
1.0.12020-12-21Tweaked the window style bits to make OSD windows “click-throughable”. Switched the filenames; now they are OSD.dll (for 64-bit Take Command) and OSD-x86.dll (for 32-bit).
1.0.02020-02-19First release. Removed /EBCDIC. Documented a few previously undocumented features, and included some demo batch files which hint at others.

Status and Licensing:

This plugin is © Copyright 2021, Charles Dye. Unaltered copies of the binary and documentation files may be freely distributed without restriction. I make no guarantee and give no warranty for its operation. If you find a problem, you can report it in the JP Software support forum.

Download:

You can download the current version of the plugin from http://prospero.unm.edu/dl/osd.zip or ftp://prospero.unm.edu/osd.zip.